CKTIS / JavaScript
TextDecoder: descodificar bytes e tratar erros e o BOM
Descodifica bytes para texto JavaScript e escolhe como tratar sequências malformadas e a marca de ordem de bytes inicial, mesmo ao ler por blocos.
Versão: Current web platform; runtime support varies
Sintaxe
new TextDecoder()
new TextDecoder(label)
new TextDecoder(label, { fatal, ignoreBOM })
decoder.decode()
decoder.decode(input)
decoder.decode(input, { stream })
decoder.fatal
decoder.ignoreBOMO método de instância decoder.decode() devolve uma cadeia de caracteres JavaScript. A entrada de bytes é facultativa e pode ser, por exemplo, um ArrayBuffer, um array tipado ou uma DataView. O construtor new TextDecoder(label, options) escolhe a codificação, por predefinição "utf-8". Uma etiqueta desconhecida ou que corresponda à codificação replacement provoca um RangeError no construtor.
decoder.fatal e decoder.ignoreBOM são propriedades booleanas só de leitura. Ambas têm o valor false por predefinição e são configuradas no construtor, não em decode(). Com fatal: false, os erros de descodificação produzem o carácter de substituição U+FFFD; com fatal: true, decode() lança um TypeError. A descodificação estrita não torna seguro utilizar o texto resultante como HTML.
Em UTF-8, UTF-16LE e UTF-16BE, ignoreBOM: false omite a marca de ordem de bytes (BOM) inicial, enquanto ignoreBOM: true a conserva como U+FEFF no resultado. Ou seja, true desativa o tratamento especial, não elimina a marca. Esta opção não altera a codificação nem remove U+FEFF mais adiante no texto.
Para uma entrada por blocos, usa o mesmo descodificador com { stream: true } enquanto forem esperados mais bytes. O descodificador mantém o estado e pode devolver uma cadeia vazia enquanto espera pelo resto de um carácter. Passa o último bloco sem stream: true ou termina com decode() sem argumentos. É nesse momento que uma sequência final incompleta provoca um erro de descodificação. A entrada independente seguinte começa com um estado novo.
TextDecoder faz parte da API web Encoding e não está incorporado no ECMAScript 2024. Verifica a disponibilidade no ambiente de execução de destino.
Exemplos
{
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}`);
}
}Resultado
default BOM: 65 keep BOM: 65279 replacement: 65533 split: 0, 8364 truncated: TypeError
As primeiras três linhas mostram os pontos de código decimais de `A`, do BOM conservado e do carácter de substituição. A linha `split` mostra um primeiro resultado vazio e o ponto de código de `€`; no modo estrito, a sequência truncada só lança um `TypeError` no `decode()` final.
Lições relacionadas
- JavaScript · Lição 3 · Avançado · Versão: 4