NDEFRecord — Schnittstelle · JavaScript-Referenz

Signatur

interface NDEFRecord

Beschreibung

NDEFRecord ist die kleinste Dateneinheit der Web-NFC-API. Eine NDEF-Nachricht (NDEFMessage) besteht aus einem oder mehreren solcher Datensätze. Jeder Datensatz hat einen Typ (recordType), optional einen MIME-Typ (mediaType), eine ID und die eigentlichen Nutzdaten als DataView in data.

In der Praxis begegnen dir NDEFRecord-Objekte vor allem im reading-Event eines NDEFReader: Über event.message.records iterierst du alle Datensätze eines gescannten Tags und wertest sie je nach recordType aus, z. B. "text", "url", "mime", "smart-poster", "absolute-url", "empty", "unknown" oder externe Typen wie "example.com:status".

Zum Schreiben musst du den Konstruktor normalerweise nicht direkt aufrufen: NDEFReader.prototype.write() akzeptiert einfache Objekte mit denselben Feldern (record init). Mit new NDEFRecord(init) kannst du einen Datensatz aber vorab erstellen und prüfen.

Wichtige Eigenschaften (alle schreibgeschützt):

recordType: Typ des Datensatzes als String.
mediaType: MIME-Typ bei "mime"-Datensätzen, sonst null.
id: Kennung des Datensatzes oder null.
data: Nutzdaten als DataView oder null.
encoding: Textkodierung bei "text"-Datensätzen (z. B. "utf-8"), sonst null.
lang: Sprach-Tag bei "text"-Datensätzen (z. B. "de"), sonst null.
toRecords(): Gibt bei verschachtelten Datensätzen (z. B. "smart-poster" oder externen/lokalen Typen) die eingebetteten NDEFRecord-Objekte zurück.

Parameter

Name	Typ	Default	Beschreibung
$recordInit Pflicht	Object		Konfigurationsobjekt für den Konstruktor `new NDEFRecord(recordInit)` bzw. für Einträge in `NDEFReader.write()`.
$recordInit.recordType Pflicht	string		Typ des Datensatzes: `"empty"`, `"text"`, `"url"`, `"absolute-url"`, `"mime"`, `"smart-poster"`, `"unknown"`, ein externer Typ (`"domain.tld:typ"`) oder ein lokaler Typ (`":typ"`).
$recordInit.data	string\|ArrayBuffer\|TypedArray\|DataView\|NDEFMessageInit		Nutzdaten. Für `"text"` und `"url"` ein String, für `"mime"` ein Puffer, für `"smart-poster"` und externe Typen auch eine eingebettete Nachricht (`{ records: [...] }`).
$recordInit.mediaType	string		MIME-Typ, nur bei `recordType: "mime"` sinnvoll, z. B. `"application/json"`.
$recordInit.id	string		Optionale Kennung des Datensatzes.
$recordInit.encoding	string	"utf-8"	Textkodierung für `"text"`-Datensätze: `"utf-8"`, `"utf-16"`, `"utf-16le"` oder `"utf-16be"`.
$recordInit.lang	string	Sprache des Dokuments	BCP-47-Sprach-Tag für `"text"`-Datensätze, z. B. `"de-DE"`.

Rückgabewert

Typ

NDEFRecord

Beschreibung

Der Konstruktor liefert ein neues NDEFRecord-Objekt. Bei ungültigen Kombinationen (z. B. "url" ohne String-Daten) wird ein TypeError geworfen.

Beispiele

Datensätze eines gescannten Tags auswerten

const scanTag = async () => {
  const reader = new NDEFReader();
  await reader.scan(); // löst Berechtigungsabfrage aus

  reader.addEventListener('reading', ({ message, serialNumber }) => {
    console.log(`Tag ${serialNumber} mit ${message.records.length} Datensätzen`);

    for (const record of message.records) {
      switch (record.recordType) {
        case 'text': {
          const decoder = new TextDecoder(record.encoding);
          console.log(`Text (${record.lang}):`, decoder.decode(record.data));
          break;
        }
        case 'url':
          console.log('URL:', new TextDecoder().decode(record.data));
          break;
        case 'mime':
          if (record.mediaType === 'application/json') {
            const json = JSON.parse(new TextDecoder().decode(record.data));
            console.log('JSON:', json);
          }
          break;
        default:
          console.log('Nicht behandelter Typ:', record.recordType);
      }
    }
  });

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

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

Tag 04:a2:3b:1c:5f:61:80 mit 2 Datensätzen Text (de): Willkommen im Lager 3 URL: https://example.com/lager/3

NDEFRecord direkt erzeugen und prüfen

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

console.log(record.recordType);  // "text"
console.log(record.lang);        // "de"
console.log(record.encoding);    // "utf-8"
console.log(new TextDecoder().decode(record.data));

text de utf-8 Hallo NFC

Mehrere Datensätze inkl. JSON auf ein Tag schreiben

const writeInventoryTag = async (item) => {
  const reader = new NDEFReader();
  const payload = new TextEncoder().encode(JSON.stringify(item));

  try {
    await reader.write({
      records: [
        { recordType: 'text', data: item.name, lang: 'de' },
        { recordType: 'url', data: `https://example.com/artikel/${item.id}` },
        { recordType: 'mime', mediaType: 'application/json', data: payload }
      ]
    });
    console.log('Tag erfolgreich beschrieben.');
  } catch (err) {
    console.error('Schreiben fehlgeschlagen:', err.name, err.message);
  }
};

document.querySelector('#write').addEventListener('click', () =>
  writeInventoryTag({ id: 4711, name: 'Akkuschrauber', stock: 12 })
);

Tag erfolgreich beschrieben.

Verschachtelte Smart-Poster-Datensätze mit toRecords()

const handleRecord = (record) => {
  if (record.recordType !== 'smart-poster') return;

  const decoder = new TextDecoder();
  for (const inner of record.toRecords()) {
    if (inner.recordType === 'url') {
      console.log('Ziel:', decoder.decode(inner.data));
    } else if (inner.recordType === 'text') {
      console.log('Titel:', decoder.decode(inner.data));
    }
  }
};

Ziel: https://example.com/event Titel: Sommerfest 2024

Siehe auch

IDBRecord NDEFReader DOMRect IDBFactory MediaRecorder CrashReport