CKTIS / JavaScript
TextDecoder: decodificare i byte e gestire errori e BOM
Decodifica i byte in testo JavaScript e scegli come trattare le sequenze malformate e il marcatore iniziale dell’ordine dei byte, anche con input a blocchi.
Versione: Current web platform; runtime support varies
Sintassi
new TextDecoder()
new TextDecoder(label)
new TextDecoder(label, { fatal, ignoreBOM })
decoder.decode()
decoder.decode(input)
decoder.decode(input, { stream })
decoder.fatal
decoder.ignoreBOMIl metodo di istanza decoder.decode() restituisce una stringa JavaScript. I byte in ingresso sono facoltativi e possono provenire, per esempio, da un ArrayBuffer, un array tipizzato o una DataView. Il costruttore new TextDecoder(label, options) seleziona la codifica, che per impostazione predefinita è "utf-8". Un’etichetta sconosciuta o associata alla codifica replacement causa un RangeError nel costruttore.
decoder.fatal e decoder.ignoreBOM sono proprietà booleane di sola lettura. Entrambe valgono false per impostazione predefinita e si configurano nel costruttore, non in decode(). Con fatal: false, gli errori di decodifica producono il carattere sostitutivo U+FFFD; con fatal: true, decode() genera un TypeError. La decodifica rigorosa non rende sicuro l’uso del testo risultante come HTML.
Per UTF-8, UTF-16LE e UTF-16BE, ignoreBOM: false omette il marcatore iniziale dell’ordine dei byte (BOM), mentre ignoreBOM: true lo conserva come U+FEFF nel risultato. In altre parole, true disattiva il trattamento speciale, non elimina il marcatore. L’opzione non cambia la codifica e non rimuove U+FEFF più avanti nel testo.
Per un input a blocchi, usa lo stesso decodificatore con { stream: true } finché sono attesi altri byte. Il decodificatore conserva lo stato e può restituire una stringa vuota mentre attende il resto di un carattere. Passa l’ultimo blocco senza stream: true oppure concludi con decode() senza argomenti. È a quel punto che una sequenza finale incompleta causa un errore di decodifica. Il successivo input indipendente parte da uno stato nuovo.
TextDecoder fa parte dell’API web Encoding e non è integrato in ECMAScript 2024. Verifica che sia disponibile nell’ambiente di esecuzione di destinazione.
Esempi
{
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}`);
}
}Risultato
default BOM: 65 keep BOM: 65279 replacement: 65533 split: 0, 8364 truncated: TypeError
Le prime tre righe mostrano i punti di codice decimali di `A`, del BOM conservato e del carattere sostitutivo. La riga `split` mostra un primo risultato vuoto e il punto di codice di `€`; in modalità rigorosa, la sequenza troncata genera un `TypeError` solo al `decode()` finale.
Lezioni correlate
- JavaScript · Lezione 3 · Avanzato · Versione: 4