new NDEFReadingEvent() — Methode · JavaScript-Referenz

Signatur

new NDEFReadingEvent(type, options)

Beschreibung

Der Konstruktor NDEFReadingEvent() gehört zur Web-NFC-API. Er erstellt ein Ereignisobjekt, wie es der Browser beim Event reading eines NDEFReader auslöst, sobald ein NFC-Tag in Reichweite kommt. Das Objekt enthält die Seriennummer des Tags (serialNumber) und die gelesene NDEF-Nachricht (message) als NDEFMessage.

Im Normalfall ruft man den Konstruktor nicht selbst auf – der Browser erzeugt die Events automatisch. Sinnvoll ist der manuelle Aufruf vor allem für Tests, Mocks und Simulationen: Man kann damit ein synthetisches Lese-Ereignis erzeugen und per dispatchEvent() an einen eigenen EventTarget oder einen NDEFReader senden, um die Auswertelogik ohne echtes NFC-Tag zu prüfen.

Das Pflichtfeld options.message wird intern in ein NDEFMessage-Objekt umgewandelt; es muss daher ein Objekt mit einem records-Array sein. Fehlt es, wirft der Konstruktor einen TypeError.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Name des Ereignisses, üblicherweise `"reading"` (Groß-/Kleinschreibung beachten).
$options Pflicht	object		Initialisierungsobjekt. Erbt die `EventInit`-Felder (`bubbles`, `cancelable`, `composed`) und ergänzt: `serialNumber` (`string`, optional, Standard `""`): Seriennummer des Tags, z. B. `"04:a2:3b:1c"`. `message` (`object`, Pflicht): `NDEFMessageInit` mit einem Array `records` aus Datensätzen (`recordType`, `data`, optional `mediaType`, `encoding`, `lang`, `id`).

Rückgabewert

Typ

NDEFReadingEvent

Beschreibung

Ein neues NDEFReadingEvent mit den Eigenschaften serialNumber und message (NDEFMessage).

Beispiele

Synthetisches Lese-Ereignis erzeugen

const event = new NDEFReadingEvent('reading', {
  serialNumber: '04:a2:3b:1c:5d:80:00',
  message: {
    records: [{ recordType: 'text', data: 'Hallo NFC' }]
  }
});

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

reading 04:a2:3b:1c:5d:80:00 text

Auswertelogik ohne echtes Tag testen

const decoder = new TextDecoder();

const handleReading = ({ serialNumber, message }) => {
  for (const record of message.records) {
    if (record.recordType === 'text') {
      console.log(`Tag ${serialNumber}: ${decoder.decode(record.data)}`);
    }
  }
};

// Mock-Ziel statt echtem NDEFReader
const mockReader = new EventTarget();
mockReader.addEventListener('reading', handleReading);

mockReader.dispatchEvent(new NDEFReadingEvent('reading', {
  serialNumber: '04:11:22:33',
  message: { records: [{ recordType: 'text', data: 'Raum 204' }] }
}));

Tag 04:11:22:33: Raum 204

Echte Lesung mit NDEFReader (Vergleich)

const scanTag = async () => {
  if (!('NDEFReader' in window)) {
    console.warn('Web NFC wird nicht unterstützt.');
    return;
  }
  const reader = new NDEFReader();
  await reader.scan(); // erfordert Nutzergeste + Berechtigung
  reader.onreading = (event) => {
    // event ist ein vom Browser erzeugtes NDEFReadingEvent
    console.log('Seriennummer:', event.serialNumber);
    console.log('Datensätze:', event.message.records.length);
  };
  reader.onreadingerror = () => console.error('Tag nicht lesbar.');
};

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

// Wichtig · Fallstricke

Sehr eingeschränkte Unterstützung: Web NFC gibt es nur in Chrome/Edge für Android (ab 89). Desktop-Browser, Firefox und Safari (auch iOS) unterstützen es nicht. Vorher mit 'NDEFReadingEvent' in window prüfen.
Die API ist nur in sicheren Kontexten (HTTPS) und im obersten Browsing-Kontext verfügbar, nicht in Cross-Origin-iframes.
Fehlt options.message oder ist records ungültig (z. B. falscher data-Typ für den recordType), wirft der Konstruktor einen TypeError.
Selbst erzeugte Events haben isTrusted === false. Sie lösen keine echte Hardware-Interaktion aus und dienen nur Tests oder interner Weiterleitung.
serialNumber ist nicht fälschungssicher und darf nicht zur Authentifizierung verwendet werden.

Siehe auch

NDEFReadingEvent NDEFReader NDEFReader.prototype.scan() NDEFMessage NDEFRecord new AudioProcessingEvent()