TextDecoderStream.ignoreBOM — Eigenschaft · JavaScript-Referenz

Signatur

get TextDecoderStream.prototype.ignoreBOM

Beschreibung

Die Eigenschaft ignoreBOM eines TextDecoderStream gibt an, mit welcher Einstellung der Stream erzeugt wurde. Der Wert kommt aus der Option ignoreBOM im Konstruktor: new TextDecoderStream(label, { ignoreBOM }). Später ändern lässt er sich nicht, die Eigenschaft ist nur lesbar.

Der Name führt leicht in die Irre. „ignoreBOM“ bedeutet, dass der Decoder das BOM nicht gesondert behandelt. Beim Standardwert false erkennt der Decoder ein führendes BOM und entfernt es aus der Ausgabe. Bei true bleibt es als Zeichen U+FEFF am Anfang des ersten Text-Chunks stehen.

true lohnt sich, wenn der Inhalt originalgetreu weitergegeben werden soll, etwa beim Durchreichen, Prüfen oder Hashen von Dateien. Auch wenn nachgelagerter Code das BOM selbst auswerten soll, zum Beispiel bei CSV-Dateien aus Excel, ist true sinnvoll. Zum Anzeigen oder Parsen von Text (etwa mit JSON.parse) behält man den Standardwert false. Sonst steht ein unsichtbares Zeichen am Textanfang und stört.

Die Einstellung gilt nur für die UTF-Kodierungen utf-8, utf-16le und utf-16be. Außerdem zählt nur ein BOM ganz am Anfang des Streams. Ein U+FEFF mitten im Datenstrom wird immer als normales Zeichen (Zero Width No-Break Space) ausgegeben.

Beispiele

Einstellung abfragen

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

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

false true

Unterschied mit und ohne BOM im Stream

// UTF-8-BOM (EF BB BF) gefolgt von "Hallo"
const bytes = new Uint8Array([0xef, 0xbb, 0xbf, 0x48, 0x61, 0x6c, 0x6c, 0x6f]);

const decode = async (ignoreBOM) => {
  const stream = new Blob([bytes]).stream()
    .pipeThrough(new TextDecoderStream('utf-8', { ignoreBOM }));
  let text = '';
  for await (const chunk of stream) text += chunk;
  return text;
};

const ohne = await decode(false);
const mit = await decode(true);
console.log(ohne.length, JSON.stringify(ohne));
console.log(mit.length, mit.codePointAt(0).toString(16));

5 "Hallo" 6 feff

CSV per fetch laden und BOM selbst auswerten

const ladeCsv = async (url) => {
  const res = await fetch(url);
  const decoder = new TextDecoderStream('utf-8', { ignoreBOM: true });
  const reader = res.body.pipeThrough(decoder).getReader();

  let text = '';
  for (;;) {
    const { value, done } = await reader.read();
    if (done) break;
    text += value;
  }

  // Excel-Export erkennen, BOM danach entfernen
  const vonExcel = decoder.ignoreBOM && text.startsWith('\uFEFF');
  if (vonExcel) text = text.slice(1);
  return { vonExcel, zeilen: text.split(/\r?\n/) };
};

const { vonExcel, zeilen } = await ladeCsv('/daten/export.csv');
console.log(vonExcel, zeilen[0]);

true "Name;Ort;Datum"

// Wichtig · Fallstricke

Schreibgeschützt: Eine Zuweisung wie stream.ignoreBOM = true wird im nicht-strikten Modus stillschweigend ignoriert und löst im strikten Modus einen TypeError aus. Für eine andere Einstellung muss man einen neuen Stream erzeugen.
Verwechslungsgefahr: true heißt BOM behalten, nicht BOM entfernen.
Ist ignoreBOM: true gesetzt, liefern JSON.parse, Vergleiche wie text === 'abc' oder startsWith bei Daten mit BOM unerwartete Ergebnisse, weil das unsichtbare U+FEFF am Anfang steht.
Die Kodierung wird durch das BOM nicht automatisch umgeschaltet. Das Label im Konstruktor (Standard utf-8) bleibt maßgeblich.
Bei Nicht-UTF-Kodierungen wie windows-1252 hat die Option keine Wirkung.
Kompatibilität: Chrome/Edge 71+, Safari 14.1+ und Firefox 105+. In Node.js ab 16.6 über stream/web, ab 18 global verfügbar. Für ältere Umgebungen gibt es TextDecoder mit { stream: true }, dort mit derselben Option.

Siehe auch

TextDecoder.ignoreBOM TextDecoderStream.encoding TextDecoderStream.readable TextDecoderStream.writable TextDecoderStream.fatal