KennisbankExamencentrum
NL · NLNederlands (Nederland)
Taal kiezen13

CKTIS / JavaScript

TextDecoder: bytes decoderen, fouten en de BOM afhandelen

Decodeer bytes naar JavaScript-tekst en bepaal hoe je ongeldige reeksen en een bytevolgordemarkering aan het begin afhandelt, ook bij invoer in blokken.

Versie: 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

De instantiemethode decoder.decode() geeft een JavaScript-string terug. De optionele invoerbron voor bytes kan bijvoorbeeld een ArrayBuffer, een getypeerde array of een DataView zijn. De constructor new TextDecoder(label, options) kiest de codering; standaard is dat "utf-8". Een onbekend label of een label dat verwijst naar de codering replacement veroorzaakt al bij het aanmaken een RangeError.

decoder.fatal en decoder.ignoreBOM zijn alleen-lezen booleaanse eigenschappen. Ze zijn standaard false en worden ingesteld via de constructor, niet via decode(). Bij fatal: false leveren decodeerfouten het vervangingsteken U+FFFD op; bij fatal: true gooit decode() een TypeError. Strikt decoderen maakt de resulterende tekst niet veilig voor gebruik als HTML.

Voor UTF-8, UTF-16LE en UTF-16BE laat ignoreBOM: false een bytevolgordemarkering (BOM) aan het begin weg, terwijl ignoreBOM: true die als U+FEFF in het resultaat bewaart. true schakelt dus de speciale behandeling uit, maar verwijdert de markering niet. Deze optie verandert de codering niet en verwijdert geen U+FEFF verderop in de tekst.

Gebruik bij invoer in blokken dezelfde decoder met { stream: true } zolang er nog bytes worden verwacht. De decoder bewaart zijn toestand en kan een lege string teruggeven terwijl hij op de rest van een teken wacht. Geef het laatste blok door zonder stream: true of sluit af met decode() zonder argumenten. Pas dan veroorzaakt een onvolledige reeks aan het einde een decodeerfout. De volgende onafhankelijke invoer begint met een nieuwe toestand.

TextDecoder hoort bij de Encoding API van het webplatform en is niet ingebouwd in ECMAScript 2024. Controleer de beschikbaarheid in je doelomgeving.

Voorbeelden

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

Resultaat

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

De eerste drie regels tonen de decimale codepunten van `A`, de bewaarde BOM en het vervangingsteken. De regel `split` toont een leeg eerste resultaat en het codepunt van `€`; in de strikte modus veroorzaakt de afgebroken reeks pas bij de afsluitende `decode()` een `TypeError`.

Gerelateerde lessen

  • JavaScript · Les 3 · Gevorderd · Versie: 4

Bronnen