Signatur
Beschreibung
Die Eigenschaft records der Schnittstelle NDEFMessage gehört zur Web-NFC-API. Sie liefert ein schreibgeschütztes Array von NDEFRecord-Objekten, also allen Datensätzen, die in einer NDEF-Nachricht (NFC Data Exchange Format) enthalten sind, zum Beispiel Text, URLs, MIME-Daten oder anwendungsspezifische externe Typen.
In der Praxis greift man darauf meistens im reading-Ereignis eines NDEFReader zu: Das Ereignisobjekt (NDEFReadingEvent) hat eine Eigenschaft message vom Typ NDEFMessage, und über message.records geht man alle Datensätze des gescannten Tags durch. Jeder Datensatz hat unter anderem recordType, mediaType, id, encoding, lang und data (ein DataView).
Das Array ist eingefroren (Object.isFrozen() ergibt true). Datensätze lassen sich also nicht nachträglich hinzufügen oder entfernen. Wer eine neue Nachricht schreiben will, erzeugt sie mit new NDEFMessage({ records: [...] }) oder übergibt die Datensätze direkt an NDEFReader.write().
Rückgabewert
NDEFRecord-Objekten der Nachricht. Bei einem leeren Tag kann es leer sein.Beispiele
Alle Datensätze eines gescannten Tags ausgeben
const scanTag = async () => {
const reader = new NDEFReader();
await reader.scan(); // erfordert Nutzergeste + Berechtigung
reader.addEventListener('reading', ({ message, serialNumber }) => {
console.log(`Tag ${serialNumber}: ${message.records.length} Datensatz/Datensätze`);
for (const record of message.records) {
console.log(`Typ: ${record.recordType}, MIME: ${record.mediaType ?? '–'}`);
}
});
};
document.querySelector('#scan').addEventListener('click', scanTag);Text- und URL-Datensätze dekodieren
const decodeRecords = (message) => {
return message.records.map((record) => {
switch (record.recordType) {
case 'text': {
const decoder = new TextDecoder(record.encoding ?? 'utf-8');
return { typ: 'text', sprache: record.lang, wert: decoder.decode(record.data) };
}
case 'url':
return { typ: 'url', wert: new TextDecoder().decode(record.data) };
case 'mime':
if (record.mediaType === 'application/json') {
return { typ: 'json', wert: JSON.parse(new TextDecoder().decode(record.data)) };
}
return { typ: 'mime', mediaType: record.mediaType };
default:
return { typ: record.recordType };
}
});
};
const reader = new NDEFReader();
reader.onreading = (event) => console.log(decodeRecords(event.message));
await reader.scan();Eigene NDEFMessage erzeugen und records prüfen
const message = new NDEFMessage({
records: [
{ recordType: 'text', data: 'Raum 204', lang: 'de' },
{ recordType: 'url', data: 'https://example.com/raum/204' }
]
});
console.log(message.records.length);
console.log(message.records[0].recordType);
console.log(Object.isFrozen(message.records));
// Schreiben auf einen Tag
const writer = new NDEFReader();
await writer.write(message);// Wichtig · Fallstricke
- Kompatibilität: Web NFC ist experimentell und wird derzeit nur von Chrome für Android (ab 89) unterstützt. Desktop-Browser, Firefox und Safari/iOS kennen
NDEFReaderundNDEFMessagenicht. Vorher mit'NDEFReader' in windowprüfen. - Die API funktioniert nur in einem sicheren Kontext (HTTPS), nur im Frame der obersten Ebene und nur bei sichtbarer Seite.
scan()undwrite()brauchen eine Nutzergeste und die NFC-Berechtigung. recordsist eingefroren:push()oder direkte Zuweisungen werfen im Strict Mode einenTypeErroroder werden stillschweigend ignoriert.record.dataist einDataViewund kein String. Text muss man mitTextDecoderdekodieren. Bei den Typensmart-posterund bei externen Typen enthält der Datensatz eventuell eine verschachtelte Nachricht, die man mitrecord.toRecords()ausliest.- Daten von NFC-Tags sind nicht vertrauenswürdig. Den dekodierten Inhalt nie ungeprüft in
innerHTMLeinfügen oder als URL öffnen (XSS- und Phishing-Gefahr).