ArrayBuffer

Об'єкт ArrayBuffer (масив-буфер) використовується для представлення узагальненого буфера двійкових даних.

Це масив байтів, який в інших мовах нерідко називають "байтовим масивом". Не можна працювати зі вмістом ArrayBuffer безпосередньо; замість цього слід створювати об'єкти типізованих масивів або об'єкт DataView, які представляють цей буфер у конкретному форматі, і використовувати їх для читання та запису вмісту буфера.

Конструктор ArrayBuffer() створює новий ArrayBuffer із заданою довжиною в байтах. Також можна отримати масив-буфер з наявних даних, наприклад, із рядка Base64 або з локального файлу.

ArrayBuffer – це переносний об'єкт.

Опис

Зміна розміру ArrayBuffer

Об'єкти ArrayBuffer легко можуть мати змінний розмір, завдяки наданню налаштування maxByteLength при виклику конструктора ArrayBuffer(). Дізнатися, чи має ArrayBuffer змінний розмір, і який його максимум, можна шляхом звертання до його властивостей resizable і maxByteLength відповідно. Новий розмір ArrayBuffer змінного розміру можна задати за допомогою виклику resize(). Нові байти ініціалізуються 0.

Завдяки цим можливостям зміна розміру ArrayBuffer ефективніша: без них довелось би створювати копію буфера з новим розміром. Це також дає JavaScript паритет щодо WebAssembly у цьому відношенні (лінійна пам'ять Wasm може змінювати розмір за допомогою WebAssembly.Memory.prototype.grow()).

Перенесення ArrayBuffer

Об'єкти ArrayBuffer можна переносити між різними контекстами виконання, наприклад, вебворкерами чи сервісними воркерами, за допомогою алгоритму структурованого клонування. Це робиться шляхом передачі ArrayBuffer як переносного об'єкта у виклику Worker.postMessage() чи ServiceWorker.postMessage(). У чистому JavaScript також можна передавати власність пам'яті з одного ArrayBuffer до іншого за допомогою його методів transfer() чи transferToFixedLength().

Коли ArrayBuffer переноситься, його вихідна копія стає від'єднаною – це означає, що нею більше не можна скористатися. В будь-яку мить є лише одна копія ArrayBuffer, яка має фактичний доступ до цільової ділянки пам'яті. Від'єднані буфери мають такі властивості:

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

Перевірити, чи є ArrayBuffer від'єднаним, можна за його властивістю detached.

Конструктор

ArrayBuffer()

Створює новий об'єкт ArrayBuffer.

Статичні властивості

ArrayBuffer[@@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[@@toStringTag]

Початковим значенням властивості @@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);

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

Сумісність із браузерами

desktop mobile server
Chrome Edge Firefox Internet Explorer Opera Safari WebView Android Chrome Android Firefox for Android Opera Android Safari on iOS Samsung Internet Deno Node.js
ArrayBuffer
Chrome Full support 7
Edge Full support 12
Firefox Full support 4
Internet Explorer Full support 10
Opera Full support 11.6
Safari Full support 5.1
WebView Android Full support 4
Chrome Android Full support 18
Firefox for Android Full support 4
Opera Android Full support 12
Safari on iOS Full support 4.2
Samsung Internet Full support 1.0
Deno Full support 1.0
Node.js Full support 0.10.0
@@species Chrome Full support 51
Edge Full support 13
Firefox Full support 48
Internet Explorer No support No
Opera Full support 38
Safari Full support 10
WebView Android Full support 51
Chrome Android Full support 51
Firefox for Android Full support 48
Opera Android Full support 41
Safari on iOS Full support 10
Samsung Internet Full support 5.0
Deno Full support 1.0
Node.js Full support 6.5.0
ArrayBuffer() constructor Chrome Full support 7
Edge Full support 12
Firefox Full support 4
Internet Explorer Full support 10
Opera Full support 11.6
Safari Full support 5.1
WebView Android Full support 4
Chrome Android Full support 18
Firefox for Android Full support 4
Opera Android Full support 12
Safari on iOS Full support 4.2
Samsung Internet Full support 1.0
Deno Full support 1.0
Node.js Full support 0.10.0
ArrayBuffer() without new throws
Chrome Full support 7
Edge Full support 14
Firefox Full support 44
Internet Explorer No support No
Opera Full support 15
Safari Full support 5.1
WebView Android Full support 37
Chrome Android Full support 18
Firefox for Android Full support 44
Opera Android Full support 14
Safari on iOS Full support 5
Samsung Internet Full support 1.0
Deno Full support 1.0
Node.js Full support 0.12.0
byteLength Chrome Full support 7
Edge Full support 12
Firefox Full support 4
Internet Explorer Full support 10
Opera Full support 11.6
Safari Full support 5.1
WebView Android Full support 4
Chrome Android Full support 18
Firefox for Android Full support 4
Opera Android Full support 12
Safari on iOS Full support 4.2
Samsung Internet Full support 1.0
Deno Full support 1.0
Node.js Full support 0.10.0
isView Chrome Full support 32
Edge Full support 12
Firefox Full support 29
Internet Explorer Full support 11
Opera Full support 19
Safari Full support 7
WebView Android Full support 37
Chrome Android Full support 32
Firefox for Android Full support 29
Opera Android Full support 19
Safari on iOS Full support 7
Samsung Internet Full support 2.0
Deno Full support 1.0
Node.js Full support 4.0.0
slice Chrome Full support 17
Edge Full support 12
Firefox Full support 12
footnote
Internet Explorer Full support 11
Opera Full support 12.1
Safari Full support 6
WebView Android Full support 4.4
Chrome Android Full support 18
Firefox for Android Full support 14
footnote
Opera Android Full support 12.1
Safari on iOS Full support 6
Samsung Internet Full support 1.0
Deno Full support 1.0
Node.js Full support 0.12.0

Дивіться також