NDEFReadingEvent — Schnittstelle · JavaScript-Referenz

Signatur

interface NDEFReadingEvent extends Event

Beschreibung

Ein NDEFReadingEvent wird im reading-Ereignis eines NDEFReader übergeben. Das passiert jedes Mal, wenn ein Gerät einen NFC-Tag mit NDEF-Daten in Reichweite erkennt, nachdem der Scan mit NDEFReader.prototype.scan() gestartet wurde.

Das Ereignis erbt von Event und hat zwei zusätzliche schreibgeschützte Eigenschaften:

serialNumber (string): die Seriennummer des Tags als Bytes in Hexadezimalschreibweise, durch Doppelpunkte getrennt (z. B. "04:a2:3b:1c:5d:80:00"). Ist keine Seriennummer verfügbar, ist der Wert ein leerer String.
message (NDEFMessage): die gelesene NDEF-Nachricht. Ihre Eigenschaft records enthält ein Array von NDEFRecord-Objekten.

Das Ereignis erzeugt man normalerweise nicht selbst. Man verarbeitet es im Handler von reader.addEventListener("reading", …) oder reader.onreading. Den Konstruktor new NDEFReadingEvent(type, init) braucht man vor allem für Tests und Simulationen.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Name des Ereignisses, üblicherweise `"reading"` (nur beim Konstruktor).
$init Pflicht	{ serialNumber?: string, message: NDEFMessageInit, bubbles?: boolean, cancelable?: boolean, composed?: boolean }		Initialisierungsobjekt. `message` ist Pflicht (enthält `records`). `serialNumber` ist standardmäßig `""`.

Rückgabewert

Typ

NDEFReadingEvent

Beschreibung

Beim Konstruktor-Aufruf: ein neues NDEFReadingEvent mit den Eigenschaften serialNumber und message.

Beispiele

NFC-Tag lesen und Text-Datensätze ausgeben

const startScan = async () => {
  if (!('NDEFReader' in window)) {
    console.log('Web NFC wird nicht unterstützt.');
    return;
  }
  const reader = new NDEFReader();
  await reader.scan(); // muss durch eine Nutzeraktion ausgelöst werden

  reader.addEventListener('reading', ({ serialNumber, message }) => {
    console.log(`Tag erkannt: ${serialNumber}`);
    for (const record of message.records) {
      if (record.recordType === 'text') {
        const decoder = new TextDecoder(record.encoding ?? 'utf-8');
        console.log(`Text (${record.lang}): ${decoder.decode(record.data)}`);
      }
    }
  });

  reader.addEventListener('readingerror', () => {
    console.log('Tag konnte nicht gelesen werden.');
  });
};

document.querySelector('#scan').addEventListener('click', startScan);

Tag erkannt: 04:a2:3b:1c:5d:80:00 Text (de): Hallo NFC

URL-Datensatz auswerten und Scan per AbortController beenden

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

reader.onreading = (event) => {
  const urlRecord = event.message.records.find((r) => r.recordType === 'url');
  if (urlRecord) {
    const url = new TextDecoder().decode(urlRecord.data);
    console.log('Gefundene URL:', url);
    controller.abort(); // nach dem ersten Treffer aufhören
  }
};

document.querySelector('#scan').onclick = async () => {
  try {
    await reader.scan({ signal: controller.signal });
  } catch (err) {
    console.log(`Scan fehlgeschlagen: ${err.name}`);
  }
};

Gefundene URL: https://programmierung.net

Ereignis für Tests selbst erzeugen

const event = new NDEFReadingEvent('reading', {
  serialNumber: '04:11:22:33:44:55:66',
  message: {
    records: [{ recordType: 'text', data: 'Testdaten', lang: 'de' }]
  }
});

console.log(event.type, event.serialNumber);
console.log(event.message.records[0].recordType);

reading 04:11:22:33:44:55:66 text

// Wichtig · Fallstricke

Kompatibilität: Web NFC ist experimentell und funktioniert nur in Chrome für Android (ab Version 89) auf Geräten mit NFC-Hardware. Desktop-Browser, Firefox und Safari unterstützen die API nicht. Deshalb vorher immer mit 'NDEFReader' in window prüfen, ob sie verfügbar ist.
Sicherer Kontext und Nutzeraktion: Die API ist nur über HTTPS verfügbar und nur im obersten Dokument, nicht in Iframes. scan() braucht beim ersten Aufruf eine Nutzeraktion (z. B. einen Klick) und die Berechtigung "nfc". Außerdem kommen Ereignisse nur an, solange die Seite sichtbar ist.
Daten dekodieren: record.data ist ein DataView. Text muss man mit TextDecoder selbst dekodieren und dabei record.encoding beachten. Bei eingebetteten Datensätzen, etwa vom Typ "smart-poster", liefert record.toRecords() die inneren Datensätze.
Seriennummer nicht als Sicherheitsmerkmal nutzen: serialNumber kann leer sein und lässt sich fälschen. Für Authentifizierung ist sie ungeeignet.
Ist ein Tag leer oder nicht NDEF-formatiert, wird statt reading das Ereignis readingerror ausgelöst. Einen Handler dafür sollte man immer registrieren.

Siehe auch

NDEFReader NDEFReader.prototype.scan() NDEFMessage NDEFRecord TextDecoder