Baza wiedzyCentrum egzaminacyjne
PLPolski
Wybierz język13

CKTIS / JavaScript

TextDecoder: dekodowanie bajtów, błędy i BOM

Dekoduj bajty do tekstu w JavaScripcie, wybierając sposób obsługi niepoprawnych sekwencji i początkowego znacznika BOM, także podczas odczytu porcjami.

Wersja: Current web platform; runtime support varies

Składnia

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

decoder.decode() zwraca ciąg znaków JavaScript. Opcjonalne wejście może być np. obiektem ArrayBuffer, tablicą typowaną lub obiektem DataView. Konstruktor new TextDecoder(label, options) wybiera kodowanie; domyślnie jest to "utf-8". Nieznana etykieta lub etykieta wskazująca kodowanie replacement powoduje RangeError już w konstruktorze.

decoder.fatal i decoder.ignoreBOM to właściwości logiczne tylko do odczytu. Obie mają domyślnie wartość false; ustawia się je w konstruktorze, a nie w decode(). Przy fatal: false błędy dekodowania skutkują wstawieniem znaku zastępczego U+FFFD; przy fatal: true metoda decode() zgłasza TypeError. Tryb ścisły nie sprawia, że zdekodowany tekst staje się bezpieczny do użycia jako HTML.

Dla UTF-8, UTF-16LE i UTF-16BE ustawienie ignoreBOM: false pomija początkowy BOM, a ignoreBOM: true zachowuje go jako U+FEFF w wyniku. Innymi słowy, true wyłącza specjalną obsługę znacznika, zamiast go usuwać. To ustawienie nie zmienia kodowania i nie usuwa U+FEFF występującego dalej w tekście.

Przy dekodowaniu porcjami używaj tego samego dekodera z { stream: true }, dopóki spodziewasz się kolejnych bajtów. Dekoder zachowuje stan i może zwrócić pusty ciąg, czekając na resztę znaku. Podaj ostatnią porcję bez stream: true albo zakończ wywołaniem decode() bez argumentów. Dopiero wtedy niekompletna sekwencja na końcu powoduje błąd dekodowania. Następne niezależne wejście zaczyna się z nowym stanem.

TextDecoder należy do webowego Encoding API i nie jest wbudowanym obiektem ECMAScript 2024. Sprawdź dostępność w docelowym środowisku uruchomieniowym.

Przykłady

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

Wynik

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

Pierwsze trzy wiersze wypisują dziesiętne punkty kodowe: `A`, zachowany BOM i znak zastępczy. Wiersz `split` pokazuje pusty pierwszy wynik i punkt kodowy `€`; niekompletna sekwencja w trybie ścisłym powoduje `TypeError` dopiero przy końcowym `decode()`.

Powiązane lekcje

  • JavaScript · Lekcja 3 · Zaawansowany · Wersja: 4

Źródła