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

Signatur

TypedArray.prototype.map(callbackFn, thisArg)

Beschreibung

map() ruft callbackFn einmal für jedes Element eines typisierten Arrays (z. B. Uint8Array, Float32Array) auf, und zwar der Reihe nach nach aufsteigendem Index. Die Rückgabewerte landen in einem neuen typisierten Array. Das Ausgangs-Array bleibt dabei unverändert. Der Algorithmus ist derselbe wie bei Array.prototype.map().

Der wichtigste Unterschied zu Array.prototype.map(): Das Ergebnis hat immer denselben Elementtyp wie das Ausgangs-Array. Genauer gesagt wird es über den Symbol.species-Konstruktor erzeugt. Jeder Rückgabewert wird deshalb in den Zieltyp umgewandelt. Bei Uint8Array werden Werte modulo 256 umgebrochen, bei Uint8ClampedArray auf 0–255 begrenzt, und bei Ganzzahltypen fallen Nachkommastellen weg. Werte, die sich nicht in eine Zahl umwandeln lassen, werden zu 0 (bzw. zu NaN bei Float-Arrays).

Typische Einsatzgebiete sind Pixel- und Audioverarbeitung, Skalierung von Messwerten und Transformationen von Binärdaten. Wenn du einen anderen Zieltyp brauchst, z. B. von Uint8Array nach Float32Array, nimm Float32Array.from(source, fn). Und wenn das Ergebnis beliebige Werte wie Strings oder Objekte enthalten soll, wandle das Array zuerst mit Array.from() um.

Parameter

Name	Typ	Default	Beschreibung
$callbackFn Pflicht	(element: number \| bigint, index: number, array: TypedArray) => number \| bigint		Funktion, die für jedes Element ausgeführt wird. Ihr Rückgabewert wird in den Elementtyp des neuen Arrays umgewandelt. Sie erhält `element` (aktueller Wert), `index` (Position) und `array` (das Array, auf dem `map()` aufgerufen wurde).
$thisArg	any	undefined	Wert, der beim Aufruf von `callbackFn` als `this` verwendet wird. Bei Pfeilfunktionen hat er keine Wirkung.

Rückgabewert

Typ

TypedArray

Beschreibung

Ein neues typisiertes Array vom selben Typ und mit derselben Länge wie das Ausgangs-Array. Es enthält die umgewandelten Rückgabewerte von callbackFn.

Beispiele

Werte quadrieren

const zahlen = new Int16Array([1, 4, 9, 16]);
const quadrate = zahlen.map((n) => n * n);

console.log(quadrate);
console.log(quadrate instanceof Int16Array);

Int16Array(4) [1, 16, 81, 256] true

Fallstrick: Überlauf und abgeschnittene Nachkommastellen

const bytes = new Uint8Array([100, 200, 250]);

// Uint8Array bricht Werte modulo 256 um
console.log(bytes.map((b) => b * 2));

// Nachkommastellen fallen weg
console.log(bytes.map((b) => b / 3));

// Uint8ClampedArray begrenzt stattdessen auf 0–255
console.log(Uint8ClampedArray.from(bytes).map((b) => b * 2));

Uint8Array(3) [200, 144, 244] Uint8Array(3) [33, 66, 83] Uint8ClampedArray(3) [200, 255, 255]

Pixeldaten aufhellen (Canvas ImageData)

const canvas = document.createElement('canvas');
canvas.width = canvas.height = 2;
const ctx = canvas.getContext('2d');
ctx.fillStyle = 'rgb(100, 50, 20)';
ctx.fillRect(0, 0, 2, 2);

const { data, width, height } = ctx.getImageData(0, 0, 2, 2);
// Alpha-Kanal (jeder 4. Wert) unverändert lassen
const heller = data.map((wert, i) => (i % 4 === 3 ? wert : wert * 1.5));

ctx.putImageData(new ImageData(heller, width, height), 0, 0);
console.log(heller.slice(0, 4));

Uint8ClampedArray(4) [150, 75, 30, 255]

Anderer Zieltyp: from() statt map()

const rohwerte = new Uint8Array([0, 128, 255]);

// map() würde bei Uint8Array bleiben – daher Float32Array.from
const normiert = Float32Array.from(rohwerte, (v) => v / 255);
console.log(normiert);

// Strings als Ergebnis: vorher in ein normales Array umwandeln
const hex = Array.from(rohwerte, (v) => v.toString(16).padStart(2, '0'));
console.log(hex.join(''));

Float32Array(3) [0, 0.501960813999176, 1] 0080ff

// Wichtig · Fallstricke

Ergebnistyp ist fest: Anders als bei Array.prototype.map() kannst du keine Strings, Objekte oder Werte außerhalb des Wertebereichs zurückgeben, ohne dass sie umgewandelt werden. Das kann zu stillem Datenverlust führen, z. B. durch Überlauf bei Uint8Array oder abgeschnittene Nachkommastellen.
BigInt-Arrays: Bei BigInt64Array und BigUint64Array muss callbackFn einen bigint zurückgeben, also z. B. n * 2n. Gibst du eine number zurück, gibt es einen TypeError.
Das neue Array wird über Symbol.species erzeugt. Unterklassen können dadurch einen anderen Konstruktor festlegen.
Wird das zugrunde liegende ArrayBuffer während der Iteration abgetrennt (detached) oder verkleinert, liefern die betroffenen Indizes undefined. Das neue Array hat aber trotzdem die ursprüngliche Länge.
Für Transformationen direkt im selben Array (ohne neuen Speicher) ist eine for-Schleife mit Zuweisung sparsamer. map() reserviert immer einen neuen Puffer.
Kompatibilität: Unterstützt in allen modernen Browsern und in Node.js (Baseline seit 2015/2016). Im Internet Explorer gibt es die Methode nicht.

Siehe auch

Array.prototype.map() TypedArray.from() TypedArray.prototype.forEach() TypedArray.prototype.filter() TypedArray.prototype.reduce() TypedArray