ArrayBuffer

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since July 2015.

Das ArrayBuffer-Objekt wird verwendet, um einen generischen, rohen binären Datenpuffer darzustellen.

Es ist ein Array von Bytes, das in anderen Sprachen oft als "Byte-Array" bezeichnet wird. Sie können den Inhalt eines ArrayBuffer nicht direkt manipulieren; stattdessen erstellen Sie eines der typisierten Array-Objekte oder ein DataView-Objekt, das den Puffer in einem bestimmten Format darstellt, und verwenden dieses, um den Inhalt des Puffers zu lesen und zu schreiben.

Der ArrayBuffer()-Konstruktor erstellt einen neuen ArrayBuffer mit der angegebenen Länge in Bytes. Sie können auch einen Array-Puffer aus bestehenden Daten erhalten, z. B. aus einem Base64-String oder aus einer lokalen Datei.

ArrayBuffer ist ein transferierbares Objekt.

Beschreibung

Resizing von ArrayBuffers

ArrayBuffer-Objekte können durch Hinzufügen der Option maxByteLength beim Aufruf des ArrayBuffer()-Konstruktors vergrößerbar gemacht werden. Sie können abfragen, ob ein ArrayBuffer vergrößerbar ist und wie groß seine maximale Größe ist, indem Sie auf seine resizable- und maxByteLength-Eigenschaften zugreifen. Sie können einem vergrößerbaren ArrayBuffer mit einem Aufruf von resize() eine neue Größe zuweisen. Neue Bytes werden auf 0 initialisiert.

Diese Funktionen machen das Vergrößern von ArrayBuffers effizienter — andernfalls müssten Sie eine Kopie des Puffers mit neuer Größe erstellen. Außerdem wird JavaScript in dieser Hinsicht mit WebAssembly gleichgestellt (Wasm lineare Speicher können mit WebAssembly.Memory.prototype.grow() vergrößert werden).

Übertragen von ArrayBuffers

ArrayBuffer-Objekte können zwischen verschiedenen Ausführungskontexten, wie Web Workers oder Service Workers, unter Verwendung des strukturierten Klon-Algorithmus übertragen werden. Dies erfolgt durch die Übergabe des ArrayBuffer als transferierbares Objekt in einem Aufruf von Worker.postMessage() oder ServiceWorker.postMessage(). In purem JavaScript können Sie auch das Eigentum des Speichers von einem ArrayBuffer zu einem anderen mit seinen transfer() oder transferToFixedLength()-Methoden übertragen.

Wenn ein ArrayBuffer übertragen wird, wird seine ursprüngliche Kopie abgetrennt — das bedeutet, sie ist nicht mehr nutzbar. Zu jedem Zeitpunkt wird es nur eine Kopie des ArrayBuffer geben, die tatsächlich Zugriff auf den zugrunde liegenden Speicher hat. Abgetrennte Buffer verhalten sich folgendermaßen:

  • byteLength wird 0 (sowohl im Puffer als auch in den zugehörigen typisierten Array-Ansichten).
  • Methoden, wie resize() und slice(), lösen einen TypeError aus, wenn sie aufgerufen werden. Die Methoden der assoziierten typisierten Array-Ansichten werfen ebenfalls einen TypeError.

Sie können überprüfen, ob ein ArrayBuffer abgetrennt ist, anhand seiner detached-Eigenschaft.

Konstruktor

ArrayBuffer()

Erstellt ein neues ArrayBuffer-Objekt.

Statische Eigenschaften

ArrayBuffer[Symbol.species]

Die Konstruktionsfunktion, die verwendet wird, um abgeleitete Objekte zu erstellen.

Statische Methoden

ArrayBuffer.isView()

Gibt true zurück, wenn arg eine der ArrayBuffer-Ansichten ist, wie z. B. typisierte Array-Objekte oder ein DataView. Gibt ansonsten false zurück.

Instanz-Eigenschaften

Diese Eigenschaften sind auf ArrayBuffer.prototype definiert und werden von allen ArrayBuffer-Instanzen geteilt.

ArrayBuffer.prototype.byteLength

Die Größe, in Bytes, des ArrayBuffer. Diese wird beim Erstellen des Arrays festgelegt und kann nur geändert werden, wenn der ArrayBuffer vergrößerbar ist, mit der Methode ArrayBuffer.prototype.resize().

ArrayBuffer.prototype.constructor

Die Konstruktionsfunktion, die das Instanzobjekt erstellt hat. Für ArrayBuffer-Instanzen ist der Anfangswert der ArrayBuffer-Konstruktor.

ArrayBuffer.prototype.detached

Nur-Lesen. Gibt true zurück, wenn der ArrayBuffer abgetrennt (übertragen) wurde, ansonsten false.

ArrayBuffer.prototype.maxByteLength

Die nur-lesbare maximale Länge, in Bytes, auf die der ArrayBuffer vergrößert werden kann. Diese wird beim Erstellen des Arrays festgelegt und kann nicht geändert werden.

ArrayBuffer.prototype.resizable

Nur-Lesen. Gibt true zurück, wenn der ArrayBuffer vergrößerbar ist, ansonsten false.

ArrayBuffer.prototype[Symbol.toStringTag]

Der Anfangswert der [Symbol.toStringTag]-Eigenschaft ist der String "ArrayBuffer". Diese Eigenschaft wird in Object.prototype.toString() verwendet.

Instanz-Methoden

ArrayBuffer.prototype.resize()

Ändert die Größe des ArrayBuffer auf die angegebene Größe, in Bytes.

ArrayBuffer.prototype.slice()

Gibt einen neuen ArrayBuffer zurück, dessen Inhalt eine Kopie der Bytes dieses ArrayBuffer von begin (inclusive) bis end (exklusiv) ist. Wenn entweder begin oder end negativ ist, bezieht es sich auf einen Index vom Ende des Arrays, im Gegensatz zum Anfang.

ArrayBuffer.prototype.transfer()

Erstellt einen neuen ArrayBuffer mit demselben Byteinhalt wie dieser Puffer und trennt dann diesen Puffer ab.

ArrayBuffer.prototype.transferToFixedLength()

Erstellt einen neuen, nicht vergrößerbaren ArrayBuffer mit demselben Byteinhalt wie dieser Puffer und trennt dann diesen Puffer ab.

Beispiele

Erstellen eines ArrayBuffers

In diesem Beispiel erstellen wir einen 8-Byte-Puffer mit einer Int32Array-Ansicht, die sich auf den Puffer bezieht:

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

Spezifikationen

Specification
ECMAScript Language Specification
# sec-arraybuffer-objects

Browser-Kompatibilität

BCD tables only load in the browser

Siehe auch