TextDecoder.decode() — Methode · JavaScript-Referenz

Signatur

TextDecoder.prototype.decode(input, options)

Beschreibung

decode() wandelt Binärdaten in einen JavaScript-String um. Welche Zeichenkodierung dabei verwendet wird, legen Sie beim Erzeugen des TextDecoder fest, z. B. 'utf-8' (Standard), 'utf-16le', 'iso-8859-2' oder 'windows-1252'. Die Methode ist das Gegenstück zu TextEncoder.prototype.encode().

Typische Einsatzfälle sind das Lesen von Textdateien über FileReader oder Blob.arrayBuffer(), das Auswerten von fetch-Streams, WebSocket-Binärnachrichten, WebAssembly-Speicher und das Parsen von Binärformaten mit eingebetteten Textfeldern.

Mit der Option { stream: true } können Sie Daten stückweise decodieren. Mehrbyte-Zeichen, die über die Grenze zwischen zwei Blöcken hinausgehen, werden dabei intern gepuffert und erst beim nächsten Aufruf ausgegeben. Der letzte Aufruf sollte ohne stream: true (oder ganz ohne Argumente) erfolgen, damit der Puffer geleert wird.

Ungültige Bytefolgen werden standardmäßig durch das Ersatzzeichen U+FFFD (�) ersetzt. Wurde der Decoder mit { fatal: true } erzeugt, wirft decode() stattdessen einen TypeError.

Parameter

Name	Typ	Default	Beschreibung
$input	ArrayBuffer \| SharedArrayBuffer \| TypedArray \| DataView	leerer Puffer	Die Bytes, die decodiert werden sollen. Bei `TypedArray` und `DataView` wird nur der sichtbare Ausschnitt (`byteOffset`/`byteLength`) gelesen.
$options	object	{}	Optionales Objekt mit Einstellungen.
$options.stream	boolean	false	Mit `true` folgen weitere Datenblöcke. Unvollständige Mehrbyte-Sequenzen am Ende werden dann gepuffert, statt als Fehler bzw. `U+FFFD` behandelt zu werden.

Rückgabewert

Typ

string

Beschreibung

Der decodierte Text. Bei stream: true enthält er nur die bis dahin vollständig decodierten Zeichen.

Beispiele

UTF-8-Bytes in einen String umwandeln

const bytes = new Uint8Array([72, 97, 108, 108, 195, 182, 32, 240, 159, 145, 139]);
const decoder = new TextDecoder(); // Standard: utf-8
console.log(decoder.decode(bytes));

Hallö 👋

Antwort von fetch als Stream stückweise decodieren

const readText = 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 Zeichen an Blockgrenzen
    text += decoder.decode(value, { stream: true });
  }
  text += decoder.decode(); // internen Puffer leeren
  return text;
};

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

Legacy-Kodierung und strikte Fehlerbehandlung

// Windows-1252: 0x80 = €, 0xE4 = ä
const latin = new TextDecoder('windows-1252');
console.log(latin.decode(new Uint8Array([0x80, 0x20, 0xE4])));

// Ungültiges UTF-8 mit fatal: true
const strict = new TextDecoder('utf-8', { fatal: true });
try {
  strict.decode(new Uint8Array([0xC3, 0x28]));
} catch (err) {
  console.log(err.name);
}

// Ohne fatal: Ersatzzeichen
console.log(new TextDecoder().decode(new Uint8Array([0xC3, 0x28])));

€ ä TypeError �(

Nullterminierten String aus einem Binärpuffer lesen

const buffer = new Uint8Array([0x46, 0x49, 0x4C, 0x45, 0x00, 0x00, 0x00, 0x00]).buffer;
const view = new Uint8Array(buffer, 0, 8);
const end = view.indexOf(0);
const name = new TextDecoder().decode(view.subarray(0, end === -1 ? view.length : end));
console.log(name);

FILE

// Wichtig · Fallstricke

BOM: Eine Byte-Order-Mark am Anfang wird standardmäßig entfernt. Soll sie erhalten bleiben, erzeugen Sie den Decoder mit { ignoreBOM: true }.
Streaming: Wenn Sie Blöcke ohne stream: true einzeln decodieren, können Mehrbyte-Zeichen (Umlaute, Emojis) an Blockgrenzen zu � werden. Vergessen Sie außerdem nicht den abschließenden Aufruf decode() ohne Argumente.
Nullbytes: 0x00 wird als Zeichen \u0000 ausgegeben und beendet den String nicht. Schneiden Sie C-Strings vorher selbst ab.
Typen: Ein normales Array ([72, 105]) oder ein String als input führt zu einem TypeError. Wandeln Sie es vorher mit new Uint8Array(...) um.
SharedArrayBuffer: In einigen Browsern wird ein SharedArrayBuffer-Ausschnitt abgelehnt. Kopieren Sie die Daten dann vorher mit slice().
Kompatibilität: Wird in allen modernen Browsern, in Web Workern, Deno und Node.js (seit Version 11 global, vorher über require('util').TextDecoder) unterstützt. Welche Legacy-Kodierungen zur Verfügung stehen, kann je nach Umgebung abweichen. Node.js-Builds ohne ICU unterstützen z. B. nur utf-8 und utf-16le.
Stream-Alternative: Für Pipelines ist TextDecoderStream oft bequemer als manuelles Streaming mit decode().

Siehe auch

Uint8Array Blob.prototype.text() new ResizeObserver() TextEncoder.encode() AudioDecoder.decode()