TypedArray.prototype.byteLength — Eigenschaft · JavaScript-Referenz

Signatur

get TypedArray.prototype.byteLength

Beschreibung

byteLength ist eine schreibgeschützte Zugriffseigenschaft (Getter) auf TypedArray.prototype. Sie gibt an, wie viele Bytes des zugrunde liegenden ArrayBuffer das typisierte Array belegt. Der Wert entspricht immer length * BYTES_PER_ELEMENT, also etwa length * 4 bei einem Float32Array.

Wichtig ist der Unterschied zu buffer.byteLength: Ein typisiertes Array kann nur einen Ausschnitt eines Puffers darstellen (über byteOffset und length). byteLength gibt dann nur die Größe dieses Ausschnitts zurück und nicht die Größe des gesamten Puffers.

Die Eigenschaft braucht man vor allem bei Binärprotokollen, beim Kopieren in andere Puffer (set(), DataView), bei WebGL/WebGPU-Puffergrößen, bei der Übertragung mit postMessage sowie beim Berechnen von Offsets für aufeinanderfolgende Datenblöcke.

Wird der Puffer abgelöst (detached, z. B. nach einem Transfer), ist byteLength gleich 0. Bei längenverfolgenden Ansichten auf einen größenveränderbaren ArrayBuffer (ES2024) passt sich der Wert automatisch an, wenn der Puffer mit resize() vergrößert oder verkleinert wird.

Rückgabewert

Typ

number

Beschreibung

Anzahl der Bytes, die das typisierte Array belegt (nicht negative Ganzzahl). 0, wenn der Puffer abgelöst wurde oder die Ansicht außerhalb eines verkleinerten, größenveränderbaren Puffers liegt.

Beispiele

Bytegröße verschiedener Array-Typen

const i8 = new Int8Array(10);
const f32 = new Float32Array(10);
const f64 = new Float64Array(10);

console.log(i8.byteLength);  // 10 × 1
console.log(f32.byteLength); // 10 × 4
console.log(f64.byteLength); // 10 × 8
console.log(f32.byteLength === f32.length * Float32Array.BYTES_PER_ELEMENT);

10 40 80 true

Ausschnitt eines Puffers vs. Gesamtpuffer

const buffer = new ArrayBuffer(64);

// Ansicht ab Byte 16 mit 8 Elementen à 2 Bytes
const view = new Uint16Array(buffer, 16, 8);

console.log(buffer.byteLength); // Gesamter Puffer
console.log(view.byteLength);   // Nur der Ausschnitt
console.log(view.byteOffset);

64 16 16

Mehrere Datenblöcke hintereinander in einen Puffer packen

const positions = new Float32Array([0, 0, 1, 1, 2, 2]);
const indices = new Uint16Array([0, 1, 2]);

// Gesamtgröße aus den byteLength-Werten berechnen
const total = positions.byteLength + indices.byteLength;
const out = new Uint8Array(total);

out.set(new Uint8Array(positions.buffer, positions.byteOffset, positions.byteLength), 0);
out.set(new Uint8Array(indices.buffer, indices.byteOffset, indices.byteLength), positions.byteLength);

console.log(`Paketgröße: ${out.byteLength} Bytes`);

Paketgröße: 30 Bytes

Abgelöster und größenveränderbarer Puffer

// Nach einem Transfer ist die Ansicht leer
const data = new Uint8Array(1024);
const moved = structuredClone(data.buffer, { transfer: [data.buffer] });
console.log(data.byteLength, moved.byteLength);

// Längenverfolgende Ansicht auf einen resizable ArrayBuffer (ES2024)
const rab = new ArrayBuffer(8, { maxByteLength: 32 });
const tracking = new Int32Array(rab);
console.log(tracking.byteLength);
rab.resize(24);
console.log(tracking.byteLength);

0 1024 8 24

// Wichtig · Fallstricke

Nur lesbar: Es gibt keinen Setter. Eine Zuweisung wie arr.byteLength = 8 wird im nicht-strikten Modus stillschweigend ignoriert und hat im strikten Modus ebenfalls keine Wirkung (die Eigenschaft ist ein geerbter Getter). Die Größe ändert man nur durch ein neues Array oder, bei größenveränderbaren Puffern, mit ArrayBuffer.prototype.resize().
Nicht mit buffer.byteLength verwechseln: Bei Ansichten mit byteOffset oder bei subarray() teilen sich mehrere Arrays einen Puffer. Wer arr.buffer komplett weiterreicht, überträgt womöglich viel mehr Daten als gedacht. Für exakte Kopien byteOffset und byteLength verwenden oder slice() nutzen.
Nicht mit length verwechseln: length zählt Elemente, byteLength zählt Bytes. Nur bei Int8Array, Uint8Array und Uint8ClampedArray sind beide gleich.
Wird der Getter auf einem Objekt aufgerufen, das kein typisiertes Array ist (z. B. über Object.getOwnPropertyDescriptor(...).get.call({})), entsteht ein TypeError.
Bei abgelösten Puffern ist der Wert 0 und es wird kein Fehler ausgelöst. Deshalb vor der Weiterverarbeitung übertragener Daten prüfen.
Kompatibilität: Wird seit ES2015 von allen modernen Browsern und von Node.js unterstützt. Das Verhalten mit größenveränderbaren ArrayBuffers gibt es erst seit ES2024 (Chrome 111+, Firefox 128+, Safari 16.4+, Node.js 20+).

Siehe auch

TypedArray.prototype.length TypedArray.prototype.byteOffset TypedArray.prototype.buffer TypedArray.BYTES_PER_ELEMENT ArrayBuffer.prototype.byteLength ArrayBuffer.prototype.resize() TypedArray.prototype.subarray() DataView