ArrayBuffer

Объект ArrayBuffer используется для представления общего буфера необработанных двоичных данных.

Это массив байтов, который часто называют "массивом байтов" в других языках. Вы не можете напрямую изменять содержимое ArrayBuffer; вместо этого вы создаете один из объектов типизированных массивов или объект DataView, который представляет буфер в определенном формате, и используете его для чтения и записи содержимого буфера.

Конструктор ArrayBuffer() создает новый ArrayBuffer указанной длины в байтах. Вы также можете получить буфер массива из существующих данных, например, из строки Base64 или из локального файла.

ArrayBuffer — это передаваемый объект.

Описание

Изменение размера ArrayBuffers

Объекты ArrayBuffer можно сделать изменяемыми, включив опцию maxByteLength при вызове конструктора ArrayBuffer(). Вы можете запросить, является ли ArrayBuffer изменяемым и каков его максимальный размер, получив доступ к его свойствам resizable и maxByteLength соответственно. Вы можете присвоить новый размер изменяемому ArrayBuffer с помощью вызова resize(). Новые байты инициализируются значением 0.

Эти функции делают изменение размера ArrayBuffer более эффективным — в противном случае вам придется создавать копию буфера нового размера. Это также дает JavaScript паритет с WebAssembly в этом отношении (линейная память Wasm может быть изменена с помощью WebAssembly.Memory.prototype.grow()).

Передача ArrayBuffers

Объекты ArrayBuffer можно передавать между различными контекстами выполнения, такими как Web Workers или Service Workers, используя алгоритм структурированного клонирования. Это делается путем передачи ArrayBuffer в качестве передаваемого объекта в вызове Worker.postMessage() или ServiceWorker.postMessage(). В чистом JavaScript вы также можете передать владение памятью от одного ArrayBuffer к другому, используя его метод transfer() или transferToFixedLength().

Когда ArrayBuffer передается, его исходная копия становится отсоединенной — это означает, что она больше не может использоваться. В любой момент времени будет только одна копия ArrayBuffer, которая фактически имеет доступ к базовой памяти. Отсоединенные буферы ведут себя следующим образом:

• byteLength становится 0 (как в буфере, так и в связанных представлениях типизированных массивов).
• Методы, такие как resize() и slice(), вызывают TypeError при вызове. Методы связанных представлений типизированных массивов также вызывают TypeError.

Вы можете проверить, отсоединен ли ArrayBuffer, по его свойству detached.

Конструктор

ArrayBuffer()

Создает новый объект ArrayBuffer.

Статические свойства

ArrayBuffer[Symbol.species]

Конструктор, который используется для создания производных объектов.

Статические методы

ArrayBuffer.isView()

Возвращает true, если arg является одним из представлений ArrayBuffer, таким как объекты типизированных массивов или DataView. В противном случае возвращает false.

Свойства экземпляра

Эти свойства определены в ArrayBuffer.prototype и разделяются всеми экземплярами ArrayBuffer.

ArrayBuffer.prototype.byteLength

Размер ArrayBuffer в байтах. Он устанавливается при создании массива и может быть изменен только с помощью метода ArrayBuffer.prototype.resize(), если ArrayBuffer является изменяемым.

ArrayBuffer.prototype.constructor

Конструктор, который создал объект экземпляра. Для экземпляров ArrayBuffer начальное значение — конструктор ArrayBuffer.

ArrayBuffer.prototype.detached

Только для чтения. Возвращает true, если ArrayBuffer был отсоединен (передан), или false, если нет.

ArrayBuffer.prototype.maxByteLength

Максимальная длина ArrayBuffer в байтах, до которой можно изменить размер этого буфера. Это свойство только для чтения, оно устанавливается при создании массива и не может быть изменено.

ArrayBuffer.prototype.resizable

Только для чтения. Возвращает true, если ArrayBuffer можно изменить, или false, если нет.

ArrayBuffer.prototype[Symbol.toStringTag]

Начальное значение свойства [Symbol.toStringTag] — строка "ArrayBuffer". Это свойство используется в Object.prototype.toString().

Методы экземпляра

ArrayBuffer.prototype.resize()

Изменяет размер ArrayBuffer до указанного размера в байтах.

ArrayBuffer.prototype.slice()

Возвращает новый ArrayBuffer, содержимое которого является копией байтов данного ArrayBuffer от begin (включительно) до end (исключая). Если begin или end отрицательны, они относятся к индексу с конца массива, а не с начала.

ArrayBuffer.prototype.transfer()

Создает новый ArrayBuffer с тем же байтовым содержимым, что и этот буфер, а затем отсоединяет этот буфер.

ArrayBuffer.prototype.transferToFixedLength()

Создает новый не изменяемый ArrayBuffer с тем же байтовым содержимым, что и этот буфер, а затем отсоединяет этот буфер.

Примеры

Создание ArrayBuffer

В этом примере мы создаем буфер размером 8 байт с представлением Int32Array, ссылающимся на буфер:

const buffer = new ArrayBuffer(8);
const view = new Int32Array(buffer);

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

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

См. также

• Polyfill of ArrayBuffer in core-js
• Руководство по типизированным массивам JavaScript
• SharedArrayBuffer
• RangeError: invalid array length