DataView.prototype.setUint16() — Methode · JavaScript-Referenz

Signatur

DataView.prototype.setUint16(byteOffset, value, littleEndian)

Beschreibung

setUint16() speichert einen Wert als vorzeichenlose 16-Bit-Ganzzahl in den zugrunde liegenden ArrayBuffer. Anders als bei einem Uint16Array kannst du mit einem DataView an beliebigen Byte-Offsets schreiben (keine Ausrichtung auf 2 Bytes nötig) und die Byte-Reihenfolge (Endianness) selbst festlegen.

Typische Einsatzfälle sind binäre Dateiformate und Protokolle: Header von WAV-, BMP- oder PNG-Dateien, Portnummern in Netzwerkpaketen, Längenfelder in eigenen Binärprotokollen über WebSocket oder WebRTC, Bluetooth-Nachrichten (Web Bluetooth) oder das Befüllen von Puffern für WebGL.

Der Wert wird vor dem Schreiben per ToUint16 umgewandelt: Nachkommastellen werden abgeschnitten, und Werte außerhalb von 0–65535 werden modulo 2¹⁶ umgebrochen – es gibt also keinen Fehler bei Überlauf. Standardmäßig wird Big-Endian geschrieben; für Little-Endian (z. B. bei den meisten Dateiformaten auf x86-Basis) musst du true als dritten Parameter übergeben.

Parameter

Name	Typ	Default	Beschreibung
$byteOffset Pflicht	number		Offset in Bytes ab dem Beginn der Ansicht, an dem geschrieben wird. Muss so gewählt sein, dass `byteOffset + 2 <= byteLength` gilt.
$value Pflicht	number		Zu schreibender Wert. Wird per `ToUint16` in eine Ganzzahl von 0 bis 65535 umgewandelt (Überlauf modulo 65536).
$littleEndian	boolean	false	`true` schreibt Little-Endian (niederwertiges Byte zuerst), `false` bzw. weggelassen schreibt Big-Endian.

Rückgabewert

Typ

undefined

Beschreibung

Kein Rückgabewert; der Puffer wird direkt verändert.

Beispiele

Grundlagen: Big- vs. Little-Endian

const buffer = new ArrayBuffer(4);
const view = new DataView(buffer);

view.setUint16(0, 0x1234);        // Big-Endian (Standard)
view.setUint16(2, 0x1234, true);  // Little-Endian

console.log([...new Uint8Array(buffer)].map((b) => b.toString(16)));
console.log(view.getUint16(2, true));

[ '12', '34', '34', '12' ] 4660

Überlauf und Nachkommastellen

const view = new DataView(new ArrayBuffer(2));

for (const v of [65535, 65536, 70000, -1, 42.9]) {
  view.setUint16(0, v);
  console.log(v, '->', view.getUint16(0));
}

65535 -> 65535 65536 -> 0 70000 -> 4464 -1 -> 65535 42.9 -> 42

Praxis: WAV-Header-Felder schreiben (Little-Endian)

const createFmtChunk = ({ channels, sampleRate, bitsPerSample }) => {
  const view = new DataView(new ArrayBuffer(24));
  const blockAlign = channels * (bitsPerSample / 8);

  // 'fmt ' als ASCII
  [...'fmt '].forEach((c, i) => view.setUint8(i, c.charCodeAt(0)));
  view.setUint32(4, 16, true);                      // Chunk-Größe
  view.setUint16(8, 1, true);                       // Audioformat: PCM
  view.setUint16(10, channels, true);               // Kanäle
  view.setUint32(12, sampleRate, true);             // Abtastrate
  view.setUint32(16, sampleRate * blockAlign, true);// Byterate
  view.setUint16(20, blockAlign, true);             // Block-Ausrichtung
  view.setUint16(22, bitsPerSample, true);          // Bits pro Sample
  return view;
};

const fmt = createFmtChunk({ channels: 2, sampleRate: 44100, bitsPerSample: 16 });
console.log(fmt.getUint16(10, true), fmt.getUint16(20, true));

2 4

Praxis: Längenpräfix für ein Binärprotokoll

const encodeMessage = (text) => {
  const payload = new TextEncoder().encode(text);
  if (payload.length > 0xffff) throw new RangeError('Nachricht zu lang');

  const out = new Uint8Array(2 + payload.length);
  new DataView(out.buffer).setUint16(0, payload.length); // Network Byte Order
  out.set(payload, 2);
  return out;
};

console.log(encodeMessage('Hallo'));

Uint8Array(7) [0, 5, 72, 97, 108, 108, 111]

// Wichtig · Fallstricke

Standard ist Big-Endian: Wer den dritten Parameter vergisst, schreibt Big-Endian – ein häufiger Fehler bei Formaten wie WAV oder BMP, die Little-Endian erwarten. Netzwerkprotokolle („Network Byte Order“) sind dagegen meist Big-Endian.
Kein Überlauffehler: Werte außerhalb von 0–65535 werden stillschweigend umgebrochen (65536 → 0, -1 → 65535). NaN und Infinity werden zu 0. Bereiche daher vorher selbst prüfen.
RangeError: Wird geworfen, wenn byteOffset negativ ist oder byteOffset + 2 über das Ende der Ansicht hinausgeht. Der Offset ist relativ zum byteOffset des DataView, nicht zum Beginn des ArrayBuffer.
TypeError: Bei einem abgetrennten (detached, z. B. per postMessage übertragenen) Puffer.
Ein BigInt als value führt zu einem TypeError; für 64-Bit-Werte gibt es setBigUint64().
Für große, gleichförmige Datenmengen in Plattform-Byte-Reihenfolge ist ein Uint16Array in der Regel schneller.
Unterstützt in allen modernen Browsern und Node.js; funktioniert auch mit SharedArrayBuffer und größenveränderlichen ArrayBuffers (ES2024).

Siehe auch

DataView.prototype.getUint16() DataView.prototype.setInt16() DataView.prototype.setUint8() DataView.prototype.setUint32() DataView Uint16Array ArrayBuffer