Signatur
Beschreibung
Uint8ClampedArray ist ein typisiertes Array, das jedes Element als vorzeichenlose 8-Bit-Ganzzahl (Byte) speichert. Im Gegensatz zu Uint8Array werden Werte außerhalb des Bereichs 0–255 nicht über Modulo-Arithmetik gewickelt, sondern geclampd: Werte kleiner als 0 werden auf 0 gesetzt, Werte größer als 255 auf 255. Dezimalzahlen werden dabei gerundet.
Der häufigste Einsatzbereich ist die Canvas-2D-API: ImageData.data ist ein Uint8ClampedArray, das die RGBA-Pixeldaten eines Canvas-Elements enthält. Jedes Pixel belegt vier aufeinanderfolgende Elemente (R, G, B, A). Das Clamping stellt sicher, dass ungültige Farbwerte nie in ungültige Byte-Werte verwandelt werden – ohne manuelle Überprüfung.
Wie alle typisierten Arrays basiert Uint8ClampedArray auf einem ArrayBuffer und bietet direkten, performanten Zugriff auf binäre Daten. Es unterstützt die üblichen Array-Methoden (map, filter, forEach usw.) sowie Slice- und Subarray-Operationen.
- Elementgröße: 1 Byte pro Element (
Uint8ClampedArray.BYTES_PER_ELEMENT === 1) - Wertebereich: 0–255 (geclampd, nicht gewickelt)
- Runden: Dezimalwerte werden auf die nächste gerade Zahl gerundet (Banker's Rounding)
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $length | number | Anzahl der Elemente. Erstellt ein nullinitialisiertes Array mit der angegebenen Länge. | |
| $typedArray | TypedArray | Ein anderes typisiertes Array, dessen Werte kopiert und geclampd werden. | |
| $object | ArrayLike|Iterable | Ein array-ähnliches oder iterierbares Objekt, aus dem die Werte übernommen werden. | |
| $buffer | ArrayBuffer|SharedArrayBuffer | Ein bestehender ArrayBuffer, auf dem das typisierte Array aufgesetzt wird. |
|
| $byteOffset | number | 0 | Byte-Versatz im ArrayBuffer, ab dem das Array beginnt. Muss ein Vielfaches von BYTES_PER_ELEMENT (1) sein. |
| $length | number | Anzahl der Elemente im Array-View auf den ArrayBuffer. |
Rückgabewert
Uint8ClampedArray-Instanz.Beispiele
Basis: Clamping-Verhalten
// Werte außerhalb 0–255 werden begrenzt
const arr = new Uint8ClampedArray([-10, 0, 128, 255, 300, 1.7, 1.5]);
console.log(arr[0]); // 0 (negativ → 0)
console.log(arr[4]); // 255 (> 255 → 255)
console.log(arr[5]); // 2 (1.7 wird auf 2 gerundet)
console.log(arr[6]); // 2 (1.5 → Banker's Rounding → 2)
// Vergleich mit Uint8Array (Wrapping)
const wrapped = new Uint8Array([300]);
console.log(wrapped[0]); // 44 (300 % 256 = 44)
console.log(arr[4]); // 255 (geclampd)Canvas-Pixelmanipulation: Bild aufhellen
const canvas = document.createElement('canvas');
canvas.width = 4;
canvas.height = 1;
const ctx = canvas.getContext('2d');
// Einen roten Pixel setzen
ctx.fillStyle = 'red';
ctx.fillRect(0, 0, 1, 1);
const imageData = ctx.getImageData(0, 0, canvas.width, canvas.height);
const data = imageData.data; // Uint8ClampedArray
// Alle Pixel um 50 aufhellen (Alpha unberührt lassen)
for (let i = 0; i < data.length; i += 4) {
data[i] += 50; // R — Clamping auf 255 automatisch
data[i + 1] += 50; // G
data[i + 2] += 50; // B
// data[i + 3] = Alpha, unveränderlich
}
ctx.putImageData(imageData, 0, 0);
console.log(data[0]); // R-Wert: war 255 (rot) + 50 → 255 (geclampd)Fortgeschritten: Graustufen-Konvertierung mit map
// Hilfsfunktion: RGB → Graustufe (Luminanz-Formel)
const toGrayscale = (imageData) => {
const src = imageData.data;
const dst = new Uint8ClampedArray(src.length);
for (let i = 0; i < src.length; i += 4) {
const r = src[i];
const g = src[i + 1];
const b = src[i + 2];
const lum = 0.299 * r + 0.587 * g + 0.114 * b; // kann > 255 sein → geclampd
dst[i] = lum;
dst[i + 1] = lum;
dst[i + 2] = lum;
dst[i + 3] = src[i + 3]; // Alpha beibehalten
}
return new ImageData(dst, imageData.width, imageData.height);
};
// Verwendung:
// const gray = toGrayscale(ctx.getImageData(0, 0, w, h));
// ctx.putImageData(gray, 0, 0);
console.log('Uint8ClampedArray.BYTES_PER_ELEMENT:', Uint8ClampedArray.BYTES_PER_ELEMENT);// Wichtig · Fallstricke
Banker's Rounding (Runden zur nächsten geraden Zahl): Dezimalwerte mit exakt 0,5 als Nachkommasteil werden auf die nächste gerade Ganzzahl gerundet. new Uint8ClampedArray([0.5])[0] === 0, new Uint8ClampedArray([1.5])[0] === 2. Dieses Verhalten unterscheidet sich von Math.round.
Kein Wrapping: Anders als Uint8Array, Int8Array etc. wird bei Uint8ClampedArray kein Modulo-Wrapping durchgeführt. Das macht es sicher für Farbwert-Arithmetik ohne explizite Bereichsprüfungen.
Performance: Uint8ClampedArray ist für Canvas-Operationen optimiert. Bei intensiver Pixelmanipulation kann es sinnvoll sein, statt map/filter direkte Index-Schleifen zu verwenden.
Browser-Kompatibilität: Vollständig in allen modernen Browsern und Node.js unterstützt. ImageData akzeptiert Uint8ClampedArray direkt im Konstruktor ab Chrome 43, Firefox 29, Safari 8.