CKTIS / JavaScript
TextDecoder: dekódování bajtů, chyby a značka BOM
Dekódujte bajty na text v JavaScriptu a zvolte, jak zpracovat neplatné sekvence a úvodní značku pořadí bajtů, a to i při čtení po blocích.
Verze: Current web platform; runtime support varies
Syntaxe
new TextDecoder()
new TextDecoder(label)
new TextDecoder(label, { fatal, ignoreBOM })
decoder.decode()
decoder.decode(input)
decoder.decode(input, { stream })
decoder.fatal
decoder.ignoreBOMInstanční metoda decoder.decode() vrací řetězec JavaScriptu. Volitelným vstupem s bajty může být například ArrayBuffer, typované pole nebo DataView. Konstruktor new TextDecoder(label, options) vybírá kódování, ve výchozím stavu "utf-8". Neznámý název kódování nebo název odpovídající kódování replacement vyvolá RangeError už v konstruktoru.
decoder.fatal a decoder.ignoreBOM jsou logické vlastnosti pouze pro čtení. Obě mají výchozí hodnotu false a nastavují se v konstruktoru, nikoli v decode(). Při fatal: false vedou chyby dekódování ke vložení náhradního znaku U+FFFD; při fatal: true metoda decode() vyvolá TypeError. Striktní dekódování nezaručuje, že výsledný text lze bezpečně použít jako HTML.
U UTF-8, UTF-16LE a UTF-16BE volba ignoreBOM: false vynechá úvodní značku pořadí bajtů (BOM), zatímco ignoreBOM: true ji ve výsledku zachová jako U+FEFF. Hodnota true tedy vypíná zvláštní zpracování, neodstraňuje samotnou značku. Volba nemění kódování ani neodstraňuje U+FEFF dále v textu.
Při vstupu po blocích používejte stejný dekodér s { stream: true }, dokud očekáváte další bajty. Dekodér si uchovává stav a při čekání na zbytek znaku může vrátit prázdný řetězec. Předejte poslední blok bez stream: true nebo dekódování ukončete voláním decode() bez argumentů. Teprve tehdy neúplná koncová sekvence způsobí chybu dekódování. Další nezávislý vstup začíná s novým stavem.
TextDecoder je součástí webového Encoding API, nikoli vestavěným objektem ECMAScriptu 2024. Ověřte dostupnost v cílovém běhovém prostředí.
Příklady
{
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}`);
}
}Výsledek
default BOM: 65 keep BOM: 65279 replacement: 65533 split: 0, 8364 truncated: TypeError
První tři řádky vypisují desítkové kódové body znaku `A`, zachované značky BOM a náhradního znaku. Řádek `split` ukazuje prázdný první výsledek a kódový bod znaku `€`; neúplná sekvence ve striktním režimu vyvolá `TypeError` až při závěrečném `decode()`.
Související lekce
- JavaScript · Lekce 3 · Pokročilá · Verze: 4