new NDEFRecord() — Methode · JavaScript-Referenz

Signatur

new NDEFRecord(options)

Beschreibung

Der Konstruktor NDEFRecord() gehört zur Web NFC API und erzeugt einen einzelnen NDEF-Datensatz (NFC Data Exchange Format). So ein Datensatz besteht aus einem Typ (recordType), optional einem MIME-Typ, einer ID, einer Sprach- und Kodierungsangabe sowie den eigentlichen Nutzdaten (data).

In der Praxis brauchst du den Konstruktor selten direkt: NDEFReader.prototype.write() nimmt auch einfache Objekte im Format NDEFRecordInit an und wandelt sie intern in NDEFRecord-Instanzen um. Sinnvoll ist der Konstruktor, wenn du Datensätze vorab prüfen, wiederverwenden oder als Unterdatensätze einer verschachtelten Nachricht ("smart-poster" oder externe Typen) aufbauen willst. Ist die Kombination aus Typ und Daten ungültig, wirft der Konstruktor sofort einen TypeError und nicht erst beim Schreiben.

Unterstützte recordType-Werte sind "empty", "text", "url", "absolute-url", "mime", "smart-poster" sowie externe Typen im Format "domain.tld:typ" und lokale Typen, die mit ":" beginnen (nur innerhalb verschachtelter Datensätze erlaubt).

Parameter

Name	Typ	Default	Beschreibung
$options Pflicht	NDEFRecordInit (Object)		Objekt, das den Datensatz beschreibt. Enthält die folgenden Eigenschaften.
$options.recordType Pflicht	string		Art des Datensatzes: `"empty"`, `"text"`, `"url"`, `"absolute-url"`, `"mime"`, `"smart-poster"`, ein externer Typ (`"example.com:foo"`) oder ein lokaler Typ (`":act"`).
$options.data	string \| BufferSource \| NDEFMessageInit		Nutzdaten. Bei `"text"`/`"url"` ein String, bei `"mime"` ein `ArrayBuffer`/`TypedArray`/`DataView`, bei `"smart-poster"` und externen Typen ggf. ein Objekt mit `records`-Array. Bei `"empty"` weglassen.
$options.mediaType	string		MIME-Typ der Daten, nur bei `recordType: "mime"` erlaubt, z. B. `"application/json"`.
$options.id	string		Optionale Kennung des Datensatzes (als URL-Zeichenkette interpretiert).
$options.encoding	string	"utf-8"	Zeichenkodierung bei `"text"`-Datensätzen: `"utf-8"`, `"utf-16"`, `"utf-16le"` oder `"utf-16be"`.
$options.lang	string	Sprache des Dokuments bzw. "en"	BCP-47-Sprachcode für `"text"`-Datensätze, z. B. `"de-DE"`.

Rückgabewert

Typ

NDEFRecord

Beschreibung

Ein neues NDEFRecord-Objekt mit den schreibgeschützten Eigenschaften recordType, mediaType, id, data (DataView), encoding und lang.

Beispiele

Text-Datensatz erzeugen und untersuchen

const record = new NDEFRecord({
  recordType: 'text',
  data: 'Hallo NFC!',
  lang: 'de-DE'
});

console.log(record.recordType, record.lang, record.encoding);
// data ist ein DataView – zum Lesen dekodieren
console.log(new TextDecoder(record.encoding).decode(record.data));

text de-DE utf-8 Hallo NFC!

URL- und JSON-Datensatz auf ein Tag schreiben

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

  const urlRecord = new NDEFRecord({
    recordType: 'url',
    data: 'https://programmierung.net'
  });

  const jsonRecord = new NDEFRecord({
    recordType: 'mime',
    mediaType: 'application/json',
    data: new TextEncoder().encode(JSON.stringify({ raum: 'B204', etage: 2 }))
  });

  try {
    const reader = new NDEFReader();
    await reader.write({ records: [urlRecord, jsonRecord] });
    console.log('Tag erfolgreich beschrieben');
  } catch (err) {
    console.error('Schreiben fehlgeschlagen:', err.name, err.message);
  }
};

// Muss durch eine Nutzergeste ausgelöst werden
document.querySelector('#schreiben').addEventListener('click', writeTag);

Tag erfolgreich beschrieben

Ungültige Kombination abfangen

try {
  // mediaType ist nur bei recordType "mime" erlaubt
  new NDEFRecord({ recordType: 'text', data: 'x', mediaType: 'text/plain' });
} catch (err) {
  console.log(err instanceof TypeError, err.message);
}

true (browserabhängige Fehlermeldung)

Smart-Poster mit verschachtelten Datensätzen

const poster = new NDEFRecord({
  recordType: 'smart-poster',
  data: {
    records: [
      { recordType: 'url', data: 'https://example.com/event' },
      { recordType: 'text', data: 'Sommerfest 2024', lang: 'de' }
    ]
  }
});

// Unterdatensätze wieder auslesen
for (const sub of poster.toRecords()) {
  console.log(sub.recordType);
}

url text

// Wichtig · Fallstricke

Kompatibilität: Web NFC ist experimentell und praktisch nur in Chrome für Android (ab Version 89) verfügbar. Desktop-Browser, Firefox und Safari/iOS unterstützen es nicht, deshalb vorher mit 'NDEFRecord' in window bzw. 'NDEFReader' in window prüfen.
Nur in sicheren Kontexten (HTTPS) und im obersten Dokument verfügbar, nicht in Cross-Origin-iframes. Zum Schreiben mit NDEFReader brauchst du eine Nutzergeste und die NFC-Berechtigung.
record.data ist immer ein DataView und kein String. Text musst du mit TextDecoder dekodieren, JSON zusätzlich mit JSON.parse() umwandeln.
Ungültige Kombinationen werfen einen TypeError, zum Beispiel mediaType ohne "mime", Daten bei "empty", ein lokaler Typ auf oberster Ebene oder encoding/lang bei einem Typ, der kein Text ist.
NFC-Tags haben wenig Speicher (oft nur 48 bis 888 Byte). Große Nutzdaten führen beim Schreiben zu einem Fehler, deshalb die Datensätze möglichst klein halten.
Sicherheit: Daten von fremden Tags sind nicht vertrauenswürdig. Gelesene URLs und Texte vor dem Einfügen ins DOM prüfen oder maskieren, sonst droht XSS.

Siehe auch

NDEFRecord NDEFReader NDEFReader.prototype.write() NDEFReader.prototype.scan() NDEFMessage NDEFRecord.prototype.toRecords() TextDecoder