new Uint8ClampedArray() — Methode · JavaScript-Referenz

Signatur

new Uint8ClampedArray(length | typedArray | object | buffer, byteOffset, length)

Beschreibung

Der Konstruktor Uint8ClampedArray() erzeugt ein typisiertes Array, dessen Elemente vorzeichenlose 8-Bit-Ganzzahlen sind. Anders als bei Uint8Array gibt es beim Zuweisen keinen Überlauf: Werte unter 0 werden zu 0, Werte über 255 werden zu 255. Nachkommawerte werden zur nächsten Ganzzahl gerundet, bei genau x,5 zur nächsten geraden Zahl (Round-half-to-even). NaN wird zu 0.

Typisch ist der Einsatz bei der Bildverarbeitung: ImageData.data aus der Canvas-API ist ein Uint8ClampedArray mit RGBA-Werten. Durch das Begrenzen lassen sich Helligkeit, Kontrast oder Filter berechnen, ohne jeden Wert manuell abschneiden zu müssen.

Der Konstruktor kennt mehrere Aufrufformen:

new Uint8ClampedArray() bzw. new Uint8ClampedArray(length) – leeres bzw. mit Nullen gefülltes Array der angegebenen Länge.
new Uint8ClampedArray(typedArray) – kopiert die Werte eines anderen typisierten Arrays (mit Begrenzung).
new Uint8ClampedArray(object) – aus einem Array-ähnlichen oder iterierbaren Objekt.
new Uint8ClampedArray(buffer, byteOffset, length) – eine Sicht auf einen bestehenden ArrayBuffer bzw. SharedArrayBuffer, ohne Daten zu kopieren.

Der Konstruktor darf nur mit new aufgerufen werden; ein Aufruf als normale Funktion wirft einen TypeError.

Parameter

Name	Typ	Default	Beschreibung
$length	number	0	Anzahl der Elemente. Alle Elemente werden mit `0` initialisiert.
$typedArray	TypedArray		Ein anderes typisiertes Array, dessen Werte kopiert und dabei auf 0–255 begrenzt werden. `BigInt64Array`/`BigUint64Array` führen zu einem `TypeError`.
$object	Array\|Iterable\|ArrayLike		Array-ähnliches oder iterierbares Objekt; jeder Wert wird in eine Zahl umgewandelt und begrenzt.
$buffer	ArrayBuffer\|SharedArrayBuffer		Speicherbereich, auf den das neue Array als Sicht zugreift. Änderungen wirken sich auf alle Sichten desselben Puffers aus.
$byteOffset	number	0	Startposition in Bytes innerhalb von `buffer`.
$length	number	bis Pufferende	Anzahl der Elemente der Sicht (nur zusammen mit `buffer`).

Rückgabewert

Typ

Uint8ClampedArray

Beschreibung

Ein neues Uint8ClampedArray-Objekt.

Beispiele

Unterschiedliche Aufrufformen und Begrenzung

const a = new Uint8ClampedArray(3);
console.log(a);

const b = new Uint8ClampedArray([-20, 100, 300, 1.5, 2.5, NaN]);
console.log(b);

// Vergleich mit Uint8Array (Überlauf statt Begrenzung)
console.log(new Uint8Array([300, -20]));

Uint8ClampedArray(3) [0, 0, 0] Uint8ClampedArray(6) [0, 100, 255, 2, 2, 0] Uint8Array(2) [44, 236]

Sicht auf einen ArrayBuffer

const buffer = new ArrayBuffer(8);
const view = new Uint8ClampedArray(buffer, 2, 4);
view.fill(999); // wird auf 255 begrenzt

console.log(view.length);
console.log(new Uint8Array(buffer));

4 Uint8Array(8) [0, 0, 255, 255, 255, 255, 0, 0]

Praxis: Bild aufhellen mit Canvas-ImageData

const canvas = document.querySelector('canvas');
const ctx = canvas.getContext('2d');
const image = ctx.getImageData(0, 0, canvas.width, canvas.height);

// Neues Pixel-Array anlegen – kein manuelles Math.min nötig
const pixels = new Uint8ClampedArray(image.data.length);
for (let i = 0; i < image.data.length; i += 4) {
  pixels[i] = image.data[i] + 60;       // R
  pixels[i + 1] = image.data[i + 1] + 60; // G
  pixels[i + 2] = image.data[i + 2] + 60; // B
  pixels[i + 3] = image.data[i + 3];      // Alpha unverändert
}

ctx.putImageData(new ImageData(pixels, canvas.width, canvas.height), 0, 0);

// Wichtig · Fallstricke

Rundung: Es wird kaufmännisch nicht gerundet, sondern „half to even“: 1.5 → 2, 2.5 → 2. Wer Math.round-Verhalten erwartet, bekommt abweichende Ergebnisse.
Ohne new aufgerufen, wirft der Konstruktor einen TypeError.
Bei der Buffer-Variante wird nicht kopiert: Mehrere Sichten teilen sich denselben Speicher. Zum Kopieren new Uint8ClampedArray(andereSicht) oder slice() verwenden.
Negative oder zu große Längen bzw. ein über das Pufferende hinausreichender Bereich führen zu einem RangeError.
Die Länge ist fest; typisierte Arrays kennen kein push/pop.
Kompatibilität: in allen modernen Browsern und Node.js verfügbar; die Iterable-Variante erfordert ES2015.

Siehe auch

Uint8ClampedArray Uint8Array ArrayBuffer TypedArray ImageData DataView new DisposableStack()