TextDecoder.encoding — Eigenschaft · JavaScript-Referenz

Signatur

TextDecoder.prototype.encoding

Beschreibung

Die Eigenschaft encoding eines TextDecoder-Objekts gibt an, welche Zeichencodierung der Decoder tatsächlich verwendet. Der Wert wird beim Aufruf des Konstruktors new TextDecoder(label) festgelegt und lässt sich danach nicht mehr ändern.

Wichtig: Zurückgegeben wird nicht das übergebene Label, sondern der kanonische Name laut WHATWG Encoding Standard, immer in Kleinbuchstaben. Aus Aliasen wie "UTF8", "unicode-1-1-utf-8" oder "latin1" werden also "utf-8" bzw. "windows-1252". Deshalb eignet sich die Eigenschaft gut, um Labels aus Benutzereingaben, HTTP-Headern oder Dateimetadaten zu normalisieren und zu prüfen.

Typische Einsatzfälle sind Logging und Fehlersuche (welche Codierung wird wirklich benutzt?), das Vergleichen von Codierungen ohne eigene Alias-Tabellen und das Durchreichen eines sauberen Codierungsnamens an andere Programmteile.

Rückgabewert

Typ

string

Beschreibung

Der kanonische Name der Codierung in Kleinbuchstaben, z. B. "utf-8", "utf-16le", "windows-1252" oder "shift_jis".

Beispiele

Standard-Codierung abfragen

const decoder = new TextDecoder();
console.log(decoder.encoding);

const utf16 = new TextDecoder('UTF-16LE');
console.log(utf16.encoding);

utf-8 utf-16le

Aliase werden auf den kanonischen Namen normalisiert

const labels = ['UTF8', 'unicode-1-1-utf-8', 'latin1', 'ISO-8859-1', 'ascii', 'sjis'];

for (const label of labels) {
  console.log(`${label} -> ${new TextDecoder(label).encoding}`);
}

UTF8 -> utf-8 unicode-1-1-utf-8 -> utf-8 latin1 -> windows-1252 ISO-8859-1 -> windows-1252 ascii -> windows-1252 sjis -> shift_jis

Codierung aus dem Content-Type-Header sicher bestimmen

const createDecoder = (contentType) => {
  const match = /charset=([^;]+)/i.exec(contentType ?? '');
  const label = match ? match[1].trim().replace(/"/g, '') : 'utf-8';
  try {
    return new TextDecoder(label);
  } catch {
    // Unbekanntes Label -> RangeError, auf UTF-8 zurückfallen
    console.warn(`Unbekannte Codierung "${label}", verwende UTF-8`);
    return new TextDecoder('utf-8');
  }
};

const loadText = async (url) => {
  const response = await fetch(url);
  const decoder = createDecoder(response.headers.get('Content-Type'));
  console.log('Dekodiere mit:', decoder.encoding);
  return decoder.decode(await response.arrayBuffer());
};

console.log(createDecoder('text/html; charset="ISO-8859-15"').encoding);
console.log(createDecoder('text/plain; charset=foo').encoding);

iso-8859-15 Unbekannte Codierung "foo", verwende UTF-8 utf-8

// Wichtig · Fallstricke

Schreibgeschützt: Eine Zuweisung wie decoder.encoding = 'utf-16le' wird im nicht-strikten Modus stillschweigend ignoriert und löst im strikten Modus einen TypeError aus. Für eine andere Codierung muss ein neuer TextDecoder erzeugt werden.
Nicht mit dem Label vergleichen: new TextDecoder('UTF-8').encoding === 'UTF-8' ist false, weil der Wert immer kleingeschrieben und kanonisch ist.
Latin-1-Falle: "iso-8859-1", "latin1" und "ascii" werden laut WHATWG-Standard auf "windows-1252" abgebildet. Das ist so gewollt und entspricht dem Browserverhalten bei HTML.
Unbekannte Labels sowie "replacement" führen schon im Konstruktor zu einem RangeError. Die Eigenschaft selbst wirft nie einen Fehler.
TextEncoder.encoding ist dagegen immer "utf-8".
Kompatibilität: Wird von allen modernen Browsern unterstützt, auch in Web Workers. In Node.js ist TextDecoder seit Version 11 global verfügbar. Ohne volle ICU-Daten beherrscht Node.js nur eine eingeschränkte Auswahl an Codierungen.

Siehe auch

PushManager.supportedContentEncodings TextDecoder.fatal TextDecoder.ignoreBOM TextEncoder.encoding TextDecoderStream.encoding