TextDecoder.ignoreBOM — Eigenschaft · JavaScript-Referenz

Signatur

TextDecoder.prototype.ignoreBOM

Beschreibung

Die Eigenschaft ignoreBOM zeigt an, wie ein TextDecoder mit einer Byte Order Mark (BOM) am Anfang des Byte-Stroms umgeht. Eine BOM ist eine kurze Bytefolge, etwa EF BB BF bei UTF-8 oder FF FE bei UTF-16LE. Programme wie Windows-Editoren oder Excel-CSV-Exporte schreiben sie oft an den Dateianfang.

Der Wert wird einmalig über die Option ignoreBOM im Konstruktor new TextDecoder(label, { ignoreBOM }) festgelegt und lässt sich danach nicht mehr ändern. Standard ist false.

false (Standard): Der Decoder erkennt eine BOM, die zu seiner Kodierung passt, und entfernt sie aus dem Ergebnis.
true: Der Decoder behandelt die BOM nicht gesondert. Sie bleibt als Zeichen U+FEFF im Ergebnis-String stehen.

Den Wert true braucht man selten, zum Beispiel wenn Daten byte-genau wiederhergestellt werden sollen oder ein Werkzeug prüfen soll, ob eine Datei eine BOM enthält. In den meisten Anwendungen ist der Standardwert richtig, weil eine übrig gebliebene BOM sonst Vergleiche, JSON.parse() oder CSV-Spaltennamen stört.

Rückgabewert

Typ

boolean

Beschreibung

true, wenn die BOM im dekodierten Text erhalten bleibt, false (Standard), wenn sie entfernt wird.

Beispiele

Standardwert abfragen und per Option setzen

const standard = new TextDecoder();
const mitBom = new TextDecoder('utf-8', { ignoreBOM: true });

console.log(standard.ignoreBOM);
console.log(mitBom.ignoreBOM);

false true

Unterschied beim Dekodieren einer UTF-8-BOM

// UTF-8-BOM (EF BB BF), danach "Hi"
const bytes = new Uint8Array([0xEF, 0xBB, 0xBF, 0x48, 0x69]);

const entfernt = new TextDecoder().decode(bytes);
const behalten = new TextDecoder('utf-8', { ignoreBOM: true }).decode(bytes);

console.log(entfernt, entfernt.length);
console.log(behalten.length, behalten.codePointAt(0).toString(16));

Hi 2 3 feff

Hochgeladene Datei auf BOM prüfen

const hatBom = async (file) => {
  const buffer = await file.slice(0, 4).arrayBuffer();
  const decoder = new TextDecoder('utf-8', { ignoreBOM: true });
  return decoder.decode(buffer).startsWith('\uFEFF');
};

document.querySelector('input[type=file]').addEventListener('change', async (e) => {
  const file = e.target.files[0];
  console.log(`${file.name} hat BOM:`, await hatBom(file));
});

daten.csv hat BOM: true

// Wichtig · Fallstricke

Der Name führt leicht in die Irre: ignoreBOM: true heißt „die BOM nicht gesondert behandeln“. Sie wird also nicht entfernt und bleibt im Text stehen. Wer die BOM loswerden will, lässt den Standardwert false.
Die Eigenschaft ist schreibgeschützt. Eine Zuweisung wie decoder.ignoreBOM = true hat keine Wirkung und wirft im Strict Mode einen TypeError. Für einen anderen Wert muss ein neuer Decoder erzeugt werden.
Die BOM bestimmt nicht die Kodierung: Ein UTF-8-Decoder entfernt nur eine UTF-8-BOM und wechselt bei einer UTF-16-BOM nicht auf UTF-16. Die Einstellung wirkt nur bei utf-8, utf-16le und utf-16be.
Beim Streaming mit decode(chunk, { stream: true }) wird die BOM nur am Anfang des Datenstroms erkannt, nicht mitten in späteren Teilstücken.
Kompatibilität: In allen modernen Browsern, in Web Workern, in Deno und in Node.js (global ab Version 11, vorher über require('util').TextDecoder) verfügbar. Der Internet Explorer unterstützt sie nicht. TextDecoderStream hat die gleiche Eigenschaft.

Siehe auch

TextDecoder TextDecoder.prototype.decode() TextDecoder.prototype.encoding TextDecoder.prototype.fatal TextEncoder TextDecoderStream Text.assignedSlot