TextDecoder — Schnittstelle · JavaScript-Referenz

Signatur

interface TextDecoder

Beschreibung

TextDecoder ist das Gegenstück zu TextEncoder. Die Schnittstelle nimmt rohe Binärdaten entgegen und dekodiert sie nach einer festgelegten Zeichenkodierung in einen JavaScript-String (intern UTF-16). Neben UTF-8 unterstützt sie viele ältere Kodierungen aus dem WHATWG Encoding Standard, z. B. windows-1252, iso-8859-2, shift_jis, gbk oder utf-16le.

Einsatzgebiete sind vor allem: Antworten von fetch() als Stream lesen, Dateien per FileReader/Blob.arrayBuffer() in fremden Kodierungen verarbeiten, Binärprotokolle über WebSockets oder WebRTC auswerten und Daten aus WebAssembly-Speicher in Strings umwandeln.

Der Konstruktor new TextDecoder(label, options) legt die Kodierung fest. Die wichtigste Methode ist decode(input, { stream }). Mit stream: true puffert der Decoder unvollständige Mehrbyte-Sequenzen am Ende eines Blocks und fügt sie beim nächsten Aufruf zusammen. Das ist nötig, wenn Daten stückweise ankommen.

Nur lesbare Eigenschaften: encoding (normalisierter Name der Kodierung, z. B. "utf-8"), fatal (ob bei ungültigen Bytes ein Fehler geworfen wird) und ignoreBOM (ob eine Byte-Order-Mark im Ergebnis bleibt).

Parameter

Name	Typ	Default	Beschreibung
$label	string	"utf-8"	Konstruktor-Argument: Name oder Alias der Kodierung, z. B. `"utf-8"`, `"latin1"`, `"windows-1252"`, `"gbk"`. Groß-/Kleinschreibung und Leerzeichen am Rand werden ignoriert. Bei einem unbekannten Label wird ein `RangeError` geworfen.
$options.fatal	boolean	false	Bei `true` wirft `decode()` einen `TypeError`, wenn ungültige Bytes vorkommen. Bei `false` werden sie durch U+FFFD (`�`) ersetzt.
$options.ignoreBOM	boolean	false	Bei `true` bleibt eine Byte-Order-Mark am Anfang im Ergebnis-String. Standardmäßig wird sie entfernt.
$input	ArrayBuffer \| TypedArray \| DataView	leerer Puffer	Argument von `decode()`: die zu dekodierenden Bytes.
$decodeOptions.stream	boolean	false	Argument von `decode()`: `true`, wenn weitere Datenblöcke folgen. Unvollständige Zeichen am Ende werden dann für den nächsten Aufruf zurückgehalten.

Rückgabewert

Typ

TextDecoder / string

Beschreibung

Der Konstruktor gibt eine TextDecoder-Instanz zurück, decode() den dekodierten string.

Beispiele

UTF-8-Bytes in einen String umwandeln

const bytes = new Uint8Array([0x48, 0x61, 0x6c, 0x6c, 0xc3, 0xb6, 0x20, 0xe2, 0x82, 0xac]);
const decoder = new TextDecoder(); // Standard: utf-8
console.log(decoder.encoding);
console.log(decoder.decode(bytes));

utf-8 Hallö €

Datei in Windows-1252 (Latin-1) einlesen

// Bytes einer alten CSV-Datei aus Windows-Excel
const bytes = new Uint8Array([0x4d, 0xfc, 0x6c, 0x6c, 0x65, 0x72, 0x3b, 0x80]);
const decoder = new TextDecoder('windows-1252');
console.log(decoder.decode(bytes));

// Im Browser mit einer echten Datei:
// const buffer = await file.arrayBuffer();
// const text = decoder.decode(buffer);

Müller;€

Fetch-Antwort als Stream dekodieren

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

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;
    // stream: true verhindert kaputte Umlaute an Blockgrenzen
    text += decoder.decode(value, { stream: true });
  }
  text += decoder.decode(); // Restpuffer leeren
  return text;
};

const text = await readTextStream('/daten.txt');
console.log(text.length);

Strenge Validierung mit fatal: true

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

try {
  strict.decode(invalid);
} catch (err) {
  console.log(err.name);
}

// Nachsichtiger Decoder ersetzt ungültige Bytes
console.log(new TextDecoder().decode(invalid));

TypeError H�I

// Wichtig · Fallstricke

Blockgrenzen: Kommen Daten stückweise an, müssen alle Blöcke außer dem letzten mit { stream: true } dekodiert werden. Sonst wird ein Mehrbyte-Zeichen, das auf zwei Blöcke verteilt ist, zu �. Zum Schluss einmal decode() ohne Argumente aufrufen, damit der Restpuffer geleert wird.
Gemeinsamer Speicher: Die Spezifikation erlaubt Views auf einem SharedArrayBuffer. Ältere Browser werfen dabei aber einen Fehler. Im Zweifel die Daten vorher mit slice() kopieren.
Aliase: "latin1" und "iso-8859-1" werden nach WHATWG-Standard als windows-1252 behandelt. decoder.encoding liefert deshalb "windows-1252".
Kein Kodieren in andere Formate: TextEncoder erzeugt nur UTF-8. Für andere Zielkodierungen braucht man Bibliotheken wie iconv-lite.
Unbekannte Labels und die Kodierung "replacement" führen zu einem RangeError.
Kompatibilität: Wird von allen modernen Browsern, Web Workern und Deno unterstützt. In Node.js ist die Schnittstelle ab Version 11 global verfügbar (vorher über require('util').TextDecoder). Für die Transform-Stream-Variante gibt es TextDecoderStream.
Leistung: Einen Decoder einmal anlegen und wiederverwenden, statt ihn bei jedem Aufruf neu zu erzeugen.

Siehe auch

TextEncoder AudioDecoder ImageDecoder VideoDecoder AudioEncoder