NDEFMessage — Schnittstelle · JavaScript-Referenz

Signatur

interface NDEFMessage

Beschreibung

NDEFMessage ist der Datencontainer der Web NFC API. Eine NDEF-Nachricht (NFC Data Exchange Format) besteht aus einem oder mehreren Datensätzen. Die schreibgeschützte Eigenschaft records liefert diese als Array von NDEFRecord-Objekten. Jeder Datensatz hat einen recordType (z. B. "text", "url", "mime") und eine Nutzlast in data (ein DataView).

Meistens erzeugt man NDEFMessage-Objekte nicht selbst. Man bekommt sie beim Lesen über das reading-Ereignis von NDEFReader: Die Eigenschaft event.message des NDEFReadingEvent ist eine NDEFMessage. Zum Schreiben übergibt man NDEFReader.write() meist einfach einen String oder ein einfaches Objekt der Form { records: [...] }. Intern wird daraus eine NDEFMessage gebaut.

Mit dem Konstruktor new NDEFMessage(messageInit) kann man eine Nachricht auch ausdrücklich anlegen, etwa um sie vorzubereiten oder zu prüfen. messageInit ist ein Objekt mit dem Pflichtfeld records: ein Array von Initialisierungsobjekten für Datensätze, jeweils mit recordType, data und optional mediaType, id, encoding und lang.

Parameter

Name	Typ	Default	Beschreibung
$messageInit Pflicht	{ records: Array<NDEFRecordInit> }		Nur für den Konstruktor: Objekt mit dem Feld `records`. Jeder Eintrag enthält `recordType` (Pflicht, z. B. `"text"`, `"url"`, `"mime"`, `"empty"`, `"smart-poster"`, `"absolute-url"` oder einen externen Typ) sowie optional `data`, `mediaType`, `id`, `encoding` und `lang`.

Rückgabewert

Typ

NDEFMessage

Beschreibung

Konstruktor: eine neue NDEFMessage-Instanz. Die Eigenschaft records ist ein schreibgeschütztes Array (FrozenArray<NDEFRecord>) mit den Datensätzen der Nachricht.

Beispiele

Nachricht beim Lesen eines Tags auswerten

const scanTag = async () => {
  const reader = new NDEFReader();
  await reader.scan(); // muss durch eine Nutzeraktion ausgelöst werden

  reader.addEventListener('reading', ({ message, serialNumber }) => {
    console.log(`Tag ${serialNumber}: ${message.records.length} Datensatz/Datensätze`);
    for (const record of message.records) {
      if (record.recordType === 'text') {
        const decoder = new TextDecoder(record.encoding ?? 'utf-8');
        console.log('Text:', decoder.decode(record.data));
      } else if (record.recordType === 'url') {
        console.log('URL:', new TextDecoder().decode(record.data));
      } else {
        console.log('Anderer Typ:', record.recordType, record.mediaType);
      }
    }
  });
};

document.querySelector('#scan').addEventListener('click', () => scanTag().catch(console.error));

Tag 04:a2:3b:1c:5d:80:00: 1 Datensatz/Datensätze Text: Hallo NFC

NDEFMessage per Konstruktor erzeugen

const message = new NDEFMessage({
  records: [
    { recordType: 'text', data: 'Willkommen im Büro', lang: 'de' },
    { recordType: 'url', data: 'https://programmierung.net' }
  ]
});

console.log(message.records.length);
console.log(message.records.map((r) => r.recordType));

2 ["text", "url"]

Mehrere Datensätze auf ein Tag schreiben

const writeTag = async () => {
  const writer = new NDEFReader();
  const payload = {
    records: [
      { recordType: 'url', data: 'https://example.com/raum/42' },
      {
        recordType: 'mime',
        mediaType: 'application/json',
        data: new TextEncoder().encode(JSON.stringify({ raum: 42, etage: 3 }))
      }
    ]
  };
  try {
    await writer.write(payload, { overwrite: true });
    console.log('Tag erfolgreich beschrieben');
  } catch (err) {
    console.error('Schreiben fehlgeschlagen:', err.name, err.message);
  }
};

document.querySelector('#write').addEventListener('click', writeTag);

Tag erfolgreich beschrieben

// Wichtig · Fallstricke

Kompatibilität: Web NFC ist experimentell. Es wird derzeit nur von Chrome für Android (ab Version 89) unterstützt, nicht von Desktop-Browsern, Firefox oder Safari/iOS. Prüfen Sie die Verfügbarkeit mit 'NDEFReader' in window.
Sicherer Kontext: Die API funktioniert nur über HTTPS und in Frames der obersten Ebene. scan() und write() brauchen eine Nutzeraktion und die Berechtigung "nfc". Außerdem muss die Seite sichtbar sein.
record.data ist ein DataView, kein String. Die Nutzlast muss man mit TextDecoder dekodieren. Bei Text-Datensätzen sollte man dabei record.encoding beachten.
Das Array records ist eingefroren. Um eine Nachricht zu ändern, legt man eine neue an.
Den Inhalt von Tags sollte man als nicht vertrauenswürdige Eingabe behandeln. Gelesene URLs oder Texte also nie ungeprüft per innerHTML einfügen oder aufrufen (Gefahr von XSS und Phishing).
Die Kapazität von NFC-Tags ist klein, oft nur wenige hundert Byte. Zu große Nachrichten lassen write() mit einem Fehler scheitern.

Siehe auch

NDEFReader NDEFRecord IDBKeyRange AudioSession CSSScale