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[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);

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

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

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

• Поліфіл ArrayBuffer у складі core-js
• Посібник Типізовані масиви JavaScript
• SharedArrayBuffer
• RangeError: invalid array length