JavaScript TextDecoder e TextEncoder
In questo capitolo esploreremo oggetti built-in come TextDecoder e TextEncoder che renderanno il tuo lavoro in JavaScript ancora più produttivo.
Padroneggiare le interfacce TextEncoder e TextDecoder in JavaScript è essenziale per gestire i dati testuali in modo efficiente, specialmente nelle applicazioni che lavorano con dati binari grezzi e diverse codifiche dei caratteri. Questa guida spiega cosa fanno queste interfacce, quando effettivamente ne hai bisogno e come usarle correttamente, con esempi eseguibili e casi pratici da tenere a mente.
Cosa tratta questa pagina
- Cosa significano codifica e decodifica del testo, e perché non puoi semplicemente trattare i byte come caratteri.
- Codifica di stringhe in byte con
TextEncoder(solo UTF-8). - Decodifica di byte in stringhe con
TextDecoder, incluse codifiche non UTF-8. - Streaming, gestione degli errori (
fatal) e un esempio reale confetch.
Introduzione alla codifica e decodifica del testo
Una string JavaScript è una sequenza di caratteri, ma la rete, il filesystem e la maggior parte delle API binarie lavorano con byte. La codifica del testo trasforma i caratteri in byte seguendo uno schema (come UTF-8); la decodifica del testo inverte questo processo, riconvertendo i byte in caratteri. La stessa string può produrre sequenze di byte diverse a seconda della codifica, motivo per cui un decoder deve sapere con quale codifica sono stati scritti i byte.
JavaScript fornisce due interfacce built-in per questo: TextEncoder (string → byte) e TextDecoder (byte → string). Compaiono ogni volta che si lavora con dati binari grezzi — leggendo un Blob, elaborando un ArrayBuffer, oppure in streaming di una risposta dall'Fetch API.
Utilizzo di TextEncoder in JavaScript
L'interfaccia TextEncoder in JavaScript converte il testo da una string in un flusso di byte codificati. Supporta esclusivamente la codifica UTF-8 e non accetta parametri di codifica nel suo costruttore.
Esempio base di codifica del testo
Per codificare una string usando TextEncoder, segui questo semplice esempio:
Questo script produce un Uint8Array che mostra la versione codificata in UTF-8 di "Hello, world!". Ogni numero corrisponde a un byte: 72 è H, 101 è e, e così via. Questo array è il dato binario che può essere trasmesso tramite protocolli di rete o archiviato per un uso successivo. Nota che il costruttore non accetta argomenti — TextEncoder produce sempre e solo UTF-8.
Tecniche di codifica avanzate
Gestione dei caratteri non standard
TextEncoder gestisce l'intero intervallo Unicode senza problemi. I caratteri multi-byte (lettere cinesi, emoji, lettere accentate) si espandono in più byte ciascuno — motivo chiave per cui la lunghezza in byte di una string codificata è solitamente maggiore della sua .length:
Questo mostra che TextEncoder converte qualsiasi carattere rappresentabile in UTF-8, inclusi emoji e simboli speciali, e che non si deve mai supporre che un carattere equivalga a un byte.
Utilizzo di TextDecoder in JavaScript
Mentre TextEncoder converte le stringhe in byte, TextDecoder esegue l'operazione inversa, trasformando i dati byte codificati in stringhe leggibili. Supporta più codifiche ma usa UTF-8 come predefinita.
Esempio base di decodifica del testo
Ecco come puoi decodificare dati byte in una string:
L'argomento di decode() può essere un Uint8Array, qualsiasi altro TypedArray, un ArrayBuffer o un DataView — qualsiasi cosa che racchiuda byte grezzi.
Questo codice converte un Uint8Array nella string "Hello, world!", illustrando la funzionalità di base di TextDecoder.
Decodifica con codifiche diverse
Esempio con ISO-8859-1
A differenza di TextEncoder, che è solo UTF-8, TextDecoder può leggere molte codifiche legacy. Passa l'etichetta della codifica (ad esempio "iso-8859-1", "windows-1252" o "utf-16le") al costruttore:
Questo produce "Hello, Monde!", mostrando come gestire flussi di byte non UTF-8 — utile quando si leggono file prodotti da sistemi più vecchi o strumenti non Unicode.
Buone pratiche per la codifica e la decodifica
Garantire l'integrità del testo
Quando si codifica e decodifica il testo, assicurarsi che il testo sia trasferito o archiviato correttamente e completamente. Verificare sempre che i dati byte codificati vengano riconvertiti nel testo originale senza perdite.
Decodifica in streaming attraverso i chunk
Un carattere multi-byte può essere suddiviso tra due chunk di dati che arrivano dalla rete. Decodificare ogni chunk in modo indipendente corromperebbe il carattere al confine. L'opzione { stream: true } dice al decoder di trattenere qualsiasi sequenza finale incompleta e di anteporla al chunk successivo. Chiama decode() una volta alla fine senza argomenti per svuotare il buffer:
Senza { stream: true }, quella sequenza di byte suddivisa verrebbe decodificata come caratteri di sostituzione (U+FFFD) e il 你 originale andrebbe perso.
Gestione degli errori con fatal
Per impostazione predefinita, TextDecoder sostituisce le sequenze di byte non valide con il carattere di sostituzione (U+FFFD, visualizzato come �) invece di generare un'eccezione. Per applicare una validazione rigorosa e generare un TypeError su input malformato, passa { fatal: true }:
Usa fatal: true quando devi rifiutare dati corrotti; mantieni il comportamento predefinito (con perdita) quando la visualizzazione parziale è preferibile a un crash.
Esempio reale: decodifica di un flusso di risposta Fetch
L'uso pratico più comune di TextDecoder è la lettura di un corpo di risposta HTTP in streaming byte per byte. Combinato con l'opzione { stream: true }, riassembla in modo sicuro il testo anche quando i caratteri si trovano a cavallo dei confini dei chunk. Lo snippet seguente simula un flusso a due chunk in modo da poter essere eseguito ovunque:
Nel codice reale otterresti quei chunk da response.body.getReader() dopo una chiamata fetch, che è anche il modo in cui funziona il tracciamento del progresso del download.
Quando usare TextEncoder e TextDecoder
- Leggere o scrivere il contenuto di un Blob o File come byte grezzi.
- Lavorare direttamente con un ArrayBuffer o typed array.
- Elaborare una risposta di rete in streaming chunk per chunk.
- Calcolare la lunghezza in byte (per gli header
Content-Length) dove il numero di caratteri non è sufficiente.
Di solito non ne hai bisogno per JSON ordinario o testo recuperato con response.json() / response.text() — il browser gestisce lì la decodifica per te.
Conclusione
TextEncoder e TextDecoder sono il ponte tra le stringhe JavaScript e i byte grezzi usati dalle API binarie, dalla rete e dal filesystem. Ricorda gli elementi essenziali: TextEncoder è solo UTF-8 e non accetta opzioni; TextDecoder supporta molte codifiche e offre { stream: true } per i dati in chunk e { fatal: true } per la validazione rigorosa. Con questi strumenti nel tuo arsenale, puoi gestire il testo correttamente attraverso qualsiasi codifica e sorgente di dati.