NDEFRecord.toRecords() — Methode · JavaScript-Referenz

Signatur

NDEFRecord.prototype.toRecords()

Beschreibung

Die Methode toRecords() gehört zur Web-NFC-API und wertet die Rohdaten (NDEFRecord.data, ein DataView) eines Datensatzes als eingebettete NDEF-Nachricht aus. Das Ergebnis ist ein Array von NDEFRecord-Objekten, die wieder genauso ausgelesen werden können wie die Datensätze der obersten Ebene.

Eingebettete Datensätze gibt es nur bei bestimmten Datensatztypen:

"smart-poster" – ein Smart Poster enthält z. B. einen URL-Datensatz, Titel-Texte, ein Icon, eine Aktion (":act") oder eine Größe (":s").
Externe Typen wie "example.com:meinTyp" – eigene, domänengebundene Formate, die verschachtelte Datensätze tragen können.
Lokale Typen wie ":act" – nur innerhalb eines übergeordneten Datensatzes gültig.

Typischerweise ruft man toRecords() im reading-Event eines NDEFReader auf, nachdem man anhand von record.recordType geprüft hat, dass verschachtelte Daten zu erwarten sind. Für einfache Typen wie "text", "url" oder "mime" liest man stattdessen record.data direkt, etwa mit einem TextDecoder.

Rückgabewert

Typ

Array<NDEFRecord>

Beschreibung

Ein Array der in data eingebetteten Datensätze. Ist der recordType kein Smart Poster, kein externer und kein lokaler Typ, wird eine NotSupportedError-DOMException ausgelöst. Sind die Daten keine gültige NDEF-Nachricht, wird ebenfalls ein Fehler ausgelöst.

Beispiele

Smart Poster auslesen

const reader = new NDEFReader();

const leseSmartPoster = async () => {
  await reader.scan();
  reader.addEventListener("reading", ({ message }) => {
    for (const record of message.records) {
      if (record.recordType !== "smart-poster") continue;

      const decoder = new TextDecoder();
      for (const teil of record.toRecords()) {
        switch (teil.recordType) {
          case "url":
            console.log("URL:", decoder.decode(teil.data));
            break;
          case "text": {
            const textDecoder = new TextDecoder(teil.encoding);
            console.log(`Titel (${teil.lang}):`, textDecoder.decode(teil.data));
            break;
          }
          case ":act":
            console.log("Aktion:", teil.data.getUint8(0));
            break;
        }
      }
    }
  });
};

// Muss durch eine Nutzeraktion ausgelöst werden
document.querySelector("#scan").addEventListener("click", leseSmartPoster);

URL: https://programmierung.net Titel (de): Programmierung.net Aktion: 0

Externen Typ mit verschachtelten Datensätzen schreiben und lesen

// Schreiben: externer Typ mit eingebetteten Datensätzen
const schreibeProfil = async () => {
  const writer = new NDEFReader();
  await writer.write({
    records: [{
      recordType: "example.com:profil",
      data: {
        records: [
          { recordType: "text", data: "Anna" },
          { recordType: "url", data: "https://example.com/anna" }
        ]
      }
    }]
  });
};

// Lesen: eingebettete Datensätze wieder zerlegen
const verarbeite = (record) => {
  if (record.recordType === "example.com:profil") {
    const [name, link] = record.toRecords();
    const decoder = new TextDecoder();
    console.log(decoder.decode(name.data), decoder.decode(link.data));
  }
};

Anna https://example.com/anna

Fehler bei nicht unterstütztem Typ abfangen

const sichereEintraege = (record) => {
  try {
    return record.toRecords();
  } catch (err) {
    if (err.name === "NotSupportedError") {
      console.warn(`Typ "${record.recordType}" hat keine eingebetteten Datensätze.`);
      return [];
    }
    throw err;
  }
};

// z. B. mit einem Text-Datensatz
const textRecord = new NDEFRecord({ recordType: "text", data: "Hallo" });
console.log(sichereEintraege(textRecord));

Typ "text" hat keine eingebetteten Datensätze. []

// Wichtig · Fallstricke

Browser-Unterstützung: Web NFC ist experimentell und derzeit nur in Chrome für Android (ab Version 89) verfügbar. Firefox, Safari und Desktop-Browser unterstützen die API nicht. Vorher mit "NDEFReader" in window prüfen.
Sicherer Kontext: Nur über HTTPS nutzbar. scan() und write() erfordern eine Nutzeraktion und die NFC-Berechtigung.
Bei "text", "url", "absolute-url", "mime", "empty" und "unknown" löst toRecords() eine NotSupportedError aus. Deshalb vorher recordType prüfen oder den Aufruf mit try/catch absichern.
Lokale Typen (beginnen mit :) sind nur innerhalb eines übergeordneten Datensatzes erlaubt, nicht auf oberster Ebene einer Nachricht.
Daten von NFC-Tags stammen aus einer nicht vertrauenswürdigen Quelle: URLs und Texte vor der Anzeige prüfen und niemals ungeprüft per innerHTML einfügen (XSS-Gefahr).

Siehe auch

NDEFRecord NDEFRecord.data NDEFRecord.recordType NDEFReader NDEFReader.scan() NDEFReader.write() NDEFMessage TextDecoder