Btoa: примеры (JAVASCRIPT)

Функция btoa и работа с Base64 в JavaScript

Раздел: Работа с данными, Кодирование

btoa(stringToEncode: string): string

типовые примеры btoa на php, python, mysql btoa изменения javascript примеры расширенные

Основные характеристики функции btoa

Функция btoa() выполняет кодирование строки в формат Base64. Название представляет сокращение от "binary to ASCII". Метод доступен в глобальной области видимости веб-браузеров и в среде Node.js.

Использование функции актуально для преобразования бинарных данных или текста в текстовый формат, который безопасно передавать через сети или хранить в текстовых полях. Распространенные сценарии применения включают кодирование данных для Data URLs, передачу через HTTP-запросы, хранение в localStorage.

Функция принимает один обязательный аргумент:

stringToEncode - строка, подлежащая кодированию. Строка должна содержать только символы из набора Latin1 (ISO-8859-1), то есть каждый символ должен представляться одним байтом.

Возвращаемое значение представляет собой строку ASCII, содержащую закодированные данные в формате Base64. Если входной аргумент не соответствует требованиям, генерируется исключение DOMException с типом 'InvalidCharacterError'.

Базовые примеры применения

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

console.log(btoa('Hello World!'));

SGVsbG8gV29ybGQh

Попытка кодирования символов за пределами Latin1:

try {
  console.log(btoa('Привет'));
} catch(e) {
  console.error(e.message);
}

Failed to execute 'btoa' on 'Window': The string to be encoded contains characters outside of the Latin1 range.

Кодирование пустой строки:

console.log(btoa(''));

Альтернативные методы JavaScript

atob() - выполняет обратное преобразование, декодируя строку Base64 в исходную строку Latin1.

TextEncoder и TextDecoder API - позволяют работать с различными кодировками текста, включая UTF-8. В комбинации с ручным преобразованием в Base64 могут обрабатывать Unicode строки.

Buffer в Node.js - предоставляет методы toString('base64') и from(string, 'base64'). Поддерживает различные кодировки входных данных, включая UTF-8, что делает Buffer предпочтительным выбором в Node.js среде.

Для работы с Unicode в браузере часто применяют комбинацию: btoa(encodeURIComponent(str)) или используют TextEncoder для преобразования строки в Uint8Array с последующим ручным кодированием в Base64.

Реализации в других языках

PHP: Функции base64_encode() и base64_decode(). Работают с бинарными данными и строками, включая многобайтовые кодировки.

echo base64_encode('Hello World!');

SGVsbG8gV29ybGQh

Python: Модуль base64 с методами b64encode() и b64decode(). Принимает и возвращает байтовые строки.

import base64
print(base64.b64encode(b'Hello World!').decode())

SGVsbG8gV29ybGQh

MySQL: Функции TO_BASE64() и FROM_BASE64(). Используются в SQL-запросах для работы со строками.

SELECT TO_BASE64('Hello World!');

SGVsbG8gV29ybGQh

Отличия от JavaScript реализации заключаются в поддержке различных кодировок входных данных и особенностях обработки бинарных данных. Большинство альтернатив не ограничиваются набором Latin1.

Типичные ошибки использования

Попытка закодировать строку с Unicode символами приводит к исключению:

btoa('café'); // символ 'é' выходит за пределы Latin1

Uncaught DOMException: Failed to execute 'btoa' on 'Window'...

Передача нестроковых значений вызывает неявное преобразование, которое может привести к неожиданным результатам:

console.log(btoa(12345));
console.log(btoa(null));

MTIzNDU=
bnVsbA==

Использование возвращаемого значения как окончательного URL без дополнительного экранирования может вызвать проблемы, так как Base64 содержит символы '+' и '/', имеющие специальное значение в URL.

История изменений

Функция btoa долгое время остается стабильной без существенных изменений в спецификациях. Основные обновления связаны с улучшением сообщений об ошибках и обработкой граничных случаев.

В современных браузерах уточнено поведение при передаче аргументов нестрокового типа - происходит автоматическое преобразование к строке перед кодированием.

В Node.js функция была добавлена в глобальную область видимости для совместимости с браузерным API, хотя изначально отсутствовала. Рекомендуется использовать Buffer для работы с Base64 в Node.js.

Расширенные примеры применения

Создание Data URL для изображения:

Пример javascript

const svg = '';
const dataUrl = 'data:image/svg+xml;base64,' + btoa(svg);
console.log(dataUrl.substring(0, 80) + '...');

data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIxMDAiIGhlaWdodD0iM...

Кодирование JSON с предварительным преобразованием Unicode:

Пример javascript

function encodeUnicode(str) {
  return btoa(encodeURIComponent(str).replace(/%([0-9A-F]{2})/g, (match, p1) => {
    return String.fromCharCode('0x' + p1);
  }));
}
const json = JSON.stringify({ name: 'Иван', age: 30 });
console.log(encodeUnicode(json));

eyJuYW1lIjoi0JjQstCw0L0iLCJhZ2UiOjMwfQ==

Постепенное кодирование больших данных:

Пример javascript

function encodeInChunks(text, chunkSize = 100) {
  const result = [];
  for (let i = 0; i < text.length; i += chunkSize) {
    const chunk = text.substring(i, i + chunkSize);
    result.push(btoa(chunk));
  }
  return result;
}
console.log(encodeInChunks('Long text that needs chunk processing', 10));

['TG9uZyB0ZXh0IH', 'RoYXQgbmVlZHMg', 'Y2h1bmsgcHJvY2', 'Vzc2luZw==']

Сравнение производительности разных подходов к кодированию:

Пример javascript

const testData = 'A'.repeat(10000);
console.time('btoa');
const encoded = btoa(testData);
console.timeEnd('btoa');
console.log('Длина результата:', encoded.length);

btoa: 0.5ms
Длина результата: 13336

JS btoa function comments

Btoa Creates a base-64 encoded ASCII string from a binary string.