TypedArray.prototype.length — Eigenschaft · JavaScript-Referenz

Signatur

get TypedArray.prototype.length

Beschreibung

Die Eigenschaft length liefert die Anzahl der Elemente in einem typisierten Array wie Uint8Array, Float32Array oder BigInt64Array. Sie ist eine reine Getter-Eigenschaft auf %TypedArray%.prototype und hat keinen Setter. Anders als bei normalen Arrays lässt sich die Länge also nicht durch eine Zuweisung ändern.

Der Wert wird beim Zugriff berechnet. Er ergibt sich aus der Größe des zugrunde liegenden ArrayBuffer, dem byteOffset und der Elementgröße (BYTES_PER_ELEMENT). Wurde das Array ohne feste Länge auf einem größenveränderbaren ArrayBuffer erzeugt (ES2024, resizable), passt sich length automatisch an, wenn der Puffer mit resize() vergrößert oder verkleinert wird.

Wichtig ist der Unterschied zu byteLength: length zählt Elemente, byteLength zählt Bytes. Bei einem Float64Array mit 4 Elementen ist length gleich 4, byteLength aber 32. Man nutzt length vor allem für Schleifen, zum Prüfen von Grenzen und zum Anlegen passend großer Zielpuffer.

Rückgabewert

Typ

number

Beschreibung

Die Anzahl der Elemente als ganze Zahl ≥ 0. Der Wert ist 0, wenn der zugrunde liegende ArrayBuffer abgetrennt (detached) wurde oder die Ansicht wegen eines verkleinerten Puffers außerhalb der Grenzen liegt.

Beispiele

Elementanzahl vs. Bytegröße

const buffer = new ArrayBuffer(16);
const floats = new Float64Array(buffer);
const bytes = new Uint8Array(buffer);

console.log(floats.length);     // Elemente à 8 Byte
console.log(floats.byteLength); // Bytes
console.log(bytes.length);

2 16 16

Teilansicht mit byteOffset

const buffer = new ArrayBuffer(32);
// Ansicht ab Byte 8 bis zum Pufferende
const tail = new Int32Array(buffer, 8);
// Ansicht mit fester Länge von 3 Elementen
const slice = new Int32Array(buffer, 4, 3);

console.log(tail.length);  // (32 - 8) / 4
console.log(slice.length);

6 3

Iteration über Audiodaten

const samples = new Float32Array([0.1, -0.5, 0.8, -0.2]);

let peak = 0;
for (let i = 0; i < samples.length; i++) {
  peak = Math.max(peak, Math.abs(samples[i]));
}
console.log(`Spitzenwert: ${peak}`);

Spitzenwert: 0.800000011920929

Längenanpassung bei größenveränderbarem ArrayBuffer (ES2024)

const buffer = new ArrayBuffer(8, { maxByteLength: 64 });
const tracking = new Uint16Array(buffer); // ohne feste Länge
const fixed = new Uint16Array(buffer, 0, 2); // feste Länge

console.log(tracking.length, fixed.length);
buffer.resize(32);
console.log(tracking.length, fixed.length);
buffer.resize(2);
console.log(tracking.length, fixed.length); // fixed liegt jetzt außerhalb der Grenzen

4 2 16 2 1 0

// Wichtig · Fallstricke

Nur lesbar: Eine Zuweisung wie ta.length = 10 wird im nicht-strikten Modus stillschweigend ignoriert und löst im Strict Mode einen TypeError aus. Für eine andere Größe muss ein neues typisiertes Array erzeugt werden, z. B. mit subarray(), slice() oder new Uint8Array(n) plus set().
Abgetrennte Puffer: Nach ArrayBuffer.prototype.transfer() oder postMessage mit Transfer-Liste ist der Puffer abgetrennt (detached), und length liefert 0. Es wird kein Fehler geworfen, daher bei Worker-Code auf diesen Fall prüfen.
Elemente statt Bytes: Beim Kopieren in rohe Puffer oder bei der Übergabe an WebGL, WebAudio oder Streams meist byteLength verwenden.
Der Getter wirft einen TypeError, wenn er auf einem Objekt aufgerufen wird, das kein typisiertes Array ist, z. B. Object.getOwnPropertyDescriptor(Object.getPrototypeOf(Int8Array.prototype), 'length').get.call([]).
Größenveränderbare und wachsende SharedArrayBuffer mit automatischer Längenanpassung gibt es erst ab ES2024. In älteren Umgebungen ist length nach der Erzeugung fest. Die Eigenschaft selbst wird von allen Browsern und Node.js unterstützt.

Siehe auch

TypedArray.prototype.byteLength TypedArray.prototype.byteOffset TypedArray.BYTES_PER_ELEMENT TypedArray.prototype.subarray() ArrayBuffer.prototype.resize() TypedArray[Symbol.species]