new Uint8Array() — Methode · JavaScript-Referenz

Signatur

new Uint8Array(lengthOrSourceOrBuffer, byteOffset, length)

Beschreibung

Der Konstruktor Uint8Array() legt ein typisiertes Array an, dessen Elemente vorzeichenlose 8-Bit-Ganzzahlen sind. Damit ist Uint8Array die übliche Darstellung für rohe Bytes: Dateiinhalte, Netzwerkdaten, Ergebnisse von TextEncoder, crypto.getRandomValues() oder Response.arrayBuffer().

Je nach Argument verhält sich der Konstruktor unterschiedlich:

Ohne Argument oder mit einer Zahl: Es wird ein neuer, mit 0 gefüllter Puffer mit der angegebenen Länge angelegt.
Mit einem typisierten Array, Array oder iterierbaren Objekt: Die Werte werden in einen neuen Puffer kopiert und dabei in den Bereich 0–255 umgewandelt (modulo 256).
Mit einem ArrayBuffer oder SharedArrayBuffer: Es wird kein Speicher kopiert, sondern eine Sicht auf den bestehenden Puffer erzeugt, optional ab byteOffset und mit length Elementen. Änderungen wirken sich auf alle Sichten desselben Puffers aus.

Der Konstruktor darf nur mit new aufgerufen werden; ein Aufruf ohne new wirft einen TypeError. Die Länge eines typisierten Arrays ist fest, Methoden wie push() gibt es nicht.

Parameter

Name	Typ	Default	Beschreibung
$length	number	0	Anzahl der Elemente (= Bytes). Alle Elemente werden mit `0` initialisiert.
$typedArray \| object	TypedArray \| Array \| Iterable \| ArrayLike		Quelle, deren Werte in ein neues `Uint8Array` kopiert werden. Werte werden per `ToUint8` umgewandelt (z. B. `256 → 0`, `-1 → 255`).
$buffer	ArrayBuffer \| SharedArrayBuffer		Bestehender Puffer, auf den das neue Array als Sicht zugreift – ohne Kopie.
$byteOffset	number	0	Nur mit `buffer`: Start-Offset in Bytes innerhalb des Puffers.
$length	number	buffer.byteLength - byteOffset	Nur mit `buffer`: Anzahl der Elemente der Sicht. Ohne Angabe reicht die Sicht bis zum Pufferende.

Rückgabewert

Typ

Uint8Array

Beschreibung

Ein neues Uint8Array-Objekt – entweder mit eigenem Puffer oder als Sicht auf den übergebenen ArrayBuffer.

Beispiele

Varianten der Erzeugung

const leer = new Uint8Array(4);
const ausArray = new Uint8Array([10, 255, 256, -1]);
const ausIterable = new Uint8Array(new Set([1, 2, 3]));

console.log(leer);
console.log(ausArray); // 256 → 0, -1 → 255
console.log(ausIterable);

Uint8Array(4) [0, 0, 0, 0] Uint8Array(4) [10, 255, 0, 255] Uint8Array(3) [1, 2, 3]

Sicht auf einen ArrayBuffer (keine Kopie)

const buffer = new ArrayBuffer(8);
const gesamt = new Uint8Array(buffer);
const mitte = new Uint8Array(buffer, 2, 4); // Bytes 2..5

mitte.fill(0xff);
console.log(gesamt);
console.log(mitte.byteOffset, mitte.length);

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

Text in Bytes umwandeln und als Hex ausgeben

const bytes = new TextEncoder().encode('Hallö');
const kopie = new Uint8Array(bytes); // echte Kopie

const hex = Array.from(kopie, (b) => b.toString(16).padStart(2, '0')).join(' ');
console.log(kopie.length, hex);

6 48 61 6c 6c c3 b6

Datei-Signatur aus einer Response prüfen

const istPng = async (url) => {
  const res = await fetch(url);
  const bytes = new Uint8Array(await res.arrayBuffer(), 0, 8);
  const signatur = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];
  return signatur.every((b, i) => bytes[i] === b);
};

istPng('/logo.png').then(console.log);

true

// Wichtig · Fallstricke

Kopie vs. Sicht: new Uint8Array(andererTypedArray) kopiert, new Uint8Array(andererTypedArray.buffer) teilt den Speicher. Achtung: .buffer kann größer sein als das Array – immer byteOffset und byteLength mitgeben.
Überlauf: Werte außerhalb 0–255 werden modulo 256 umgebrochen, Nachkommastellen abgeschnitten, NaN wird zu 0. Für Begrenzung statt Umbruch Uint8ClampedArray verwenden.
byteOffset muss bei Uint8Array nicht ausgerichtet sein (Elementgröße 1), aber byteOffset + length darf buffer.byteLength nicht überschreiten – sonst RangeError.
Ohne new aufgerufen: TypeError. Sehr große Längen können einen RangeError auslösen.
Wird der zugrunde liegende Puffer übertragen (z. B. per postMessage mit Transfer-Liste), ist die Sicht danach leer (length === 0).
Unterstützt in allen modernen Browsern und Node.js; Node-Buffer ist eine Unterklasse von Uint8Array. Neuere Methoden wie Uint8Array.fromBase64() / toHex() sind noch nicht überall verfügbar.

Siehe auch

Uint8Array ArrayBuffer Uint8ClampedArray DataView TypedArray.from() TextEncoder new BigInt64Array()