TextDecoderStream.encoding — Eigenschaft · JavaScript-Referenz

Signatur

TextDecoderStream.encoding

Beschreibung

Die Eigenschaft encoding eines TextDecoderStream gibt an, mit welcher Zeichenkodierung der Stream eingehende Bytes (Uint8Array-Chunks) in Text umwandelt. Der Wert steht fest, sobald der Konstruktor new TextDecoderStream(label) aufgerufen wird, und lässt sich danach nicht mehr ändern.

Zurückgegeben wird immer der kanonische Name der Kodierung laut WHATWG Encoding Standard, in Kleinbuchstaben. Du bekommst also nicht unbedingt das Label zurück, das du übergeben hast. Aus "UTF8", "unicode-1-1-utf-8" oder "utf-8" wird jeweils "utf-8". Aus "latin1" und "iso-8859-1" wird "windows-1252".

Die Eigenschaft hilft beim Debuggen und Protokollieren. Außerdem kannst du damit prüfen, ob ein Label, das z. B. aus einem Content-Type-Header ausgelesen wurde, auf die erwartete Kodierung abgebildet wurde, bevor du einen Antwort-Stream dekodierst.

Rückgabewert

Typ

string

Beschreibung

Der kanonische Name der Kodierung in Kleinbuchstaben, z. B. "utf-8", "utf-16le", "windows-1252" oder "shift_jis". Ohne Argument im Konstruktor ist der Wert "utf-8".

Beispiele

Standardkodierung und normalisierte Labels

const standard = new TextDecoderStream();
console.log(standard.encoding);

// Verschiedene Labels werden auf den kanonischen Namen abgebildet
const labels = ['UTF8', 'latin1', 'sjis', 'UTF-16'];
for (const label of labels) {
  const decoder = new TextDecoderStream(label);
  console.log(`${label} -> ${decoder.encoding}`);
}

utf-8 UTF8 -> utf-8 latin1 -> windows-1252 sjis -> shift_jis UTF-16 -> utf-16le

Kodierung aus dem Content-Type-Header ermitteln und Antwort streamen

const ladeText = async (url) => {
  const response = await fetch(url);
  const contentType = response.headers.get('content-type') ?? '';
  const charset = /charset=([^;]+)/i.exec(contentType)?.[1]?.trim() ?? 'utf-8';

  let decoderStream;
  try {
    decoderStream = new TextDecoderStream(charset);
  } catch {
    // Unbekanntes Label -> RangeError, auf UTF-8 zurückfallen
    decoderStream = new TextDecoderStream('utf-8');
  }
  console.log(`Dekodiere mit: ${decoderStream.encoding}`);

  let text = '';
  const reader = response.body.pipeThrough(decoderStream).getReader();
  while (true) {
    const { done, value } = await reader.read();
    if (done) break;
    text += value;
  }
  return text;
};

ladeText('/daten.txt').then((t) => console.log(t.length));

Dekodiere mit: utf-8 1234

Eigenschaft ist schreibgeschützt

const decoder = new TextDecoderStream('utf-16be');
decoder.encoding = 'utf-8'; // wird ignoriert (im Strict Mode: TypeError)
console.log(decoder.encoding);
console.log(decoder.fatal, decoder.ignoreBOM);

utf-16be false false

// Wichtig · Fallstricke

Kein Label-Echo: encoding gibt den kanonischen Namen zurück, nicht das übergebene Label. Wenn du decoder.encoding === 'latin1' vergleichst, ist das Ergebnis immer false, denn der Wert lautet "windows-1252".
Ungültige Labels: Ein unbekanntes Label oder "replacement" führt schon im Konstruktor zu einem RangeError. Eine Instanz mit ungültigem encoding kann es also nicht geben.
Schreibgeschützt: Eine Zuweisung wird stillschweigend ignoriert, im Strict Mode (auch in ES-Modulen) löst sie einen TypeError aus. Für eine andere Kodierung musst du einen neuen Stream erzeugen.
Kompatibilität: TextDecoderStream ist seit 2022 in Chrome, Edge, Firefox (ab 105) und Safari (ab 14.1) verfügbar, außerdem in Node.js, Deno und Bun. In Web Workern steht die Eigenschaft ebenfalls zur Verfügung.
Browser unterstützen nicht immer den vollen Satz an Legacy-Kodierungen (z. B. "iso-2022-jp"). In Node.js ohne vollständige ICU-Daten können Kodierungen außerhalb von UTF-8/UTF-16/Latin-1 fehlen.

Siehe auch

ServiceWorkerRegistration.waiting TextDecoderStream.fatal TextDecoderStream.ignoreBOM TextDecoderStream.readable TextDecoderStream.writable