Signatur
Beschreibung
Uint8Array ist ein typisiertes Array (TypedArray), das eine Folge von 8-Bit-Ganzzahlen ohne Vorzeichen im Bereich 0–255 repräsentiert. Es eignet sich hervorragend für die Verarbeitung von Binärdaten, wie sie bei Netzwerkprotokollen, Datei-Uploads, kryptografischen Operationen (WebCrypto API), WebSockets oder dem Lesen von Blobs und Dateien anfallen.
Intern legt jede Uint8Array-Instanz ihre Daten in einem ArrayBuffer ab. Über den Konstruktor kann entweder ein neuer Puffer erstellt, ein vorhandener ArrayBuffer bzw. SharedArrayBuffer eingebunden oder ein anderes TypedArray bzw. ein normales Array konvertiert werden. Wird ein Wert außerhalb des Bereichs 0–255 geschrieben, wird er modulo 256 gespeichert (Bit-Abschneidung).
Alle gängigen Array-Methoden wie map(), filter(), forEach(), slice() und reduce() stehen zur Verfügung und geben ebenfalls Uint8Array-Instanzen zurück. Darüber hinaus bietet Uint8Array die statischen Methoden Uint8Array.from() und Uint8Array.of() analog zu Array.
- BYTES_PER_ELEMENT: immer
1 - Kein Vorzeichen – für vorzeichenbehaftete Bytes ist
Int8Arrayzuständig. - Für besonders speichereffiziente Bitmasken-Operationen eignet sich
Uint8ClampedArray(klemmt Werte auf 0–255 statt sie zu truncaten).
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $length | number | Anzahl der Elemente (Bytes). Es wird ein neuer ArrayBuffer der entsprechenden Länge angelegt, mit Nullen initialisiert. |
|
| $typedArray | TypedArray | Ein anderes typisiertes Array, dessen Werte in das neue Uint8Array kopiert werden (mit Konvertierung der Einzelwerte). |
|
| $object | object|Array | Ein Array-ähnliches oder iterierbares Objekt; seine Elemente werden in 8-Bit-Ganzzahlen umgewandelt und kopiert. | |
| $buffer | ArrayBuffer|SharedArrayBuffer | Ein vorhandener Puffer, auf dem das Uint8Array als View operiert. Optional kombinierbar mit byteOffset und length. |
|
| $byteOffset | number | 0 | Byte-Offset vom Anfang des ArrayBuffer, ab dem die View beginnt. Muss ein Vielfaches von BYTES_PER_ELEMENT (= 1) sein. |
| $length | number | Anzahl der Elemente im View, wenn ein buffer angegeben wurde. Standard: alle verbleibenden Bytes des Puffers. |
Rückgabewert
Uint8Array-Instanz, die auf einem ArrayBuffer operiert.Beispiele
Grundlegende Erstellung und Manipulation
// Neues Uint8Array mit 4 Elementen (alle 0)
const arr = new Uint8Array(4);
arr[0] = 42;
arr[1] = 255;
arr[2] = 256; // wird zu 0 (256 % 256)
arr[3] = -1; // wird zu 255 (Bit-Truncation)
console.log(arr); // Uint8Array(4) [42, 255, 0, 255]
console.log(arr.byteLength); // 4
console.log(Uint8Array.BYTES_PER_ELEMENT); // 1Binärdaten mit der Fetch-API verarbeiten
// PNG-Bild herunterladen und als Uint8Array auslesen
const response = await fetch('https://example.com/image.png');
const arrayBuffer = await response.arrayBuffer();
const bytes = new Uint8Array(arrayBuffer);
// PNG-Signatur prüfen: erste 8 Bytes müssen [137,80,78,71,13,10,26,10] sein
const PNG_SIGNATURE = [137, 80, 78, 71, 13, 10, 26, 10];
const isPNG = PNG_SIGNATURE.every((byte, i) => bytes[i] === byte);
console.log('Ist PNG:', isPNG);
// Ersten 16 Bytes als Hex-String ausgeben
const hex = Array.from(bytes.slice(0, 16))
.map(b => b.toString(16).padStart(2, '0'))
.join(' ');
console.log('Header:', hex);Uint8Array mit WebCrypto für kryptografische Operationen
// 16 kryptografisch sichere Zufallsbytes erzeugen
const randomBytes = new Uint8Array(16);
crypto.getRandomValues(randomBytes);
console.log('Zufallsbytes:', randomBytes);
// Text als UTF-8-Bytes kodieren
const encoder = new TextEncoder();
const encoded = encoder.encode('Hallo Welt');
console.log('Kodiert:', encoded); // Uint8Array der UTF-8-Bytes
// SHA-256-Hash berechnen
const hashBuffer = await crypto.subtle.digest('SHA-256', encoded);
const hashBytes = new Uint8Array(hashBuffer);
const hashHex = Array.from(hashBytes)
.map(b => b.toString(16).padStart(2, '0'))
.join('');
console.log('SHA-256:', hashHex);// Wichtig · Fallstricke
Truncation vs. Clamping: Im Gegensatz zu Uint8ClampedArray werden Werte außerhalb von 0–255 nicht geklemmt, sondern abgeschnitten (Modulo-256). 256 wird zu 0, 257 zu 1, -1 zu 255 usw. Das ist in der Regel das gewünschte Verhalten für Protokoll- und Binärverarbeitung, kann aber bei Canvas-Pixeloperationen zu unerwarteten Ergebnissen führen – dort besser Uint8ClampedArray verwenden.
Sicherheit: Beim Lesen von extern empfangenen Binärdaten (z. B. via WebSocket) sollten Länge und Inhalt stets validiert werden, bevor die Daten weiterverarbeitet werden. Uint8Array selbst führt keine Validierung durch.
SharedArrayBuffer: Bei Verwendung mit SharedArrayBuffer (für parallele Webworker) sind Atomics-Operationen für threadsichere Zugriffe erforderlich. SharedArrayBuffer erfordert zudem COOP/COEP-HTTP-Header (Cross-Origin-Opener-Policy/Cross-Origin-Embedder-Policy).
Browser-Kompatibilität: Uint8Array ist seit ES2015 standardisiert und in allen modernen Browsern sowie Node.js (alle unterstützten Versionen) vollständig verfügbar.