Signatur
Beschreibung
Die Methode write() der Schnittstelle NDEFReader gehört zur Web-NFC-API. Sie wartet darauf, dass der Nutzer ein NFC-Tag an das Gerät hält, und schreibt dann eine NDEF-Nachricht (NFC Data Exchange Format) darauf. Das zurückgegebene Promise wird erfüllt, sobald die Nachricht geschrieben ist, und abgelehnt, wenn etwas schiefgeht oder der Vorgang abgebrochen wird.
Die Nachricht kann ganz unterschiedlich aussehen: Ein einfacher string wird zu einem Text-Datensatz ("text"), ein ArrayBuffer bzw. eine TypedArray/DataView zu einem MIME-Datensatz mit application/octet-stream. Für mehr Kontrolle übergibst du ein Objekt mit einem Array records. Jeder Datensatz hat dann einen recordType wie "text", "url", "mime", "absolute-url", "smart-poster", "empty" oder einen externen Typ (z. B. "example.com:meinTyp").
Typische Einsatzfälle sind das Beschreiben von Tags für Inventar, Museumsführer, Visitenkarten oder Geräte-Kopplung direkt aus einer Web-App heraus, ohne dass man eine native App braucht. Mit dem Parameter options steuerst du, ob vorhandene Daten überschrieben werden dürfen (overwrite), und kannst den Wartevorgang über ein AbortSignal abbrechen.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $message Pflicht | string | BufferSource | NDEFMessageInit | Die zu schreibende Nachricht. Ein string wird als UTF-8-Text-Datensatz geschrieben, ein BufferSource als Binär-MIME-Datensatz. Ein Objekt { records: [...] } enthält beliebig viele Datensätze mit den Feldern recordType, data sowie optional mediaType, id, encoding und lang. |
|
| $options | Object | {} | Optionales Konfigurationsobjekt. |
| $options.overwrite | boolean | true | Bei false wird nur auf leere bzw. unformatierte Tags geschrieben. Enthält das Tag schon Daten, wird das Promise mit NoModificationAllowedError abgelehnt. |
| $options.signal | AbortSignal | Signal eines AbortController. Damit lässt sich der Schreibvorgang abbrechen, der Rückgabewert wird dann mit AbortError abgelehnt. |
Rückgabewert
Promise, das mit undefined erfüllt wird, sobald die Nachricht auf das Tag geschrieben ist. Bei einem Fehler wird es mit einer DOMException abgelehnt, z. B. AbortError, NotAllowedError (Berechtigung verweigert), NotSupportedError (kein NFC-Adapter oder Tag nicht kompatibel), NotReadableError (NFC ausgeschaltet), NoModificationAllowedError (bei overwrite: false), NetworkError (Übertragung abgebrochen, etwa weil das Tag entfernt wurde) oder SyntaxError/TypeError (ungültige Nachricht).Beispiele
Einfachen Text auf ein Tag schreiben
const button = document.querySelector('#schreiben');
button.addEventListener('click', async () => {
if (!('NDEFReader' in window)) {
console.log('Web NFC wird nicht unterstützt.');
return;
}
try {
const ndef = new NDEFReader();
console.log('Bitte Tag an das Gerät halten …');
await ndef.write('Hallo von programmierung.net!');
console.log('Nachricht geschrieben.');
} catch (error) {
console.error(`Schreiben fehlgeschlagen: ${error.name} – ${error.message}`);
}
});Mehrere Datensätze: URL, deutscher Text und JSON
const writeProductTag = async (product) => {
const ndef = new NDEFReader();
const encoder = new TextEncoder();
await ndef.write({
records: [
{ recordType: 'url', data: `https://shop.example.com/p/${product.id}` },
{ recordType: 'text', data: product.name, lang: 'de', encoding: 'utf-8' },
{
recordType: 'mime',
mediaType: 'application/json',
data: encoder.encode(JSON.stringify(product))
}
]
});
console.log(`Tag für Produkt ${product.id} beschrieben.`);
};
document.querySelector('#tag').addEventListener('click', () =>
writeProductTag({ id: 4711, name: 'Kölnisch Wasser', preis: 12.9 })
.catch((err) => console.error(err.name))
);Nur leere Tags beschreiben und nach Zeitlimit abbrechen
document.querySelector('#init').addEventListener('click', async () => {
const ndef = new NDEFReader();
const controller = new AbortController();
const timer = setTimeout(() => controller.abort(), 10_000);
try {
await ndef.write('Neues Inventar-Tag', {
overwrite: false,
signal: controller.signal
});
console.log('Leeres Tag erfolgreich initialisiert.');
} catch (error) {
switch (error.name) {
case 'AbortError':
console.log('Kein Tag innerhalb von 10 Sekunden erkannt.');
break;
case 'NoModificationAllowedError':
console.log('Tag enthält bereits Daten – nicht überschrieben.');
break;
case 'NotAllowedError':
console.log('NFC-Berechtigung wurde verweigert.');
break;
default:
console.error(error);
}
} finally {
clearTimeout(timer);
}
});