ArrayBuffer.prototype.byteLength — Eigenschaft · JavaScript-Referenz

Signatur

get ArrayBuffer.prototype.byteLength

Beschreibung

Die Eigenschaft byteLength ist ein Getter auf ArrayBuffer.prototype. Sie liefert die Größe des zugrunde liegenden Speicherblocks in Bytes. Diesen Wert legt man beim Erzeugen mit new ArrayBuffer(length) fest. Einen Setter gibt es nicht: Zuweisungen werden im nicht-strikten Modus stillschweigend ignoriert und lösen im strikten Modus einen TypeError aus.

Man braucht byteLength vor allem bei binären Daten, etwa beim Auswerten von fetch-Antworten über response.arrayBuffer(), beim Lesen von Dateien, bei WebSockets, WebGL oder WebAssembly-Speicher. Mit dem Wert kann man Puffergrößen prüfen, Upload-Limits einhalten oder berechnen, wie viele Elemente in eine bestimmte Typed-Array-Sicht passen (z. B. byteLength / 4 für Float32Array).

Seit ES2024 gibt es größenveränderbare Buffer, die mit new ArrayBuffer(length, { maxByteLength }) erzeugt werden. Bei ihnen ändert sich byteLength nach einem Aufruf von resize(). Die feste Obergrenze steht in maxByteLength. Wird ein Buffer abgelöst (detached), etwa durch transfer() oder durch Übertragung mit postMessage, liefert byteLength danach 0.

Rückgabewert

Typ

number

Beschreibung

Eine nicht-negative Ganzzahl: die aktuelle Größe des Buffers in Bytes. Bei einem abgelösten (detached) Buffer ist der Wert 0.

Beispiele

Größe eines neuen Buffers abfragen

const buffer = new ArrayBuffer(16);
console.log(buffer.byteLength);

// Sichten auf denselben Speicher
const ints = new Int32Array(buffer);
console.log(ints.length); // 16 Bytes / 4 Bytes pro Element

// Zuweisung hat keine Wirkung (im strikten Modus: TypeError)
buffer.byteLength = 100;
console.log(buffer.byteLength);

16 4 16

Download-Größe prüfen mit fetch

const MAX_BYTES = 5 * 1024 * 1024; // 5 MiB

const loadBinary = async (url) => {
  const response = await fetch(url);
  const data = await response.arrayBuffer();
  if (data.byteLength > MAX_BYTES) {
    throw new Error(`Datei zu groß: ${data.byteLength} Bytes`);
  }
  console.log(`Geladen: ${(data.byteLength / 1024).toFixed(1)} KiB`);
  return data;
};

loadBinary('/assets/modell.bin').catch(console.error);

Geladen: 42.0 KiB

Größenveränderbarer Buffer (ES2024)

const buf = new ArrayBuffer(8, { maxByteLength: 64 });
console.log(buf.byteLength, buf.maxByteLength, buf.resizable);

buf.resize(32);
console.log(buf.byteLength);

buf.resize(4);
console.log(buf.byteLength);

8 64 true 32 4

byteLength nach transfer() / Detach

const original = new ArrayBuffer(1024);
const moved = original.transfer();

console.log(original.byteLength); // abgelöst
console.log(original.detached);
console.log(moved.byteLength);

0 true 1024

// Wichtig · Fallstricke

Nur lesbar: byteLength hat keinen Setter. Die Größe eines festen Buffers lässt sich nicht nachträglich ändern. Stattdessen legt man einen neuen Buffer an, benutzt transfer(newLength) oder einen größenveränderbaren Buffer mit resize().
Nicht mit length verwechseln: ArrayBuffer hat keine Eigenschaft length, der Ausdruck ergibt undefined. Bei Typed Arrays zählt length die Elemente, byteLength dagegen die Bytes. Außerdem kann typedArray.byteLength kleiner sein als typedArray.buffer.byteLength, wenn die Sicht nur einen Ausschnitt abdeckt (Stichwort byteOffset).
Abgelöste Buffer: Nach postMessage(buf, [buf]), structuredClone mit transfer oder buf.transfer() ist byteLength gleich 0. Das ist eine häufige Fehlerquelle bei Workern.
SharedArrayBuffer hat einen eigenen Getter SharedArrayBuffer.prototype.byteLength. Wendet man den ArrayBuffer-Getter per call auf ein anderes Objekt an, wird ein TypeError ausgelöst.
Kompatibilität: Der Getter selbst funktioniert in allen Browsern und in Node.js. Größenveränderbare Buffer (resize, maxByteLength) und transfer() gibt es erst seit ES2024 (Chrome 111+/114+, Firefox 128+, Safari 16.4+/17.4+, Node.js 20+).

Siehe auch

ArrayBuffer.prototype.maxByteLength ArrayBuffer.prototype.detached ArrayBuffer.prototype.resizable ArrayBuffer[Symbol.species] SharedArrayBuffer.prototype.byteLength