DataView.prototype.byteOffset — Eigenschaft · JavaScript-Referenz

Signatur

get DataView.prototype.byteOffset

Beschreibung

Die Zugriffseigenschaft byteOffset liefert den Abstand in Bytes zwischen dem Anfang des zugrunde liegenden Puffers (view.buffer) und dem ersten Byte, auf das der DataView zugreift. Der Wert wird beim Erzeugen über den zweiten Konstruktor-Parameter festgelegt (new DataView(buffer, byteOffset, byteLength)) und ändert sich danach nicht. Ohne Angabe ist er 0.

Gebraucht wird byteOffset vor allem, wenn mehrere Ansichten denselben Speicher teilen, etwa beim Auslesen von Binärformaten (Dateikopfzeilen, Netzwerkpakete, WebAssembly-Speicher). Mit byteOffset und byteLength lässt sich ausrechnen, welcher Bereich des Puffers zum View gehört. So kann man Positionen im View in absolute Positionen im Puffer umrechnen und umgekehrt.

Alle Lese- und Schreibmethoden wie getUint32() oder setFloat64() zählen ihren Offset relativ zu byteOffset. view.getUint8(0) liest also das Byte an der Position view.byteOffset im Puffer.

Rückgabewert

Typ

number

Beschreibung

Eine nicht negative ganze Zahl: der Abstand des Views zum Anfang seines Puffers in Bytes. Ist der Puffer abgekoppelt (detached) oder liegt der View nach einer Größenänderung außerhalb des Puffers, wird ein TypeError geworfen.

Beispiele

Offset beim Erzeugen festlegen und auslesen

const buffer = new ArrayBuffer(16);

const full = new DataView(buffer);          // ganzer Puffer
const part = new DataView(buffer, 4, 8);    // Bytes 4 bis 11

console.log(full.byteOffset); // 0
console.log(part.byteOffset); // 4

// Schreibzugriffe zählen relativ zum byteOffset
part.setUint8(0, 255);
console.log(new Uint8Array(buffer)[4]); // 255

0 4 255

DataView aus einem Uint8Array-Ausschnitt erzeugen

// Typischer Fall: Ein Teilbereich (z. B. ein Node.js-Buffer oder subarray)
// liegt NICHT am Anfang seines ArrayBuffer.
const bytes = new Uint8Array([0x00, 0x00, 0xca, 0xfe, 0xba, 0xbe, 0x00, 0x00]);
const magic = bytes.subarray(2, 6);

// Falsch wäre: new DataView(magic.buffer) – das beginnt bei Byte 0!
const view = new DataView(magic.buffer, magic.byteOffset, magic.byteLength);

console.log(view.byteOffset);                  // 2
console.log(view.getUint32(0).toString(16));   // "cafebabe"

2 cafebabe

Relative Position in eine absolute Pufferposition umrechnen

const buffer = new ArrayBuffer(64);
const header = new DataView(buffer, 0, 16);
const payload = new DataView(buffer, header.byteLength, 48);

const toAbsolute = (view, relOffset) => view.byteOffset + relOffset;

console.log(payload.byteOffset);          // 16
console.log(toAbsolute(payload, 10));     // 26

16 26

TypeError bei abgekoppeltem oder geschrumpftem Puffer

// Abgekoppelter Puffer (ArrayBuffer.prototype.transfer, ES2024)
const buffer = new ArrayBuffer(8);
const view = new DataView(buffer, 2);
buffer.transfer();

try {
  view.byteOffset;
} catch (err) {
  console.log(err.name); // "TypeError"
}

// Größenveränderbarer Puffer: View liegt nach resize() außerhalb
const rab = new ArrayBuffer(8, { maxByteLength: 16 });
const tail = new DataView(rab, 6);
rab.resize(4);

try {
  tail.byteOffset;
} catch (err) {
  console.log(err.name); // "TypeError"
}

TypeError TypeError

// Wichtig · Fallstricke

Nur lesbar: byteOffset hat keinen Setter. Eine Zuweisung wird im nicht strikten Modus stillschweigend ignoriert und löst im strikten Modus einen TypeError aus. Für einen anderen Offset muss man einen neuen DataView anlegen.
Häufiger Fehler: Wer aus einem Uint8Array-Ausschnitt oder einem Node.js-Buffer nur new DataView(arr.buffer) erzeugt, liest ab Byte 0 des gesamten Puffers statt ab dem Ausschnitt. Deshalb immer arr.byteOffset und arr.byteLength mitgeben. Das ist besonders wichtig bei kleinen Node.js-Buffern, die sich einen gemeinsamen Speicherpool teilen.
Abgekoppelte Puffer: Wurde der Puffer abgekoppelt, etwa durch transfer() oder durch postMessage mit Übertragungsliste, wirft der Zugriff einen TypeError. Das gilt auch, wenn ein größenveränderbarer ArrayBuffer (ES2024) so weit verkleinert wurde, dass der View außerhalb liegt.
Der Konstruktor wirft einen RangeError, wenn byteOffset größer ist als die Länge des Puffers.
Kompatibilität: Die Eigenschaft wird in allen modernen Browsern und in Node.js unterstützt. Das Verhalten mit größenveränderbaren Puffern und mit transfer() gibt es erst in neueren Laufzeitumgebungen (ab ES2024).

Siehe auch

DataView DataView.prototype.byteLength DataView.prototype.buffer TypedArray.prototype.byteOffset ArrayBuffer SharedArrayBuffer