Управление кодировкой UTF-8 в JavaScript: практическое пособие

Расширенные примеры работы с UTF-8

Потоковое декодирование с TextDecoder

При получении данных по частям (например, по сети) важно корректно обрабатывать границы многобайтных символов. TextDecoder поддерживает режим {stream: true}, который сохраняет внутреннее состояние.

const decoder = new TextDecoder('utf-8', {fatal: true, stream: true});

// Первая часть данных
const part1 = new Uint8Array([0xD0, 0x9F]); // начало 'П'
console.log(decoder.decode(part1, {stream: true})); // '' - символ не завершён

// Вторая часть
const part2 = new Uint8Array([0xD1, 0x80, 0xD0, 0xB8]); // 'ри'
console.log(decoder.decode(part2, {stream: true})); // 'При'

// Последняя часть
const part3 = new Uint8Array([0xD0, 0xB5, 0xD1, 0x82]); // 'ет'
console.log(decoder.decode(part3, {stream: false})); // 'Привет'

Работа с суррогатными парами: codePointAt вместо charCodeAt

Символы за пределами Basic Multilingual Plane (U+10000 – U+10FFFF) занимают два суррогата в UTF-16. Метод String.prototype.codePointAt возвращает полную кодовую точку, что упрощает кодирование.

const emoji = '?'; // U+1F600
console.log(emoji.length); // 2 (суррогатная пара)
console.log(emoji.charCodeAt(0).toString(16)); // d83d
console.log(emoji.charCodeAt(1).toString(16)); // de00
console.log(emoji.codePointAt(0).toString(16)); // 1f600

// Кодирование с codePointAt
function utf8EncodeUsingCodePoint(str) {
  const bytes = [];
  for (let cp of str) {
    const code = cp.codePointAt(0);
    if (code <= 0x7F) {
      bytes.push(code);
    } else if (code <= 0x7FF) {
      bytes.push(0xC0 | (code >> 6), 0x80 | (code & 0x3F));
    } else if (code <= 0xFFFF) {
      bytes.push(0xE0 | (code >> 12),
                 0x80 | ((code >> 6) & 0x3F),
                 0x80 | (code & 0x3F));
    } else {
      bytes.push(0xF0 | (code >> 18),
                 0x80 | ((code >> 12) & 0x3F),
                 0x80 | ((code >> 6) & 0x3F),
                 0x80 | (code & 0x3F));
    }
  }
  return new Uint8Array(bytes);
}
console.log(utf8EncodeUsingCodePoint('?')); // Uint8Array(4) [240, 159, 152, 128]

Преобразование hex-строки в UTF-8

Иногда данные передаются в шестнадцатеричном представлении (например, в API). Для декодирования требуется сначала преобразовать hex в массив байт, затем применить TextDecoder.

function hexToUtf8(hexStr) {
  // удаляем пробелы и приводим к единому виду
  const clean = hexStr.replace(/\s/g, '');
  const bytes = new Uint8Array(clean.length / 2);
  for (let i = 0; i < bytes.length; i++) {
    bytes[i] = parseInt(clean.substr(i * 2, 2), 16);
  }
  return new TextDecoder().decode(bytes);
}

const hex = 'D0 9F D1 80 D0 B8 D0 B2 D0 B5 D1 82'; // 'Привет'
console.log(hexToUtf8(hex)); // 'Привет'

Удаление BOM (Byte Order Mark) из UTF-8 данных

Некоторые источники добавляют BOM (0xEF, 0xBB, 0xBF) в начало потока. TextDecoder имеет опцию ignoreBOM: true, которая автоматически пропускает BOM.

const bytesWithBOM = new Uint8Array([0xEF, 0xBB, 0xBF, 0xD0, 0x9F]); // BOM + 'П'
const decoder1 = new TextDecoder('utf-8', {ignoreBOM: true});
console.log(decoder1.decode(bytesWithBOM)); // 'П' (без BOM)

const decoder2 = new TextDecoder('utf-8', {ignoreBOM: false});
console.log(decoder2.decode(bytesWithBOM)); // '\uFEFFП' (BOM как символ)

Сравнение производительности методов кодирования

Для больших строк (сотни тысяч символов) различия существенны. TextEncoder оптимизирован на уровне браузера, а ручное кодирование может быть в 10–20 раз медленнее.

// Измерение времени (упрощённо)
const longString = 'A'.repeat(100000) + '?'.repeat(10000);

console.time('TextEncoder');
new TextEncoder().encode(longString);
console.timeEnd('TextEncoder');

console.time('Manual UTF-8');
stringToUtf8Bytes(longString);
console.timeEnd('Manual UTF-8');

// Примерный результат:
// TextEncoder: 0.5ms
// Manual UTF-8: 12ms

Использование TextEncoder.encodeInto для частичного кодирования

Метод encodeInto позволяет кодировать строку в готовый Uint8Array, контролируя смещение и ограничивая количество записываемых байт. Полезно при работе с буферами фиксированного размера.

const encoder = new TextEncoder();
const dest = new Uint8Array(10); // маленький буфер
const result = encoder.encodeInto('Привет, мир!', dest);
console.log(result.read);   // 7 (сколько символов обработано)
console.log(result.written); // 10 (сколько байт записано)
console.log(dest);          // первые 10 байт строки

// Оставшиеся символы можно дописать в следующий буфер
const rest = encoder.encodeInto('мир!', dest);
console.log(rest);