new Uint16Array() — Methode · JavaScript-Referenz

Signatur

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

Beschreibung

Mit new Uint16Array() legt man ein typisiertes Array an, dessen Elemente vorzeichenlose 16-Bit-Ganzzahlen sind. Jedes Element belegt genau 2 Byte (Uint16Array.BYTES_PER_ELEMENT === 2). Beim Anlegen werden alle Elemente mit 0 initialisiert, sofern keine Quelldaten übergeben werden.

Der Konstruktor kann auf mehrere Arten aufgerufen werden:

new Uint16Array() oder new Uint16Array(length): legt ein neues, mit Nullen gefülltes Array der angegebenen Länge an.
new Uint16Array(typedArray): kopiert die Werte eines anderen typisierten Arrays und wandelt sie dabei in 16-Bit-Werte um.
new Uint16Array(object): übernimmt Werte aus einem iterierbaren oder array-ähnlichen Objekt, z. B. einem normalen Array.
new Uint16Array(buffer, byteOffset, length): erzeugt eine Sicht auf einen vorhandenen ArrayBuffer oder SharedArrayBuffer, ohne Daten zu kopieren.

Typische Einsatzgebiete sind Binärformate (z. B. Dateiköpfe, Netzwerkprotokolle), Indexpuffer in WebGL, Audiodaten mit 16-Bit-Auflösung sowie UTF-16-Codeeinheiten von Zeichenketten. Werte außerhalb des Bereichs 0–65535 werden per Modulo-Arithmetik umgebrochen (z. B. wird -1 zu 65535), Nachkommastellen werden abgeschnitten.

Parameter

Name	Typ	Default	Beschreibung
$length	number	0	Anzahl der Elemente. Es wird ein neuer `ArrayBuffer` mit `length * 2` Byte angelegt, alle Werte sind `0`.
$typedArray	TypedArray		Ein anderes typisiertes Array (z. B. `Uint8Array`, `Float32Array`). Die Werte werden kopiert und in 16-Bit-Ganzzahlen umgewandelt. Ein `BigInt64Array` ist nicht erlaubt (`TypeError`).
$object	Iterable\|ArrayLike		Ein iterierbares oder array-ähnliches Objekt, z. B. ein normales Array oder ein `Set`. Die Werte werden kopiert.
$buffer	ArrayBuffer\|SharedArrayBuffer		Vorhandener Speicherbereich, auf den das neue Array als Sicht zugreift. Änderungen wirken sich direkt auf den Puffer aus.
$byteOffset	number	0	Startposition in Byte innerhalb von `buffer`. Muss ein Vielfaches von 2 sein, sonst wird ein `RangeError` geworfen.
$length	number	(buffer.byteLength - byteOffset) / 2	Anzahl der Elemente der Sicht (nur zusammen mit `buffer`). Ohne Angabe reicht die Sicht bis zum Pufferende.

Rückgabewert

Typ

Uint16Array

Beschreibung

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

Beispiele

Anlegen mit Länge und aus einem Array

const leer = new Uint16Array(4);
console.log(leer);

const werte = new Uint16Array([1, 300, 65535, 65536, -1, 3.9]);
console.log(werte);
console.log(werte.byteLength);

Uint16Array(4) [0, 0, 0, 0] Uint16Array(6) [1, 300, 65535, 0, 65535, 3] 12

Sicht auf einen ArrayBuffer (ohne Kopie)

const buffer = new ArrayBuffer(8);
const alle = new Uint16Array(buffer);          // 4 Elemente
const mitte = new Uint16Array(buffer, 2, 2);   // ab Byte 2, 2 Elemente

mitte[0] = 1234;
console.log(alle);
console.log(mitte.byteOffset, mitte.length);

// Ungerader Offset ist nicht erlaubt
try {
  new Uint16Array(buffer, 1);
} catch (err) {
  console.log(err.name);
}

Uint16Array(4) [0, 1234, 0, 0] 2 2 RangeError

UTF-16-Codeeinheiten einer Zeichenkette

const text = 'Grüße 👋';
const einheiten = Uint16Array.from(text, (zeichen) => zeichen.charCodeAt(0));

// Genauer: jede Codeeinheit einzeln erfassen
const codes = new Uint16Array(text.length);
for (let i = 0; i < text.length; i++) {
  codes[i] = text.charCodeAt(i);
}
console.log(codes.length);
console.log(String.fromCharCode(...codes));

8 Grüße 👋

Indexpuffer für WebGL erzeugen

// Zwei Dreiecke bilden ein Rechteck
const indices = new Uint16Array([0, 1, 2, 2, 3, 0]);

const canvas = document.createElement('canvas');
const gl = canvas.getContext('webgl');
if (gl) {
  const ibo = gl.createBuffer();
  gl.bindBuffer(gl.ELEMENT_ARRAY_BUFFER, ibo);
  gl.bufferData(gl.ELEMENT_ARRAY_BUFFER, indices, gl.STATIC_DRAW);
  console.log('Indexpuffer mit', indices.length, 'Einträgen angelegt');
}

Indexpuffer mit 6 Einträgen angelegt

// Wichtig · Fallstricke

Nur mit new: Ein Aufruf als Funktion (Uint16Array([1, 2])) wirft einen TypeError.
Überlauf ohne Fehler: Werte außerhalb von 0–65535 werden still umgebrochen (Modulo 2¹⁶), NaN wird zu 0. Wer Werte begrenzen statt umbrechen will, muss selbst klemmen – ein Uint16ClampedArray gibt es nicht.
Ausrichtung: Bei einer Sicht auf einen ArrayBuffer muss byteOffset ein Vielfaches von 2 sein und die verbleibende Pufferlänge durch 2 teilbar sein, sonst folgt ein RangeError.
Byte-Reihenfolge: Die Werte liegen in der Byte-Reihenfolge der Plattform (praktisch immer Little-Endian). Für Dateiformate oder Netzwerkprotokolle mit fester Byte-Reihenfolge besser DataView mit getUint16(offset, littleEndian) verwenden.
Kopie vs. Sicht: Aus einem Array oder typisierten Array wird kopiert; aus einem ArrayBuffer wird nur eine Sicht erzeugt – Änderungen betreffen dann alle Sichten auf denselben Puffer.
BigInt: BigInt-Werte oder ein BigInt64Array als Quelle führen zu einem TypeError.
Seit ES2015 in allen modernen Browsern und in Node.js verfügbar (Baseline). Die Unterstützung für in der Größe veränderbare ArrayBuffer (längenverfolgende Sichten) kam erst mit ES2024.

Siehe auch

Uint16Array Int16Array Uint8Array Uint32Array ArrayBuffer DataView TypedArray.from()