new BarcodeDetector() — Methode · JavaScript-Referenz

Signatur

new BarcodeDetector(options)

Beschreibung

Der Konstruktor BarcodeDetector() gehört zur Shape Detection API. Er liefert einen Detektor, dessen Methode detect() Barcodes in einer Bildquelle findet, etwa in einem <img>, <video>, <canvas>, ImageBitmap, ImageData oder Blob. Die Erkennung übernimmt die Plattform selbst, meist hardwarebeschleunigt. Eine eigene JavaScript-Bibliothek zum Dekodieren braucht man deshalb nicht.

Über das optionale Objekt options legt man mit formats fest, nach welchen Barcode-Formaten gesucht wird. Je weniger Formate man angibt, desto schneller und zuverlässiger läuft die Erkennung. Welche Formate das aktuelle Gerät unterstützt, verrät die statische Methode BarcodeDetector.getSupportedFormats().

Typische Einsatzfälle sind QR-Code-Scanner in Web-Apps, das Scannen von Artikelnummern (EAN/UPC) im Handel oder Lager und das Auslesen von Tickets oder Bordkarten (PDF417, Aztec). Den Konstruktor ruft man in der Regel nur einmal auf und verwendet die Instanz dann für viele detect()-Aufrufe weiter.

Parameter

Name	Typ	Default	Beschreibung
$options	object	{}	Optionales Konfigurationsobjekt.
$options.formats	string[]	alle von der Plattform unterstützten Formate	Liste der gesuchten Barcode-Formate, z. B. `"qr_code"`, `"ean_13"`, `"ean_8"`, `"upc_a"`, `"upc_e"`, `"code_128"`, `"code_39"`, `"code_93"`, `"codabar"`, `"itf"`, `"data_matrix"`, `"aztec"`, `"pdf417"`. Ein leeres Array oder ein unbekanntes Format löst einen `TypeError` aus.

Rückgabewert

Typ

BarcodeDetector

Beschreibung

Eine neue BarcodeDetector-Instanz. Ihre Methode detect(image) liefert ein Promise<DetectedBarcode[]>. Jeder Eintrag enthält rawValue, format, boundingBox und cornerPoints.

Beispiele

Unterstützung prüfen und Detektor für QR-Codes anlegen

const createQrDetector = async () => {
  if (!('BarcodeDetector' in globalThis)) {
    console.warn('BarcodeDetector wird nicht unterstützt');
    return null;
  }
  const supported = await BarcodeDetector.getSupportedFormats();
  console.log('Unterstützte Formate:', supported);

  if (!supported.includes('qr_code')) return null;
  return new BarcodeDetector({ formats: ['qr_code'] });
};

const detector = await createQrDetector();
console.log(detector);

Unterstützte Formate: ['aztec', 'code_128', 'ean_13', 'qr_code', ...] BarcodeDetector {}

Barcode in einem Bild erkennen

const detector = new BarcodeDetector({ formats: ['ean_13', 'qr_code'] });
const img = document.querySelector('#produktfoto');
await img.decode(); // sicherstellen, dass das Bild geladen ist

try {
  const barcodes = await detector.detect(img);
  for (const { format, rawValue, boundingBox } of barcodes) {
    console.log(`${format}: ${rawValue} bei x=${boundingBox.x}`);
  }
  if (barcodes.length === 0) console.log('Kein Barcode gefunden');
} catch (err) {
  console.error('Erkennung fehlgeschlagen:', err);
}

ean_13: 4006381333931 bei x=112

Live-Scanner mit der Kamera

const video = document.querySelector('video');
const stream = await navigator.mediaDevices.getUserMedia({
  video: { facingMode: 'environment' }
});
video.srcObject = stream;
await video.play();

const detector = new BarcodeDetector({ formats: ['qr_code'] });

const scan = async () => {
  const [code] = await detector.detect(video);
  if (code) {
    console.log('Gescannt:', code.rawValue);
    stream.getTracks().forEach((t) => t.stop()); // Kamera freigeben
    return;
  }
  requestAnimationFrame(scan);
};
scan();

Gescannt: https://programmierung.net

// Wichtig · Fallstricke

Kompatibilität: Die API ist experimentell. Chromium-Browser (Chrome, Edge, Opera) unterstützen sie vor allem auf Android, macOS und ChromeOS. Firefox und Safari bieten sie nicht an (Stand 2024). Unter Windows und Linux fehlt die Unterstützung teilweise oder ganz. Prüfe deshalb immer mit 'BarcodeDetector' in globalThis und halte eine Ausweichlösung bereit, etwa eine Bibliothek wie ZXing oder ein Polyfill.
Die API funktioniert nur in einem sicheren Kontext (HTTPS). Sie steht auch in Web Workern zur Verfügung.
Übergibt man formats als leeres Array oder mit einem unbekannten Wert, löst der Konstruktor einen TypeError aus. Nicht unterstützte, aber bekannte Formate werden auf manchen Plattformen einfach ignoriert. Gleiche die Liste deshalb vorher mit getSupportedFormats() ab.
getSupportedFormats() kann ein leeres Array liefern. Dann existiert der Konstruktor zwar, erkennt aber nichts.
Performance: Rufe detect() nicht öfter auf, als nötig ist, und warte jeweils auf das Promise, statt Aufrufe parallel zu stapeln. Lege die Instanz nur einmal an und verwende sie weiter.
Sicherheit: rawValue ist eine unvertrauenswürdige Eingabe. Füge den Wert nicht ungeprüft per innerHTML ein (XSS-Gefahr) und öffne URLs aus QR-Codes nicht automatisch.
Bilder aus fremden Quellen ohne CORS-Freigabe (sogenannter „tainted“ Canvas) führen zu einem SecurityError.

Siehe auch

new CustomElementRegistry() new IdleDetector() new Accelerometer() new AudioDecoder() new BlobEvent()