NDEFReader: readingerror — Ereignis · JavaScript-Referenz

Signatur

ndefReader.addEventListener("readingerror", handler)

Beschreibung

Das Ereignis readingerror gehört zur Web-NFC-API. Der Browser löst es an einer NDEFReader-Instanz aus, wenn nach dem Aufruf von scan() ein NFC-Tag erkannt wird, dessen Daten sich aber nicht lesen lassen. Typische Gründe sind Tags, die nicht NDEF-formatiert sind, beschädigte oder unvollständige Daten und ein Tag, der zu früh aus der Reichweite genommen wurde.

Du kannst den Handler auf zwei Arten registrieren: mit ndefReader.addEventListener("readingerror", handler) oder über die Eigenschaft ndefReader.onreadingerror = handler. Das übergebene Objekt ist ein einfaches Event. Es enthält keine genauere Fehlerursache. In der Praxis zeigst du deshalb meist einen allgemeinen Hinweis an, zum Beispiel „Tag konnte nicht gelesen werden, bitte erneut versuchen“.

Wichtig ist die Abgrenzung: readingerror betrifft nur Fehler beim Lesen eines erkannten Tags. Fehler beim Starten des Scans (fehlende Berechtigung, NFC ausgeschaltet, keine Hardware) bekommst du nicht über dieses Ereignis. Sie kommen als Ablehnung des Promise, das scan() zurückgibt, meist als NotAllowedError oder NotSupportedError. Erfolgreiche Lesevorgänge meldet das Ereignis reading.

Beispiele

Lesefehler mit addEventListener behandeln

const scanButton = document.querySelector('#scan');
const status = document.querySelector('#status');

scanButton.addEventListener('click', async () => {
  if (!('NDEFReader' in window)) {
    status.textContent = 'Web NFC wird nicht unterstützt.';
    return;
  }

  const reader = new NDEFReader();

  reader.addEventListener('readingerror', () => {
    status.textContent = 'Tag erkannt, aber nicht lesbar. Bitte erneut an das Gerät halten.';
  });

  reader.addEventListener('reading', ({ serialNumber, message }) => {
    status.textContent = `Tag ${serialNumber}: ${message.records.length} Datensätze`;
  });

  try {
    await reader.scan(); // muss durch eine Nutzergeste ausgelöst werden
    status.textContent = 'Scan läuft – Tag an das Gerät halten …';
  } catch (err) {
    // Berechtigung verweigert, NFC aus usw. – nicht über readingerror!
    status.textContent = `Scan konnte nicht starten: ${err.name}`;
  }
});

Tag erkannt, aber nicht lesbar. Bitte erneut an das Gerät halten.

Über die on-Property und mit Fehlerzähler

const reader = new NDEFReader();
let fehlversuche = 0;

reader.onreadingerror = (event) => {
  fehlversuche += 1;
  console.warn(`Lesefehler #${fehlversuche}`, event.type);
  if (fehlversuche >= 3) {
    console.warn('Tag ist vermutlich nicht NDEF-formatiert.');
  }
};

reader.onreading = (event) => {
  fehlversuche = 0;
  console.log('Gelesen:', event.serialNumber);
};

document.querySelector('#scan').onclick = () => reader.scan().catch(console.error);

Lesefehler #1 readingerror Lesefehler #2 readingerror Lesefehler #3 readingerror Tag ist vermutlich nicht NDEF-formatiert.

Listener und Scan per AbortController beenden

const controller = new AbortController();
const reader = new NDEFReader();

const onError = () => console.log('Lesen fehlgeschlagen');
reader.addEventListener('readingerror', onError, { signal: controller.signal });

document.querySelector('#scan').addEventListener('click', async () => {
  await reader.scan({ signal: controller.signal });
  // Scan nach 10 Sekunden beenden und Listener entfernen
  setTimeout(() => {
    controller.abort();
    console.log('Scan beendet');
  }, 10_000);
});

// Alternativ ohne Signal:
// reader.removeEventListener('readingerror', onError);

Scan beendet

// Wichtig · Fallstricke

Kompatibilität: Web NFC ist experimentell und läuft nur in Chrome für Android (ab 89). Firefox, Safari/iOS und Desktop-Browser unterstützen die API nicht. Prüfe vorher mit 'NDEFReader' in window, ob sie vorhanden ist.
Die API steht nur in einem sicheren Kontext (HTTPS) und nur im Hauptframe der obersten Ebene zur Verfügung. Der erste Aufruf von scan() braucht eine Nutzergeste und die Berechtigung "nfc".
readingerror liefert keine Fehlerursache. Fehler beim Start (Berechtigung, NFC deaktiviert) fängst du über das catch des scan()-Promise ab.
Registriere die Listener vor dem Aufruf von scan(), sonst verpasst du womöglich frühe Ereignisse.
Ist die Seite nicht sichtbar (Tab im Hintergrund, Bildschirm aus), unterbricht der Browser das Scannen. Dann kommen keine Ereignisse an.

Siehe auch

NDEFReader NDEFReader: reading NDEFReader.prototype.scan() NDEFReader.prototype.write() NDEFReadingEvent BroadcastChannel: messageerror