new TextDecoder() — Methode · JavaScript-Referenz

Signatur

new TextDecoder(label, options)

Beschreibung

Der Konstruktor TextDecoder() erzeugt einen Dekodierer für genau eine Zeichenkodierung. Mit dessen Methode decode() wandeln Sie ArrayBuffer, TypedArray oder DataView in einen String um. Standard ist "utf-8", unterstützt werden aber alle Kodierungen des WHATWG Encoding Standard, z. B. "utf-16le", "iso-8859-2", "windows-1252" oder "shift_jis".

Einsatzgebiete sind z. B. das Auslesen von Dateien über FileReader bzw. Blob.arrayBuffer(), das Verarbeiten von fetch-Streams, WebSocket-Binärnachrichten, WebAssembly-Speicher oder binären Dateiformaten, in denen Textfelder eingebettet sind.

Mit der Option fatal: true wird bei ungültigen Byte-Folgen ein TypeError geworfen, statt sie stillschweigend durch das Ersatzzeichen U+FFFD (�) zu ersetzen. Mit ignoreBOM: true bleibt eine Byte-Order-Mark im Ergebnis erhalten. Bei Streaming-Daten sollte decode(chunk, { stream: true }) verwendet werden, damit Mehrbyte-Zeichen, die über Chunk-Grenzen verteilt sind, korrekt zusammengesetzt werden.

Parameter

Name	Typ	Default	Beschreibung
$label	string	"utf-8"	Bezeichnung der Kodierung, z. B. `"utf-8"`, `"utf-16le"`, `"windows-1252"`. Groß-/Kleinschreibung und umgebende Leerzeichen werden ignoriert; Aliase wie `"latin1"` sind erlaubt.
$options	Object	{}	Optionales Konfigurationsobjekt.
$options.fatal	boolean	false	Bei `true` wirft `decode()` einen `TypeError` bei ungültigen Byte-Folgen, statt `U+FFFD` einzusetzen.
$options.ignoreBOM	boolean	false	Bei `true` wird eine vorhandene Byte-Order-Mark nicht entfernt, sondern als Zeichen `U+FEFF` ausgegeben.

Rückgabewert

Typ

TextDecoder

Beschreibung

Ein neues TextDecoder-Objekt mit den schreibgeschützten Eigenschaften encoding, fatal und ignoreBOM sowie der Methode decode().

Beispiele

UTF-8-Bytes in einen String umwandeln

const decoder = new TextDecoder(); // Standard: utf-8
const bytes = new Uint8Array([0x48, 0x61, 0x6c, 0x6c, 0x6f, 0x20, 0xc3, 0xbc]);

console.log(decoder.encoding);
console.log(decoder.decode(bytes));

utf-8 Hallo ü

Alte Windows-1252-Datei korrekt lesen

// z. B. aus <input type="file"> stammende CSV-Datei
const readLegacyCsv = async (file) => {
  const buffer = await file.arrayBuffer();
  const decoder = new TextDecoder('windows-1252');
  return decoder.decode(buffer);
};

// Simulation ohne echte Datei:
const blob = new Blob([new Uint8Array([0x47, 0x72, 0xfc, 0xdf, 0x65])]);
readLegacyCsv(blob).then(console.log);

Grüße

Strikte Validierung mit fatal: true

const strict = new TextDecoder('utf-8', { fatal: true });
const invalid = new Uint8Array([0x41, 0xff, 0x42]);

try {
  strict.decode(invalid);
} catch (err) {
  console.log(err.name, '– ungültiges UTF-8');
}

// Ohne fatal wird ersetzt:
console.log(new TextDecoder().decode(invalid));

TypeError – ungültiges UTF-8 A�B

fetch-Antwort streamend dekodieren

const readStreamAsText = async (url) => {
  const response = await fetch(url);
  const reader = response.body.getReader();
  const decoder = new TextDecoder();
  let text = '';

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;
    // stream: true hält unvollständige Mehrbyte-Zeichen zurück
    text += decoder.decode(value, { stream: true });
  }
  text += decoder.decode(); // Rest-Puffer leeren
  return text;
};

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

// Wichtig · Fallstricke

Ein unbekanntes label führt zu einem RangeError. Das Label "replacement" ist ebenfalls unzulässig.
Die Eigenschaft encoding gibt immer den normalisierten Namen zurück: new TextDecoder('latin1').encoding ergibt "windows-1252", denn laut WHATWG-Standard werden ISO-8859-1 und ASCII wie Windows-1252 behandelt.
Wenn Daten in Stücken ankommen, ohne { stream: true } dekodiert werden, können Mehrbyte-Zeichen an den Chunk-Grenzen zerbrechen und als � erscheinen.
Das Gegenstück TextEncoder kodiert ausschließlich nach UTF-8. Andere Kodierungen gibt es nur beim Dekodieren.
Eine Instanz lässt sich wiederverwenden. In Schleifen sollte man den Dekodierer einmal außerhalb anlegen, statt ihn bei jedem Durchlauf neu zu erzeugen.
Kompatibilität: in allen modernen Browsern verfügbar, auch in Web Workern. In Node.js ab Version 11 global, vorher über require('util').TextDecoder. Ob Kodierungen außer UTF-8 und UTF-16 unterstützt werden, hängt in Node.js von der ICU-Ausstattung ab (ab Node.js 13 standardmäßig vollständig).
Für Streams gibt es als Alternative TextDecoderStream, die sich mit pipeThrough() verwenden lässt.

Siehe auch

Uint8Array new TextEncoder() new AudioDecoder() new ImageDecoder() new VideoDecoder()