Base de connaissancesCentre d’examen
FRFrançais
Choisir la langue13

CKTIS / JavaScript

TextDecoder : décoder des octets et gérer les erreurs et le BOM

Décodez des octets en texte JavaScript et choisissez le traitement des séquences mal formées et de la marque d’ordre des octets initiale, même par blocs.

Version : Current web platform; runtime support varies

Syntaxe

new TextDecoder()
new TextDecoder(label)
new TextDecoder(label, { fatal, ignoreBOM })
decoder.decode()
decoder.decode(input)
decoder.decode(input, { stream })
decoder.fatal
decoder.ignoreBOM

La méthode d’instance decoder.decode() renvoie une chaîne JavaScript. L’entrée d’octets est facultative : il peut s’agir, par exemple, d’un ArrayBuffer, d’un tableau typé ou d’une DataView. Le constructeur new TextDecoder(label, options) choisit l’encodage, "utf-8" par défaut. Un libellé inconnu ou associé à l’encodage replacement provoque une RangeError dès la construction.

decoder.fatal et decoder.ignoreBOM sont des propriétés booléennes en lecture seule. Elles valent false par défaut et se règlent dans les options du constructeur, pas dans decode(). Avec fatal: false, les erreurs de décodage produisent le caractère de remplacement U+FFFD ; avec fatal: true, decode() lève une TypeError. Le décodage strict ne rend pas le texte obtenu sûr à utiliser comme HTML.

Pour UTF-8, UTF-16LE et UTF-16BE, ignoreBOM: false omet la marque d’ordre des octets (BOM) initiale, tandis que ignoreBOM: true la conserve sous la forme U+FEFF dans le résultat. Autrement dit, true désactive le traitement spécial, sans supprimer la marque. Cette option ne modifie pas l’encodage et ne supprime pas les U+FEFF situés plus loin dans le texte.

Pour une entrée par blocs, réutilisez le même décodeur avec { stream: true } tant qu’il reste des octets à recevoir. Il conserve son état et peut renvoyer une chaîne vide en attendant la fin d’un caractère. Passez le dernier bloc sans stream: true, ou terminez par decode() sans argument. C’est alors qu’une séquence finale incomplète provoque une erreur de décodage. L’entrée indépendante suivante repart d’un état neuf.

TextDecoder fait partie de l’API web Encoding et n’est pas intégré à ECMAScript 2024. Vérifiez sa disponibilité dans l’environnement d’exécution visé.

Exemples

{
  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}`);
  }
}

Résultat

default BOM: 65
keep BOM: 65279
replacement: 65533
split: 0, 8364
truncated: TypeError

Les trois premières lignes affichent les points de code décimaux de `A`, du BOM conservé et du caractère de remplacement. La ligne `split` montre un premier résultat vide et le point de code de `€` ; en mode strict, la séquence tronquée ne provoque une `TypeError` qu’au dernier appel à `decode()`.

Leçons associées

  • JavaScript · Leçon 3 · Avancé · Version : 4

Sources