BarcodeDetector.detect() — Methode · JavaScript-Referenz

Signatur

BarcodeDetector.prototype.detect(imageBitmapSource)

Beschreibung

Die Methode detect() einer BarcodeDetector-Instanz analysiert eine Bildquelle und erkennt darin einen oder mehrere Barcodes (z. B. QR-Code, EAN-13, Code 128, Data Matrix). Welche Formate gesucht werden, legt der Konstruktor über die Option formats fest. Das zurückgegebene Promise wird mit einem Array von DetectedBarcode-Objekten erfüllt – ein leeres Array bedeutet, dass nichts gefunden wurde.

Jedes Ergebnisobjekt enthält rawValue (den dekodierten Inhalt als String), format (z. B. "qr_code"), boundingBox (ein DOMRectReadOnly) sowie cornerPoints (vier Eckpunkte, im Uhrzeigersinn ab oben links). Damit lassen sich Codes nicht nur auslesen, sondern auch im Bild markieren.

Typische Einsatzfälle sind Scanner in Web-Apps: Kamerabild per getUserMedia() in ein <video> leiten und regelmäßig – etwa per requestAnimationFrame() – detect() aufrufen. Da die Erkennung auf native Plattformbibliotheken zurückgreift, ist sie deutlich schneller als reine JavaScript-Bibliotheken, aber eben nicht überall verfügbar.

Parameter

Name	Typ	Default	Beschreibung
$imageBitmapSource Pflicht	HTMLImageElement \| SVGImageElement \| HTMLVideoElement \| HTMLCanvasElement \| OffscreenCanvas \| ImageBitmap \| ImageData \| VideoFrame \| Blob		Die zu analysierende Bildquelle. Bilder müssen vollständig geladen sein, Videos müssen einen aktuellen Frame haben (`readyState` ≥ 2).

Rückgabewert

Typ

Promise<DetectedBarcode[]>

Beschreibung

Ein Promise, das mit einem Array von DetectedBarcode-Objekten (rawValue, format, boundingBox, cornerPoints) erfüllt wird. Wird mit einem DOMException abgelehnt, wenn die Quelle ungültig oder nicht lesbar ist (z. B. SecurityError bei ursprungsfremden Bildern ohne CORS, InvalidStateError bei nicht geladenen Bildern).

Beispiele

QR-Code aus einem Bild auslesen

const img = document.querySelector('#ticket');
await img.decode(); // sicherstellen, dass das Bild geladen ist

const detector = new BarcodeDetector({ formats: ['qr_code'] });
const barcodes = await detector.detect(img);

if (barcodes.length === 0) {
  console.log('Kein QR-Code gefunden');
} else {
  barcodes.forEach(({ format, rawValue }) => console.log(format, rawValue));
}

qr_code https://example.com/ticket/4711

Live-Scanner mit Kamera und Feature-Erkennung

const startScanner = async (video) => {
  if (!('BarcodeDetector' in window)) {
    throw new Error('BarcodeDetector wird nicht unterstützt');
  }
  const supported = await BarcodeDetector.getSupportedFormats();
  const formats = ['ean_13', 'qr_code', 'code_128'].filter((f) => supported.includes(f));
  const detector = new BarcodeDetector({ formats });

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

  const scan = async () => {
    try {
      const [code] = await detector.detect(video);
      if (code) {
        console.log(`Gefunden (${code.format}): ${code.rawValue}`);
        video.srcObject.getTracks().forEach((t) => t.stop());
        return;
      }
    } catch (err) {
      console.error('Erkennung fehlgeschlagen:', err);
    }
    requestAnimationFrame(scan);
  };
  scan();
};

startScanner(document.querySelector('video'));

Gefunden (ean_13): 4006381333931

Erkannte Barcodes auf einem Canvas markieren

const canvas = document.querySelector('canvas');
const ctx = canvas.getContext('2d');
const detector = new BarcodeDetector();

const barcodes = await detector.detect(canvas);
ctx.strokeStyle = 'lime';
ctx.lineWidth = 3;

for (const { boundingBox, rawValue } of barcodes) {
  const { x, y, width, height } = boundingBox;
  ctx.strokeRect(x, y, width, height);
  ctx.fillText(rawValue, x, y - 4);
}
console.log(`${barcodes.length} Barcode(s) markiert`);

2 Barcode(s) markiert

// Wichtig · Fallstricke

Kompatibilität: Die Shape Detection API ist experimentell. Chromium-Browser unterstützen sie vor allem auf Android, macOS und ChromeOS; unter Windows/Linux fehlt sie meist. Firefox unterstützt sie nicht. Immer per 'BarcodeDetector' in window prüfen und ggf. auf eine Bibliothek (z. B. ZXing) oder ein Polyfill ausweichen.
Sicherer Kontext: Nur über HTTPS (bzw. localhost) verfügbar; der Kamerazugriff erfordert zusätzlich die Zustimmung des Nutzers.
Formate prüfen: Nicht jede Plattform unterstützt jedes Format. Mit BarcodeDetector.getSupportedFormats() abfragen – nicht unterstützte Formate im Konstruktor führen zu einem TypeError.
CORS: Ursprungsfremde Bilder ohne passende CORS-Header („tainted“) führen zu einem SecurityError. crossorigin="anonymous" setzen.
Performance: Nicht in einer engen Schleife ohne Pause aufrufen. Warten, bis das vorherige Promise erfüllt ist, und ggf. drosseln (z. B. alle 200 ms), um CPU und Akku zu schonen.
Sicherheit: rawValue ist unkontrollierte Eingabe. Nie ungeprüft per innerHTML einfügen oder als URL öffnen – Schutz vor XSS und Phishing-Links.

Siehe auch

BarcodeDetector.getSupportedFormats() LanguageDetector.detect() IdleDetector.start() LanguageDetector.destroy() NodeIterator.detach()