CKTIS / JavaScript
TextDecoder: decodificar bytes y gestionar errores y la BOM
Decodifica bytes a texto JavaScript y decide cómo tratar las secuencias mal formadas y la marca de orden de bytes inicial, incluso al leer por bloques.
Versión: Current web platform; runtime support varies
Sintaxis
new TextDecoder()
new TextDecoder(label)
new TextDecoder(label, { fatal, ignoreBOM })
decoder.decode()
decoder.decode(input)
decoder.decode(input, { stream })
decoder.fatal
decoder.ignoreBOMEl método de instancia decoder.decode() devuelve una cadena de JavaScript. La entrada de bytes es opcional y puede ser, por ejemplo, un ArrayBuffer, un arreglo tipado o una DataView. El constructor new TextDecoder(label, options) selecciona la codificación, que por defecto es "utf-8". Una etiqueta desconocida o que corresponda a la codificación replacement provoca un RangeError al construir el decodificador.
decoder.fatal y decoder.ignoreBOM son propiedades booleanas de solo lectura. Ambas valen false por defecto y se configuran en el constructor, no en decode(). Con fatal: false, los errores de decodificación producen el carácter de sustitución U+FFFD; con fatal: true, decode() lanza un TypeError. La decodificación estricta no hace que el texto resultante sea seguro para usarlo como HTML.
En UTF-8, UTF-16LE y UTF-16BE, ignoreBOM: false omite la marca de orden de bytes (BOM) inicial, mientras que ignoreBOM: true la conserva como U+FEFF en el resultado. Es decir, true desactiva el tratamiento especial, no elimina la marca. Esta opción no cambia la codificación ni elimina U+FEFF más adelante en el texto.
Para una entrada por bloques, usa el mismo decodificador con { stream: true } mientras esperes más bytes. Conserva su estado y puede devolver una cadena vacía mientras espera el resto de un carácter. Pasa el último bloque sin stream: true o termina con decode() sin argumentos. En ese momento, una secuencia final incompleta provoca un error de decodificación. La siguiente entrada independiente empieza con un estado nuevo.
TextDecoder forma parte de la API web Encoding y no está incorporado en ECMAScript 2024. Comprueba que esté disponible en el entorno de ejecución de destino.
Ejemplos
{
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
Las tres primeras líneas muestran los puntos de código decimales de `A`, la BOM conservada y el carácter de sustitución. La línea `split` muestra un primer resultado vacío y el punto de código de `€`; en modo estricto, la secuencia truncada solo lanza un `TypeError` en el `decode()` final.
Lecciones relacionadas
- JavaScript · Lección 3 · Avanzado · Versión: 4