Uint8Array.fromBase64()

Статический метод Uint8Array.fromBase64() создаёт новый объект Uint8Array из строки, закодированной в base64.

Этот метод следует предпочесть Window.atob(), поскольку он возвращает массив байтов, с которым легче работать, чем со строкой, содержащей необработанные байты, если только декодированные двоичные данные на самом деле не предназначены для использования в качестве текста ASCII. Если у вас уже выделен буфер массива и вы хотите его заполнить, используйте вместо этого метод экземпляра Uint8Array.prototype.setFromBase64().

Синтаксис

Uint8Array.fromBase64(string)
Uint8Array.fromBase64(string, options)

Параметры

string

Строка base64, кодирующая байты для преобразования в Uint8Array. Строка должна содержать только символы алфавита base64, который включает A–Z, a–z, 0–9, и два специальных символа, которые либо + и / (при использовании alphabet: "base64" в options), либо - и _ (при использовании alphabet: "base64url" в options). В конце могут быть символы заполнения =. Любые символы пробела ASCII внутри строки игнорируются.

options Необязательно

Объект, настраивающий процесс интерпретации строки base64. Он может содержать следующие свойства:

alphabet Необязательно

Строка, указывающая используемый алфавит base64. Это может быть одно из следующего:

"base64" (по умолчанию)

Принимает ввод, закодированный с использованием стандартного алфавита base64, в котором используются + и /.

"base64url"

Принимает ввод, закодированный с использованием URL-безопасного алфавита base64, в котором используются - и _.

lastChunkHandling Необязательно

Строка, указывающая, как обрабатывать последний фрагмент строки base64. Поскольку каждые 4 символа в base64 кодируют 3 байта, строка разделяется на фрагменты по 4 символа. Если последний фрагмент содержит менее 4 символов, его необходимо обрабатывать по-другому. Это может быть одно из следующего:

"loose" (по умолчанию)

Последний фрагмент может состоять из 2 или 3 символов base64, либо иметь длину ровно 4 символа с символами заполнения =. Последний фрагмент декодируется и добавляется к результату.

"strict"

Последний фрагмент должен иметь длину ровно 4 символа с символами заполнения =. Кроме того, биты переполнения (конечные биты из последнего символа base64, которые не представляют никаких данных) должны быть равны 0. Последний фрагмент декодируется и добавляется к результату.

"stop-before-partial"

Если последний фрагмент имеет длину ровно 4 символа с символами заполнения =, то он декодируется и добавляется к результату. В противном случае последний частичный фрагмент игнорируется (но если он содержит один символ base64, за которым следует =, то все равно выбрасывается ошибка синтаксиса). Это полезно, если строка поступает из потока и последний фрагмент еще не завершен. Чтобы узнать, сколько символов ввода было прочитано, используйте вместо этого Uint8Array.prototype.setFromBase64() (связанная страница также содержит пример потокового декодирования с использованием "stop-before-partial").

Возвращаемое значение

Новый объект Uint8Array, содержащий декодированные байты из строки, закодированной в base64.

Исключения

SyntaxError

Выбрасывается, если входная строка содержит символы вне указанного алфавита или если последний фрагмент не удовлетворяет параметру lastChunkHandling.

TypeError

Выбрасывается в одном из следующих случаев:

• Входная строка не является строкой.
• Объект options не является объектом или undefined.
• Параметры не соответствуют ожидаемым значениям или undefined.

Примеры

Декодирование строки base64

В этом примере используются параметры alphabet и lastChunkHandling по умолчанию для декодирования строки base64. Обратите внимание, что:

• Пробел в строке игнорируется.
• Строка содержит 14 символов base64, что не кратно 4. Это допустимо и может быть декодировано только с помощью lastChunkHandling: "loose".
• Последний фрагмент, Ph, заканчивается символом h, который в base64 является 0b100001, поэтому последние 0001 бита являются «битами переполнения» и игнорируются. Это допустимо и может быть декодировано только с помощью lastChunkHandling: "loose".

const uint8Array = Uint8Array.fromBase64("PGI+ TURO PC9i Ph");
console.log(uint8Array); // Uint8Array(10) [60, 98, 62, 77, 68, 78, 60, 47, 98, 62]

Декодирование URL-безопасной строки base64

В этом примере используется опция alphabet для декодирования URL-безопасной строки base64.

const uint8Array = Uint8Array.fromBase64("PGI-TUROPC9iPg", {
  alphabet: "base64url",
});
console.log(uint8Array); // Uint8Array(10) [60, 98, 62, 77, 68, 78, 60, 47, 98, 62]

Декодирование строки base64 со строгой обработкой последнего фрагмента

В этом примере используется опция lastChunkHandling для декодирования строки base64, где последний фрагмент должен иметь длину ровно 4 символа с символами заполнения =, а биты переполнения должны быть равны 0.

const array1 = Uint8Array.fromBase64("PGI+ TURO PC9i Pg==", {
  lastChunkHandling: "strict",
});
console.log(array1); // Uint8Array(10) [60, 98, 62, 77, 68, 78, 60, 47, 98, 62]

const array2 = Uint8Array.fromBase64("PGI+ TURO PC9i Ph==", {
  lastChunkHandling: "strict",
});
// Throws a SyntaxError because h is 0b100001, where the last 4 bits are not 0

const array3 = Uint8Array.fromBase64("PGI+ TURO PC9i Pg", {
  lastChunkHandling: "strict",
});
// Throws a SyntaxError because the last chunk is not exactly 4 characters long

Декодирование строки base64 с частичной обработкой последнего фрагмента

В этом примере используется опция lastChunkHandling для декодирования строки base64, игнорируя любой частичный последний фрагмент.

// The last chunk is complete
const array1 = Uint8Array.fromBase64("PGI+ TURO PC9i", {
  lastChunkHandling: "stop-before-partial",
});
console.log(array1); // Uint8Array(9) [60, 98, 62, 77, 68, 78, 60, 47, 98]

// The last chunk is also complete with padding
const array2 = Uint8Array.fromBase64("PGI+ TURO PC9i Pg==", {
  lastChunkHandling: "stop-before-partial",
});
console.log(array2); // Uint8Array(10) [60, 98, 62, 77, 68, 78, 60, 47, 98, 62]

// The last chunk is partial; it's ignored
const array3 = Uint8Array.fromBase64("PGI+ TURO PC9i Pg", {
  lastChunkHandling: "stop-before-partial",
});
console.log(array3); // Uint8Array(9) [60, 98, 62, 77, 68, 78, 60, 47, 98]

// The last chunk is partial with padding; it's still ignored
const array4 = Uint8Array.fromBase64("PGI+ TURO PC9i Pg=", {
  lastChunkHandling: "stop-before-partial",
});
console.log(array4); // Uint8Array(9) [60, 98, 62, 77, 68, 78, 60, 47, 98]

// The last chunk is partial, but it contains one base64 character followed by `=`
const array5 = Uint8Array.fromBase64("PGI+ TURO PC9i P=", {
  lastChunkHandling: "stop-before-partial",
});
// Throws a SyntaxError because this cannot possibly be part of a valid base64 string

Спецификации

Совместимость с браузерами

См. также

• Полифил Uint8Array.fromBase64 в core-js
• полифил es-shims Uint8Array.fromBase64
• Uint8Array
• Uint8Array.prototype.setFromBase64()
• Uint8Array.prototype.toBase64()
• Window.atob()