CKTIS / JavaScript
TextDecoder: Bytes dekodieren, Fehler und BOM behandeln
Dekodiere Bytes zu JavaScript-Text und bestimme, wie fehlerhafte Sequenzen und eine führende Byte-Reihenfolgemarkierung behandelt werden, auch bei Eingabe in Blöcken.
Version: Current web platform; runtime support varies
Syntax
new TextDecoder()
new TextDecoder(label)
new TextDecoder(label, { fatal, ignoreBOM })
decoder.decode()
decoder.decode(input)
decoder.decode(input, { stream })
decoder.fatal
decoder.ignoreBOMDie Instanzmethode decoder.decode() gibt einen JavaScript-String zurück. Als optionale Byte-Eingabe eignet sich etwa ein ArrayBuffer, ein typisiertes Array oder ein DataView. Der Konstruktor new TextDecoder(label, options) wählt die Kodierung; der Standardwert ist "utf-8". Eine unbekannte Bezeichnung oder eine Bezeichnung für die Kodierung replacement führt bereits im Konstruktor zu einem RangeError.
decoder.fatal und decoder.ignoreBOM sind schreibgeschützte boolesche Eigenschaften. Beide sind standardmäßig false und werden über Konstruktoroptionen gesetzt, nicht über decode(). Bei fatal: false führen Dekodierfehler zum Ersatzzeichen U+FFFD; bei fatal: true wirft decode() einen TypeError. Striktes Dekodieren macht den resultierenden Text nicht sicher für die Verwendung als HTML.
Für UTF-8, UTF-16LE und UTF-16BE lässt ignoreBOM: false eine führende Byte-Reihenfolgemarkierung (BOM) weg; ignoreBOM: true behält sie als U+FEFF im Ergebnis. true überspringt also die Sonderbehandlung, nicht die Markierung selbst. Die Option ändert weder die Kodierung noch entfernt sie später im Text vorkommendes U+FEFF.
Verwende bei blockweiser Eingabe denselben Decoder mit { stream: true }, solange noch Bytes folgen. Er behält seinen Zustand und kann einen leeren String zurückgeben, während er auf den Rest eines Zeichens wartet. Übergib den letzten Block ohne stream: true oder schließe die Verarbeitung mit decode() ohne Argumente ab. Erst dann führt eine unvollständige Sequenz am Ende zu einem Dekodierfehler. Die nächste unabhängige Eingabe beginnt mit frischem Zustand.
TextDecoder gehört zur Encoding API der Webplattform und ist kein eingebautes Objekt von ECMAScript 2024. Prüfe die Verfügbarkeit in deiner Zielumgebung.
Beispiele
{
const bytes = Uint8Array.of(0xEF, 0xBB, 0xBF, 0x41);
const standard = new TextDecoder();
const keep = new TextDecoder("utf-8", { ignoreBOM: true });
const strict = new TextDecoder("utf-8", { fatal: true });
console.log(`default BOM: ${standard.decode(bytes).codePointAt(0)}`);
console.log(`keep BOM: ${keep.decode(bytes).codePointAt(0)}`);
console.log(`replacement: ${standard.decode(Uint8Array.of(0xFF)).codePointAt(0)}`);
const before = strict.decode(Uint8Array.of(0xE2, 0x82), { stream: true });
const after = strict.decode(Uint8Array.of(0xAC));
console.log(`split: ${before.length}, ${after.codePointAt(0)}`);
strict.decode(Uint8Array.of(0xE2), { stream: true });
try {
strict.decode();
} catch (error) {
console.log(`truncated: ${error.name}`);
}
}Ergebnis
default BOM: 65 keep BOM: 65279 replacement: 65533 split: 0, 8364 truncated: TypeError
Die ersten drei Zeilen zeigen die dezimalen Codepunkte für `A`, die beibehaltene BOM und das Ersatzzeichen. Die Zeile `split` zeigt ein leeres erstes Ergebnis und den Codepunkt für `€`; die abgeschnittene Sequenz löst im strikten Modus erst beim abschließenden `decode()` einen `TypeError` aus.
Zugehörige Lektionen
- JavaScript · Lektion 3 · Fortgeschritten · Version: 4