WebSocket.binaryType — Eigenschaft · JavaScript-Referenz

Signatur

WebSocket.binaryType

Beschreibung

Die Eigenschaft binaryType einer WebSocket-Instanz bestimmt, in welcher Form empfangene binäre Nachrichten im message-Event unter event.data bereitgestellt werden. Textnachrichten sind davon nicht betroffen und kommen immer als string an.

Erlaubt sind zwei Werte:

"blob" (Standard im Browser): Die Daten kommen als Blob an. Das eignet sich für große Datenmengen wie Dateien oder Bilder, die man z. B. mit URL.createObjectURL() weiterverwendet, ohne sie komplett in JavaScript zu verarbeiten.
"arraybuffer": Die Daten kommen als ArrayBuffer an und lassen sich sofort und synchron mit DataView oder typisierten Arrays (Uint8Array, Float32Array …) auslesen. Das ist ideal für binäre Protokolle, Spiele, Sensordaten oder Audiostreams.

Die Eigenschaft ist les- und schreibbar und kann jederzeit geändert werden; der neue Wert gilt für alle danach verarbeiteten Nachrichten. Am besten setzt man sie direkt nach dem Erzeugen des Sockets, also noch bevor die erste Nachricht eintrifft. Auf das Senden hat binaryType keinen Einfluss: send() akzeptiert unabhängig davon string, Blob, ArrayBuffer und ArrayBufferView.

Parameter

Name	Typ	Default	Beschreibung
$value	"blob" \| "arraybuffer"	"blob"	Neuer Wert beim Setzen der Eigenschaft. Andere Zeichenketten werden laut Spezifikation stillschweigend ignoriert, der bisherige Wert bleibt dann erhalten.

Rückgabewert

Typ

"blob" | "arraybuffer"

Beschreibung

Den aktuell eingestellten Typ, in dem binäre Nachrichten als event.data übergeben werden.

Beispiele

Binäres Protokoll mit ArrayBuffer und DataView auslesen

const ws = new WebSocket('wss://example.com/telemetry');
ws.binaryType = 'arraybuffer';

ws.addEventListener('message', (event) => {
  if (typeof event.data === 'string') {
    console.log('Text:', event.data);
    return;
  }
  // Aufbau: 1 Byte Typ, 4 Byte Float32 (Little Endian)
  const view = new DataView(event.data);
  const type = view.getUint8(0);
  const value = view.getFloat32(1, true);
  console.log(`Sensor ${type}: ${value.toFixed(2)}`);
});

Sensor 3: 21.47

Empfangenes Bild als Blob direkt anzeigen

const ws = new WebSocket('wss://example.com/camera');
ws.binaryType = 'blob'; // Standardwert, hier nur zur Verdeutlichung

const img = document.querySelector('#preview');

ws.onmessage = (event) => {
  if (event.data instanceof Blob) {
    const url = URL.createObjectURL(event.data);
    img.onload = () => URL.revokeObjectURL(url); // Speicher freigeben
    img.src = url;
  }
};

Blob nachträglich in Bytes umwandeln

const ws = new WebSocket('wss://example.com/data');
console.log(ws.binaryType); // Standard prüfen

ws.addEventListener('message', async (event) => {
  if (event.data instanceof Blob) {
    // Asynchron – bei 'arraybuffer' wäre das nicht nötig
    const bytes = new Uint8Array(await event.data.arrayBuffer());
    console.log('Erste Bytes:', bytes.slice(0, 4));
  }
});

blob Erste Bytes: Uint8Array(4) [ 1, 0, 255, 16 ]

Ungültige Werte werden ignoriert

const ws = new WebSocket('wss://example.com');
ws.binaryType = 'arraybuffer';
ws.binaryType = 'uint8array'; // kein gültiger Wert
console.log(ws.binaryType);

arraybuffer

// Wichtig · Fallstricke

Rechtzeitig setzen: Setzen Sie binaryType direkt nach new WebSocket(). Nachrichten, die schon vorher verarbeitet wurden, kommen noch im alten Format an.
Typprüfung: Auch bei "arraybuffer" können Textnachrichten eintreffen. Prüfen Sie daher immer mit typeof event.data === 'string' bzw. instanceof ArrayBuffer/Blob.
Blob ist asynchron: Um auf die Bytes eines Blob zuzugreifen, brauchen Sie await blob.arrayBuffer(). Wenn mehrere Nachrichten schnell nacheinander kommen, kann dabei die Reihenfolge durcheinandergeraten, sofern Sie die Verarbeitung nicht selbst hintereinander ausführen. Wer die Daten sofort verarbeiten muss, sollte "arraybuffer" verwenden.
Ungültige Werte: Werte außer "blob" und "arraybuffer" lösen keinen Fehler aus und werden einfach ignoriert. Tippfehler fallen deshalb leicht nicht auf.
Kompatibilität: Wird von allen modernen Browsern unterstützt. Das globale WebSocket in Node.js (ab v22) folgt ebenfalls dem Standard. Die verbreitete Bibliothek ws nutzt dagegen "nodebuffer" als Standard und kennt zusätzlich "fragments".

Siehe auch

WebSocket WebSocket.prototype.send() ArrayBuffer Blob DataView ScreenOrientation.type