Base de conhecimentoCentro de Exames
PT · PTPortuguês (Portugal)
Escolher idioma13

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.ignoreBOM

O 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

Fontes