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

Signatur

DataView.prototype.setUint8(byteOffset, value)

Beschreibung

setUint8() schreibt genau ein Byte in den zugrunde liegenden ArrayBuffer eines DataView. Der Wert wird dabei als vorzeichenloser 8-Bit-Integer interpretiert, also im Bereich von 0 bis 255 gespeichert.

Die Methode eignet sich besonders zum Aufbau von Binärformaten: Datei-Header (z. B. PNG, WAV, BMP), Netzwerkprotokolle, Flag-Bytes, Versionsnummern oder Längenfelder, die mit anderen Feldtypen (setUint16(), setFloat32() …) im selben Puffer gemischt werden. Weil nur ein einzelnes Byte geschrieben wird, gibt es – anders als bei den breiteren Setter-Methoden – keinen littleEndian-Parameter; die Byte-Reihenfolge spielt hier keine Rolle.

Werte außerhalb von 0–255 werden nicht abgelehnt, sondern per Modulo-2⁸-Umwandlung (ToUint8) umgebrochen: 256 wird zu 0, -1 zu 255, Nachkommastellen werden abgeschnitten, NaN wird zu 0. Liegt byteOffset außerhalb des sichtbaren Bereichs des DataView, wird ein RangeError ausgelöst.

Parameter

Name	Typ	Default	Beschreibung
$byteOffset Pflicht	number		Position in Bytes, gemessen ab dem Anfang des `DataView` (nicht des `ArrayBuffer`), an die geschrieben wird. Wird in eine ganze Zahl umgewandelt; negative Werte oder Werte ≥ `byteLength` lösen einen `RangeError` aus.
$value Pflicht	number		Zu schreibender Wert. Wird per ToUint8 in den Bereich 0–255 umgewandelt (Modulo 256, Nachkommastellen abgeschnitten). `BigInt`-Werte lösen einen `TypeError` aus.

Rückgabewert

Typ

undefined

Beschreibung

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

Beispiele

Einzelne Bytes schreiben und lesen

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

view.setUint8(0, 42);
view.setUint8(1, 255);

console.log(view.getUint8(0));
console.log(view.getUint8(1));
console.log(new Uint8Array(buffer));

42 255 Uint8Array(4) [42, 255, 0, 0]

Umbruch bei Werten außerhalb von 0–255

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

[256, -1, 300, 12.9, NaN].forEach((v, i) => view.setUint8(i, v));

console.log([0, 1, 2, 3, 4].map(i => view.getUint8(i)));

[0, 255, 44, 12, 0]

Binären Nachrichten-Header aufbauen

// Format: [Version:u8][Flags:u8][Länge:u16 BE][Payload…]
const buildMessage = (payload, { version = 1, compressed = false, urgent = false } = {}) => {
  const bytes = new TextEncoder().encode(payload);
  const buffer = new ArrayBuffer(4 + bytes.length);
  const view = new DataView(buffer);

  const flags = (compressed ? 0b01 : 0) | (urgent ? 0b10 : 0);

  view.setUint8(0, version);
  view.setUint8(1, flags);
  view.setUint16(2, bytes.length); // Big-Endian (Standard)
  new Uint8Array(buffer, 4).set(bytes);

  return buffer;
};

const msg = buildMessage('Hi', { urgent: true });
console.log(new Uint8Array(msg));

Uint8Array(6) [1, 2, 0, 2, 72, 105]

RangeError bei ungültigem Offset abfangen

const view = new DataView(new ArrayBuffer(8), 4, 2); // sichtbar: Bytes 4–5

view.setUint8(1, 99); // schreibt in Byte 5 des Buffers

try {
  view.setUint8(2, 1); // außerhalb des Views
} catch (err) {
  console.log(err.name);
}
console.log(new Uint8Array(view.buffer));

RangeError Uint8Array(8) [0, 0, 0, 0, 0, 99, 0, 0]

// Wichtig · Fallstricke

Kein Clamping: Werte werden modulo 256 umgebrochen, nicht auf 0–255 begrenzt (300 → 44). Wer Begrenzung braucht (z. B. Farbwerte), sollte vorher Math.min(255, Math.max(0, v)) anwenden oder Uint8ClampedArray verwenden.
Offset ist relativ zum View: byteOffset zählt ab dem Start des DataView, nicht ab dem Anfang des ArrayBuffer.
Kein Endianness-Parameter: Ein zusätzliches drittes Argument wird ignoriert.
Losgelöste Puffer: Wurde der ArrayBuffer übertragen (z. B. per postMessage mit Transfer oder ArrayBuffer.prototype.transfer()), löst der Aufruf einen TypeError aus.
Performance: Für massenhaftes Schreiben einzelner Bytes ist ein Uint8Array meist schneller und lesbarer; DataView spielt seine Stärke bei gemischten Feldtypen aus.
Kompatibilität: in allen modernen Browsern und Node.js uneingeschränkt verfügbar.

Siehe auch

DataView.prototype.getUint8() DataView.prototype.setInt8() DataView.prototype.setUint16() DataView ArrayBuffer Uint8Array Uint8ClampedArray