Znalostná bázaCentrum skúšok
SKSlovenčina
Vybrať jazyk13

CKTIS / JavaScript

TextDecoder: dekódovanie bajtov, chyby a značka BOM

Dekódujte bajty na text v JavaScripte a zvoľte, ako spracovať neplatné sekvencie a úvodnú značku poradia bajtov, a to aj pri čítaní po blokoch.

Verzia: Current web platform; runtime support varies

Syntax

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

Inštančná metóda decoder.decode() vracia reťazec JavaScriptu. Voliteľným vstupom s bajtmi môže byť napríklad ArrayBuffer, typované pole alebo DataView. Konštruktor new TextDecoder(label, options) vyberá kódovanie, predvolene "utf-8". Neznámy názov kódovania alebo názov odkazujúci na kódovanie replacement vyvolá RangeError už v konštruktore.

decoder.fatal a decoder.ignoreBOM sú booleovské vlastnosti len na čítanie. Obe majú predvolenú hodnotu false a nastavujú sa v konštruktore, nie v decode(). Pri fatal: false sa pri chybách dekódovania vkladá náhradný znak U+FFFD; pri fatal: true metóda decode() vyvolá TypeError. Prísne dekódovanie nezaručuje, že výsledný text možno bezpečne použiť ako HTML.

Pri UTF-8, UTF-16LE a UTF-16BE voľba ignoreBOM: false vynechá úvodnú značku poradia bajtov (BOM), kým ignoreBOM: true ju vo výsledku zachová ako U+FEFF. Hodnota true teda vypína osobitné spracovanie, neodstraňuje samotnú značku. Táto voľba nemení kódovanie ani neodstraňuje U+FEFF ďalej v texte.

Pri vstupe po blokoch používajte ten istý dekodér s { stream: true }, kým očakávate ďalšie bajty. Dekodér si uchováva stav a počas čakania na zvyšok znaku môže vrátiť prázdny reťazec. Odovzdajte posledný blok bez stream: true alebo dekódovanie ukončite volaním decode() bez argumentov. Až vtedy neúplná koncová sekvencia spôsobí chybu dekódovania. Ďalší nezávislý vstup začína s novým stavom.

TextDecoder je súčasťou webového Encoding API, nie vstavaným objektom ECMAScriptu 2024. Overte dostupnosť v cieľovom prostredí.

Príklady

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

Výsledok

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

Prvé tri riadky zobrazujú desiatkové kódové body znaku `A`, zachovanej značky BOM a náhradného znaku. Riadok `split` ukazuje prázdny prvý výsledok a kódový bod znaku `€`; neúplná sekvencia v prísnom režime vyvolá `TypeError` až pri záverečnom `decode()`.

Súvisiace lekcie

  • JavaScript · Lekcia 3 · Pokročilá · Verzia: 4

Zdroje