База знанияИзпитен център
BGБългарски
Избери език13

CKTIS / JavaScript

TextDecoder: декодиране на байтове, грешки и BOM

Декодирайте байтове до текст в JavaScript и изберете как да се обработват невалидните последователности и началният маркер за реда на байтовете, включително при четене на части.

Версия: Current web platform; runtime support varies

Синтаксис

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() връща низ в JavaScript. Незадължителният вход с байтове може да бъде например ArrayBuffer, типизиран масив или DataView. Конструкторът new TextDecoder(label, options) избира кодирането, по подразбиране "utf-8". Непознат етикет или етикет, който съответства на кодирането replacement, предизвиква RangeError още в конструктора.

decoder.fatal и decoder.ignoreBOM са булеви свойства само за четене. И двете са false по подразбиране и се задават чрез конструктора, а не чрез decode(). При fatal: false грешките при декодиране водят до заместващия знак U+FFFD; при fatal: true методът decode() хвърля TypeError. Строгото декодиране не прави получения текст безопасен за използване като HTML.

При UTF-8, UTF-16LE и UTF-16BE настройката ignoreBOM: false пропуска началния маркер за реда на байтовете (BOM), а ignoreBOM: true го запазва в резултата като U+FEFF. Тоест true изключва специалната обработка, а не премахва самия маркер. Настройката не променя кодирането и не премахва U+FEFF по-нататък в текста.

При вход на части използвайте един и същ декодер с { stream: true }, докато очаквате още байтове. Декодерът запазва състоянието си и може да върне празен низ, докато чака останалите байтове на даден знак. Подайте последната част без stream: true или завършете с decode() без аргументи. Едва тогава непълна последователност в края предизвиква грешка при декодиране. Следващият независим вход започва с ново състояние.

TextDecoder е част от уеб интерфейса Encoding API и не е вграден в ECMAScript 2024. Проверете дали е наличен в целевата среда за изпълнение.

Примери

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

Резултат

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

Първите три реда показват десетичните кодови точки на `A`, запазения BOM и заместващия знак. Редът `split` показва празен първи резултат и кодовата точка на `€`; в строг режим прекъснатата последователност предизвиква `TypeError` едва при последното извикване на `decode()`.

Свързани уроци

  • JavaScript · Урок 3 · Напреднало · Версия: 4

Източници