new NDEFMessage() — Methode · JavaScript-Referenz

Signatur

new NDEFMessage(messageInit)

Beschreibung

Der Konstruktor NDEFMessage() gehört zur Web NFC API. Er erzeugt eine NDEF-Nachricht (NFC Data Exchange Format), die aus einem oder mehreren Datensätzen besteht. Jeder Eintrag im Array records wird dabei in ein NDEFRecord-Objekt umgewandelt, das über die schreibgeschützte Eigenschaft message.records abrufbar ist.

In der Praxis bekommst du NDEFMessage-Objekte meist fertig geliefert, nämlich über event.message im reading-Ereignis eines NDEFReader. Den Konstruktor brauchst du vor allem, wenn du Nachrichten selbst zusammenbauen, prüfen oder in Tests nachbilden willst, etwa Text-, URL-, MIME- oder anwendungsspezifische Datensätze ("example.com:typ").

Beim Erzeugen wird jeder Datensatz geprüft. Stimmen recordType und data nicht zusammen (z. B. ein "url"-Datensatz ohne String als Daten) oder ist die Liste leer, wirft der Konstruktor einen TypeError. Zum eigentlichen Schreiben auf ein Tag übergibt man NDEFReader.prototype.write() dasselbe Init-Objekt.

Parameter

Name	Typ	Default	Beschreibung
$messageInit Pflicht	Object		Objekt mit der Eigenschaft `records`: einem Array aus Datensatz-Beschreibungen (`NDEFRecordInit`).
$messageInit.records Pflicht	Array<Object>		Liste der Datensätze. Jeder Eintrag kann folgende Felder haben: `recordType` (Pflicht, z. B. `"text"`, `"url"`, `"mime"`, `"absolute-url"`, `"smart-poster"`, `"empty"`, `"unknown"` oder ein externer Typ wie `"example.com:a"`), `data` (String, `ArrayBuffer`, `TypedArray`, `DataView` oder ein verschachteltes Nachrichten-Init-Objekt), `mediaType` (MIME-Typ bei `"mime"`), `id`, `encoding` und `lang` (bei `"text"`).

Rückgabewert

Typ

NDEFMessage

Beschreibung

Ein neues NDEFMessage-Objekt. Seine Eigenschaft records enthält ein eingefrorenes Array aus NDEFRecord-Objekten.

Beispiele

Nachricht mit Text- und URL-Datensatz erzeugen

const message = new NDEFMessage({
  records: [
    { recordType: "text", data: "Hallo Welt", lang: "de" },
    { recordType: "url", data: "https://programmierung.net" }
  ]
});

for (const record of message.records) {
  console.log(record.recordType, record.lang ?? "-");
}

text de url -

JSON als MIME-Datensatz einpacken und wieder auslesen

const payload = { raum: "B12", sensor: 7 };

const message = new NDEFMessage({
  records: [{
    recordType: "mime",
    mediaType: "application/json",
    data: new TextEncoder().encode(JSON.stringify(payload))
  }]
});

const [record] = message.records;
// record.data ist eine DataView
const json = JSON.parse(new TextDecoder().decode(record.data));
console.log(record.mediaType, json.raum);

application/json B12

Empfangene Nachricht im reading-Ereignis auswerten und Tag beschreiben

const nfcTagVerarbeiten = async () => {
  if (!("NDEFReader" in window)) {
    console.warn("Web NFC wird nicht unterstützt.");
    return;
  }

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

  reader.addEventListener("reading", async ({ message, serialNumber }) => {
    // message ist ein NDEFMessage-Objekt
    for (const record of message.records) {
      if (record.recordType === "text") {
        const text = new TextDecoder(record.encoding).decode(record.data);
        console.log(`Tag ${serialNumber}: ${text}`);
      }
    }

    // Neue Nachricht schreiben (write() nimmt das Init-Objekt entgegen)
    await reader.write({
      records: [{ recordType: "text", data: `Gelesen am ${new Date().toLocaleString("de-DE")}` }]
    });
  });
};

document.querySelector("#scan").addEventListener("click", nfcTagVerarbeiten);

Tag 04:a2:3f:1b:5c:80:00: Hallo Welt

// Wichtig · Fallstricke

Kompatibilität: Web NFC ist experimentell und praktisch nur in Chrome für Android (ab 89) verfügbar. Desktop-Browser, Firefox und Safari (inkl. iOS) unterstützen die API nicht. Prüfe das vorher mit \"NDEFMessage\" in window.
Die API gibt es nur im sicheren Kontext (HTTPS) und nur im obersten Dokument (Top-Level), nicht in iframes. Lesen und Schreiben brauchen eine Nutzeraktion und die NFC-Berechtigung.
Eine leere records-Liste oder unpassende Daten (z. B. \"url\" mit Binärdaten, \"mime\" mit String) lösen einen TypeError aus. Setze den Aufruf deshalb in try…catch.
record.data ist immer eine DataView. Zum Auslesen brauchst du TextDecoder oder typisierte Arrays. Datensätze vom Typ \"empty\" haben data === null.
Das records-Array ist eingefroren. Du kannst also keine Datensätze nachträglich hinzufügen, sondern musst eine neue Nachricht erzeugen.
NFC-Tags haben oft nur wenige hundert Bytes Speicher. Große Nutzdaten führen beim Schreiben zu Fehlern.

Siehe auch

NDEFMessage NDEFMessage.records NDEFRecord NDEFReader NDEFReader.prototype.write() NDEFReader.prototype.scan()