TextDecoder.fatal — Eigenschaft · JavaScript-Referenz

Signatur

TextDecoder.prototype.fatal

Beschreibung

Die Eigenschaft fatal eines TextDecoder zeigt, welcher Fehlermodus beim Dekodieren gilt. Ist sie true, bricht decode() bei der ersten ungültigen Byte-Folge ab und wirft einen TypeError. Ist sie false (Standard), ersetzt der Decoder jede fehlerhafte Sequenz durch das Unicode-Ersatzzeichen U+FFFD (�) und dekodiert weiter.

Der Wert wird ausschließlich beim Erzeugen über die Option { fatal: true } im Konstruktor new TextDecoder(label, options) festgelegt und lässt sich danach nicht mehr ändern. Die Eigenschaft dient also nur zum Auslesen der Konfiguration – etwa wenn ein Decoder als Parameter an eine Funktion übergeben wird und diese wissen muss, ob sie mit Ausnahmen rechnen muss.

Der fatale Modus eignet sich für die Validierung von Eingaben: Man kann damit prüfen, ob ein Byte-Puffer gültiges UTF-8 enthält, bevor man ihn weiterverarbeitet oder speichert. Der tolerante Modus ist sinnvoll, wenn Text möglichst vollständig angezeigt werden soll, auch wenn einzelne Bytes beschädigt sind.

Beispiele

Fehlermodus auslesen

const tolerant = new TextDecoder();
const streng = new TextDecoder('utf-8', { fatal: true });

console.log(tolerant.fatal);
console.log(streng.fatal);

false true

Unterschiedliches Verhalten bei ungültigen Bytes

// 0xFF ist in UTF-8 niemals gültig
const bytes = new Uint8Array([0x48, 0x61, 0xff, 0x6c, 0x6c, 0x6f]);

console.log(new TextDecoder().decode(bytes));

try {
  new TextDecoder('utf-8', { fatal: true }).decode(bytes);
} catch (err) {
  console.log(err.name);
}

Ha�llo TypeError

UTF-8-Validierung eines Uploads

const istGueltigesUtf8 = (buffer) => {
  const decoder = new TextDecoder('utf-8', { fatal: true });
  try {
    decoder.decode(buffer);
    return true;
  } catch {
    return false;
  }
};

const datei = new File(['Grüße'], 'text.txt');
const buffer = await datei.arrayBuffer();
console.log(istGueltigesUtf8(buffer));

true

Decoder-Konfiguration in einer Hilfsfunktion prüfen

const sicherDekodieren = (decoder, bytes) => {
  if (!decoder.fatal) {
    // Keine Ausnahme möglich – direkt dekodieren
    return decoder.decode(bytes);
  }
  try {
    return decoder.decode(bytes);
  } catch {
    return null;
  }
};

const d = new TextDecoder('utf-8', { fatal: true });
console.log(sicherDekodieren(d, new Uint8Array([0xc3, 0x28])));

null

// Wichtig · Fallstricke

Nur lesbar: Wenn man decoder.fatal = true zuweist, passiert nichts (im Strict Mode gibt es einen TypeError). Der Modus lässt sich nur über den Konstruktor festlegen.
Streaming: Bei decode(chunk, { stream: true }) gelten unvollständige Sequenzen am Ende eines Chunks noch nicht als Fehler. Im fatalen Modus wird eine abgeschnittene Sequenz erst beim letzten Aufruf ohne stream gemeldet.
Kein Zurücksetzen der Fehlerposition: Der TypeError sagt nicht, an welchem Byte der Fehler liegt. Wer die Position braucht, muss selbst validieren.
Node.js: Der fatale Modus braucht ICU-Unterstützung. Offizielle Builds haben sie, bei Builds mit small-icu oder ohne ICU kann { fatal: true } für manche Kodierungen einen ERR_NO_ICU-Fehler auslösen.
Die Eigenschaft wird in allen modernen Browsern unterstützt, auch in Web Workern. TextDecoderStream bietet dieselbe Eigenschaft für Streams.

Siehe auch

ImageDecoder.complete TextDecoder.encoding TextDecoder.ignoreBOM TextDecoderStream.fatal TextEvent.data