TypedArray.prototype.fill() — Methode · JavaScript-Referenz

Signatur

TypedArray.prototype.fill(value, start, end)

Beschreibung

fill() schreibt einen einzelnen Wert in einen zusammenhängenden Indexbereich eines typisierten Arrays (z. B. Uint8Array, Float32Array). Die Methode arbeitet in-place: Sie verändert das bestehende Array bzw. den zugrunde liegenden ArrayBuffer und gibt dasselbe Array zurück. Deshalb lässt sie sich auch verketten.

Typische Einsatzfälle sind das Initialisieren oder Zurücksetzen von Puffern, z. B. Pixeldaten, Audio-Samples oder Binärprotokolle. Auch zum Löschen eines Bereichs mit 0 oder zum Vorbelegen mit einem Sentinel-Wert wie -1 oder NaN eignet sie sich gut. Die Methode funktioniert im Wesentlichen wie Array.prototype.fill(), ist aber auf typisierte Arrays abgestimmt und meist sehr schnell.

Der Wert wird vor dem Schreiben einmal in den Elementtyp des Arrays umgewandelt. Bei Ganzzahl-Arrays wird er abgeschnitten und modulo gerechnet (Uint8Array: 256 wird zu 0), bei Uint8ClampedArray auf 0–255 begrenzt, bei BigInt64Array/BigUint64Array muss er ein BigInt sein. Negative Werte für start und end zählen vom Ende des Arrays.

Parameter

Name	Typ	Default	Beschreibung
$value Pflicht	number \| bigint		Wert, mit dem gefüllt wird. Er wird in den Elementtyp umgewandelt. Bei `BigInt64Array`/`BigUint64Array` muss es ein `BigInt` sein.
$start	number	0	Startindex (inklusive), wird in eine Ganzzahl umgewandelt. Negative Werte zählen ab `length` rückwärts.
$end	number	this.length	Endindex (exklusive), wird in eine Ganzzahl umgewandelt. Negative Werte zählen ab `length` rückwärts.

Rückgabewert

Typ

TypedArray

Beschreibung

Dasselbe typisierte Array (keine Kopie), nachdem es verändert wurde.

Beispiele

Grundlagen: ganzes Array und Teilbereich füllen

const bytes = new Uint8Array(6);
bytes.fill(7);
console.log(bytes);

bytes.fill(0, 2, 4); // Index 2 und 3
console.log(bytes);

bytes.fill(9, -2); // die letzten zwei Elemente
console.log(bytes);

Uint8Array(6) [7, 7, 7, 7, 7, 7] Uint8Array(6) [7, 7, 0, 0, 7, 7] Uint8Array(6) [7, 7, 0, 0, 9, 9]

Typumwandlung beim Füllen

console.log(new Uint8Array(3).fill(257));        // 257 % 256
console.log(new Uint8ClampedArray(3).fill(300)); // auf 255 begrenzt
console.log(new Int8Array(3).fill(3.9));         // abgeschnitten
console.log(new BigInt64Array(2).fill(5n));

Uint8Array(3) [1, 1, 1] Uint8ClampedArray(3) [255, 255, 255] Int8Array(3) [3, 3, 3] BigInt64Array(2) [5n, 5n]

Praxis: Canvas-Pixelpuffer einfarbig füllen

const width = 4;
const height = 2;
// RGBA als 32-Bit-Wert (Little Endian: 0xAABBGGRR)
const pixels = new Uint32Array(width * height);
const opaqueRed = 0xff0000ff;
pixels.fill(opaqueRed);

// Zweite Zeile transparent machen
pixels.fill(0, width, width * 2);

const rgba = new Uint8ClampedArray(pixels.buffer);
console.log(rgba.slice(0, 4), rgba.slice(16, 20));

Uint8ClampedArray(4) [255, 0, 0, 255] Uint8ClampedArray(4) [0, 0, 0, 0]

Teilansicht (subarray) füllen verändert den gemeinsamen Puffer

const samples = new Float32Array([0.5, 0.8, -0.3, 0.1, 0.9]);
// Bereich 1..3 stummschalten – subarray teilt sich den Puffer
samples.subarray(1, 4).fill(0);
console.log(samples);

Float32Array(5) [0.5, 0, 0, 0, 0.8999999761581421]

// Wichtig · Fallstricke

Verändert das Original: fill() arbeitet in-place und gibt dieselbe Referenz zurück. Wer eine Kopie braucht, ruft vorher slice() auf. Alle Ansichten auf denselben ArrayBuffer (z. B. über subarray() oder DataView) sehen die Änderung ebenfalls.
end ist exklusiv: fill(1, 2, 4) setzt nur die Indizes 2 und 3.
Stille Umwandlung: Werte außerhalb des Wertebereichs führen zu keinem Fehler, sondern werden umgerechnet (Überlauf, Abschneiden oder Begrenzen). NaN wird in Ganzzahl-Arrays zu 0.
BigInt-Arrays: Bei BigInt64Array und BigUint64Array löst eine normale Zahl (fill(1)) einen TypeError aus. Dort ist fill(1n) nötig.
Ist der Puffer abgetrennt (detached, z. B. nach einem Transfer per postMessage), wird ein TypeError ausgelöst.
Ein leerer Bereich (start >= end) ist kein Fehler, dann passiert einfach nichts.
Zum Zurücksetzen auf 0 kann bei frischem Speicher auch ein neues typisiertes Array genügen, denn es ist bereits mit Nullen initialisiert.
Kompatibilität: Die Methode wird von allen modernen Browsern und von Node.js unterstützt (Baseline). Im Internet Explorer fehlt sie.

Siehe auch

Array.prototype.fill() TypedArray.prototype.set() TypedArray.prototype.subarray() TypedArray.prototype.copyWithin() TypedArray.prototype.slice() TypedArray ArrayBuffer