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