new ArrayBuffer() — Methode · JavaScript-Referenz

Signatur

new ArrayBuffer(length, options)

Beschreibung

Der Konstruktor new ArrayBuffer() reserviert einen zusammenhängenden Speicherblock für rohe Binärdaten. Die Länge gibst du in Bytes an. Alle Bytes sind anfangs 0. Auf den Inhalt greifst du nicht direkt zu, sondern über eine Sicht (View): ein typisiertes Array wie Uint8Array oder Float32Array oder einen DataView.

Du brauchst ArrayBuffer immer dann, wenn du mit Binärformaten arbeitest. Typische Fälle sind das Parsen von Dateiköpfen, Netzwerkprotokolle, WebSockets mit binaryType = "arraybuffer", WebGL-/WebGPU-Puffer, WebAssembly-Speicher und Audiodaten. Mehrere Views können sich denselben Puffer teilen und dieselben Bytes unterschiedlich auslegen.

Seit ES2024 kannst du über options.maxByteLength einen größenveränderbaren Puffer anlegen. Ein solcher Puffer lässt sich später mit resize() bis zur angegebenen Obergrenze vergrößern oder verkleinern. Das ist praktisch für wachsende Datenströme, weil du nicht jedes Mal neu anlegen und kopieren musst.

ArrayBuffer kannst du nur mit new aufrufen. Ein Aufruf als normale Funktion wirft einen TypeError.

Parameter

Name	Typ	Default	Beschreibung
$length Pflicht	number	0	Größe des Puffers in Bytes. Der Wert wird in eine ganze Zahl umgewandelt (`ToIndex`). Negative Werte oder Werte über der Maximalgröße lösen einen `RangeError` aus.
$options	{ maxByteLength?: number }	undefined	Optionales Objekt. Gibst du `maxByteLength` an, wird der Puffer größenveränderbar. Er kann dann per `resize()` bis zu dieser Byte-Grenze wachsen. `length` darf nicht größer als `maxByteLength` sein.

Rückgabewert

Typ

ArrayBuffer

Beschreibung

Ein neues ArrayBuffer-Objekt der angegebenen Größe, bei dem alle Bytes auf 0 stehen. Mit maxByteLength ist resizable gleich true.

Beispiele

Puffer anlegen und über eine View beschreiben

const buffer = new ArrayBuffer(8);
const bytes = new Uint8Array(buffer);

bytes[0] = 255;
bytes[1] = 16;

console.log(buffer.byteLength);
console.log(bytes);

8 Uint8Array(8) [255, 16, 0, 0, 0, 0, 0, 0]

Binären Header mit DataView schreiben und lesen

// 12-Byte-Header: Magic (uint32), Version (uint16), Flags (uint16), Länge (uint32)
const header = new ArrayBuffer(12);
const view = new DataView(header);

view.setUint32(0, 0x89504e47);      // Big Endian (Standard)
view.setUint16(4, 2);
view.setUint16(6, 0b101);
view.setUint32(8, 1024, true);       // Little Endian

console.log(view.getUint32(0).toString(16));
console.log(view.getUint16(4), view.getUint32(8, true));

89504e47 2 1024

Größenveränderbarer Puffer (ES2024)

const buf = new ArrayBuffer(4, { maxByteLength: 16 });
const view = new Uint8Array(buf); // längenverfolgende View

console.log(buf.resizable, buf.byteLength, view.length);

buf.resize(12);
console.log(buf.byteLength, view.length);

try {
  buf.resize(32);
} catch (err) {
  console.log(err.name);
}

true 4 4 12 12 RangeError

Mehrere Views auf denselben Speicher

const buffer = new ArrayBuffer(4);
const asFloat = new Float32Array(buffer);
const asBytes = new Uint8Array(buffer);

asFloat[0] = 1.0;
console.log([...asBytes]); // auf Little-Endian-Systemen

[0, 0, 128, 63]

// Wichtig · Fallstricke

Nur mit new: ArrayBuffer(8) ohne new wirft einen TypeError.
Kein direkter Zugriff: buffer[0] liefert undefined. Lesen und Schreiben geht nur über typisierte Arrays oder DataView.
RangeError: Kommt bei negativer Länge, bei length > maxByteLength oder wenn der Speicher nicht reserviert werden kann. Sehr große Puffer können auch bei gültigen Werten scheitern.
Endianness: Typisierte Arrays verwenden die Byte-Reihenfolge der Plattform, in der Praxis fast immer Little Endian. Für Dateiformate und Netzwerkprotokolle ist DataView mit ausdrücklichem Endian-Parameter die sichere Wahl.
Übertragung: Nach postMessage(buf, [buf]) oder buf.transfer() ist der ursprüngliche Puffer detached, also abgetrennt. byteLength ist dann 0, und Zugriffe über Views schlagen fehl.
Kompatibilität: Der einfache Konstruktor funktioniert in allen Browsern und in Node.js. maxByteLength und resize() gibt es erst ab ES2024 (Chrome 111+, Firefox 128+, Safari 16.4+, Node.js 20+). Für geteilten Speicher zwischen Workern gibt es SharedArrayBuffer. Er setzt Cross-Origin-Isolation voraus (COOP/COEP-Header).

Siehe auch

ArrayBuffer ArrayBuffer.prototype.slice() ArrayBuffer.prototype.resize() ArrayBuffer.prototype.transfer() ArrayBuffer.isView() DataView Uint8Array SharedArrayBuffer