Uint8Array.prototype.setFromBase64()

Метод setFromBase64() экземпляров Uint8Array заполняет этот объект Uint8Array байтами из строки, закодированной в base64, и возвращает объект, указывающий, сколько байтов было прочитано и записано.

Этот метод лучше всего подходит для заполнения предварительно выделенного буфера массива. Если вы хотите просто создать новый объект Uint8Array из строки, закодированной в base64, используйте вместо этого статический метод Uint8Array.fromBase64().

Синтаксис

setFromBase64(string)
setFromBase64(string, options)

Параметры

string

Строка base64, кодирующая байты для записи в Uint8Array. Она должна соответствовать тем же требованиям, что и string параметр метода Uint8Array.fromBase64(). Обратите внимание, что строка считывается только до заполнения массива, поэтому любой некорректный синтаксис base64 после этой точки игнорируется.

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

Объект, настраивающий процесс интерпретации строки base64. Он должен соответствовать тем же требованиям, что и options параметр метода Uint8Array.fromBase64().

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

Объект, содержащий следующие свойства:

read

Количество символов base64, прочитанных из входной строки. Если декодированные данные помещаются в массив, это длина входной строки (включая символы заполнения); в противном случае — длина строки до последнего полного блока из 4 символов, который помещается в массив. Блоки никогда не разделяются, так как оставшиеся биты нельзя частично «вернуть» в base64 без полного повторного кодирования. Если следующий блок не помещается в оставшуюся часть массива, он не будет прочитан целиком, в результате чего последние один или два байта массива не будут записаны.

written

Количество байтов, записанных в Uint8Array. Оно никогда не превышает значение свойства byteLength этого объекта Uint8Array.

Исключения

SyntaxError

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

TypeError

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

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

Примеры

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

В этом примере используются параметры alphabet и lastChunkHandling по умолчанию для декодирования строки base64 в существующий Uint8Array.

const uint8Array = new Uint8Array(16);
const result = uint8Array.setFromBase64("PGI+ TURO PC9i Pg==");
console.log(result); // { read: 19, written: 10 }
console.log(uint8Array);
// Uint8Array(16) [60, 98, 62, 77, 68, 78, 60, 47, 98, 62, 0, 0, 0, 0, 0, 0]

Декодирование длинной строки в небольшой массив

Если строка содержит больше данных, чем может поместиться в массиве, метод запишет только столько байтов, сколько вмещает массив, не отбрасывая ни одного бита.

const uint8Array = new Uint8Array(8);
const result = uint8Array.setFromBase64("PGI+ TURO PC9i Pg==");
console.log(result); // { read: 9, written: 6 }
console.log(uint8Array);
// Uint8Array(8) [60, 98, 62, 77, 68, 78, 0, 0]

Обратите внимание, что последние два байта массива не записываются. Чтобы декодировать эти два байта, нужно прочитать как минимум ещё три символа base64, представляющие 18 бит. Они не помещаются в оставшиеся два байта массива, поэтому можно записать только 2 блока, то есть 6 байт.

Запись данных со смещением

Метод setFromBase64() всегда начинает запись с начала Uint8Array. Чтобы записать данные в середину массива, можно вместо этого записать их в TypedArray.prototype.subarray().

const uint8Array = new Uint8Array(16);
// Start writing at offset 2
const result = uint8Array.subarray(2).setFromBase64("PGI+ TURO PC9i Pg==");
console.log(result); // { read: 19, written: 10 }
console.log(uint8Array);
// Uint8Array(16) [0, 0, 60, 98, 62, 77, 68, 78, 60, 47, 98, 62, 0, 0, 0, 0]

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

Этот пример адаптирован из исходного предложения. Он имитирует API TextDecoder с параметром stream. Обратите внимание на использование lastChunkHandling: "stop-before-partial" для обработки неполных блоков.

class Base64Decoder {
  #extra = "";

  decode(chunk = "", options = {}) {
    const opts = { ...options };
    // match TextEncoder API
    if (opts.stream) {
      opts.lastChunkHandling = "stop-before-partial";
    }
    chunk = this.#extra + chunk;
    this.#extra = "";
    // For simplicity, allocate new memory every time
    // the calculation below is guaranteed to be enough,
    // but may be too much if there is whitespace
    // if you're really concerned about memory, a TextDecoder style API is a bad choice
    let buffer = new Uint8Array(Math.ceil((chunk.length * 3) / 4));
    const { read, written } = buffer.setFromBase64(chunk, opts);
    buffer = buffer.subarray(0, written);
    this.#extra = chunk.slice(read);
    return buffer;
  }
}

const decoder = new Base64Decoder();

console.log(decoder.decode("SG Vsb ", { stream: true }));
// Uint8Array(3) [72, 101, 108]
console.log(decoder.decode("G8gV29ybGR ", { stream: true }));
// Uint8Array(6) [108, 111, 32, 87, 111, 114]
console.log(decoder.decode(""));
// Uint8Array(2) [108, 100]

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

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

См. также

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