DataView.prototype.byteLength — Eigenschaft · JavaScript-Referenz

Signatur

get DataView.prototype.byteLength

Beschreibung

byteLength ist eine schreibgeschützte Zugriffs-Eigenschaft (nur Getter) auf DataView.prototype. Sie gibt an, wie viele Bytes die Ansicht umfasst. Das ist nicht unbedingt die Größe des ganzen Puffers: Wurde die DataView mit byteOffset und/oder byteLength erzeugt, zeigt sie nur auf einen Ausschnitt davon.

Normalerweise wird der Wert beim Erzeugen festgelegt und bleibt danach gleich. Gibt man im Konstruktor keine Länge an, gilt buffer.byteLength - byteOffset. Eine Ausnahme sind größenveränderbare Puffer (new ArrayBuffer(n, { maxByteLength }), ES2024): Eine DataView ohne feste Länge folgt dann der aktuellen Puffergröße, ihr byteLength wächst und schrumpft also mit resize().

Gebraucht wird die Eigenschaft vor allem beim Lesen von Binärformaten (Dateiköpfe, Netzwerkprotokolle, WebSocket-Nachrichten, WebAssembly-Speicher). Mit ihr prüft man die Grenzen, bevor man mit getUint32(), getFloat64() usw. liest. Ein Zugriff außerhalb der Grenzen löst sonst einen RangeError aus.

Rückgabewert

Typ

number

Beschreibung

Eine nicht negative Ganzzahl: die Länge der Ansicht in Bytes. Löst einen TypeError aus, wenn der Puffer abgetrennt (detached) ist oder die Ansicht außerhalb der Grenzen liegt.

Beispiele

Länge bei verschiedenen Konstruktor-Argumenten

const buffer = new ArrayBuffer(16);

const ganz = new DataView(buffer);
const abOffset = new DataView(buffer, 4);
const ausschnitt = new DataView(buffer, 4, 8);

console.log(ganz.byteLength);       // gesamter Puffer
console.log(abOffset.byteLength);   // 16 - 4
console.log(ausschnitt.byteLength); // explizit angegeben

16 12 8

Grenzen prüfen beim Lesen eines Binär-Headers

const parseHeader = (view) => {
  // Header: 4 Byte Magic, 2 Byte Version, 4 Byte Länge = 10 Byte
  if (view.byteLength < 10) {
    throw new Error(`Header zu kurz: ${view.byteLength} Byte`);
  }
  return {
    magic: view.getUint32(0),
    version: view.getUint16(4),
    payloadLength: view.getUint32(6, true) // Little Endian
  };
};

const bytes = new Uint8Array([0x89, 0x50, 0x4e, 0x47, 0x00, 0x02, 0x20, 0x00, 0x00, 0x00]);
const header = parseHeader(new DataView(bytes.buffer));
console.log(header.version, header.payloadLength);

try {
  parseHeader(new DataView(new ArrayBuffer(4)));
} catch (e) {
  console.log(e.message);
}

2 32 Header zu kurz: 4 Byte

Längenverfolgende Ansicht auf größenveränderbarem Puffer (ES2024)

const rab = new ArrayBuffer(8, { maxByteLength: 32 });
const folgend = new DataView(rab);     // ohne Länge: folgt dem Puffer
const fest = new DataView(rab, 0, 4);  // feste Länge

rab.resize(16);
console.log(folgend.byteLength, fest.byteLength);

rab.resize(2);
console.log(folgend.byteLength);
try {
  console.log(fest.byteLength); // Ansicht liegt jetzt außerhalb der Grenzen
} catch (e) {
  console.log(e.name);
}

16 4 2 TypeError

Abgetrennter Puffer nach transfer()

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

const neu = buffer.transfer(); // ES2024: trennt den alten Puffer ab
console.log(buffer.detached, neu.byteLength);

try {
  view.byteLength;
} catch (e) {
  console.log(`${e.name}: Puffer ist abgetrennt`);
}

true 8 TypeError: Puffer ist abgetrennt

// Wichtig · Fallstricke

Nur lesbar: Die Eigenschaft hat keinen Setter. view.byteLength = 4 bewirkt nichts und wirft im Strict Mode einen TypeError. Um eine andere Länge zu bekommen, erzeugt man eine neue DataView.
Nicht mit buffer.byteLength verwechseln: view.byteLength ist die Länge des Ausschnitts, view.buffer.byteLength die Größe des ganzen Puffers. Bei einer DataView auf typedArray.buffer sollte man byteOffset und byteLength des Typed Arrays mitgeben, weil Node.js-Buffer oft Teile eines größeren gemeinsamen Speicherbereichs sind.
Anderes Verhalten als bei Typed Arrays: Ist der Puffer abgetrennt (z. B. durch postMessage mit Übertragung oder ArrayBuffer.prototype.transfer()), gibt TypedArray.prototype.byteLength 0 zurück. DataView.prototype.byteLength wirft dagegen einen TypeError.
Der Getter prüft seinen Empfänger. Ein Aufruf auf einem Objekt, das keine DataView ist (z. B. Object.getOwnPropertyDescriptor(DataView.prototype, 'byteLength').get.call({})), wirft einen TypeError.
Kompatibilität: Die Grundfunktion wird von allen Browsern und von Node.js unterstützt. Größenveränderbare Puffer und längenverfolgende Ansichten (ES2024) gibt es ab Chrome 111, Firefox 128, Safari 16.4 und Node.js 20.

Siehe auch

DataView DataView.prototype.byteOffset DataView.prototype.buffer ArrayBuffer.prototype.byteLength ArrayBuffer.prototype.resize() TypedArray.prototype.byteLength