WebSocket.send() — Methode · JavaScript-Referenz

Signatur

WebSocket.prototype.send(data)

Beschreibung

send() überträgt Nachrichten vom Client zum Server über eine bestehende WebSocket-Verbindung. Die Methode blockiert nicht: Die Daten werden in einen internen Puffer gelegt und im Hintergrund gesendet. Um die Anzahl der gepufferten, noch nicht gesendeten Bytes erhöht sich WebSocket.bufferedAmount. Der Wert sinkt wieder, sobald die Daten ans Netzwerk übergeben wurden.

Strings werden als Text-Frame (UTF-8-kodiert) gesendet. ArrayBuffer, typisierte Arrays, DataView und Blob gehen als Binär-Frame raus. Strukturierte Daten wie Objekte musst du vorher selbst serialisieren, üblicherweise mit JSON.stringify(). Ein Objekt direkt zu übergeben würde nur den String "[object Object]" senden.

Du darfst send() erst aufrufen, wenn die Verbindung offen ist (readyState === WebSocket.OPEN), also frühestens im open-Event. Ist die Verbindung noch im Zustand CONNECTING, wird ein InvalidStateError geworfen. Ist sie bereits im Zustand CLOSING oder CLOSED, werden die Daten stillschweigend verworfen, bufferedAmount steigt aber trotzdem.

Parameter

Name	Typ	Default	Beschreibung
$data Pflicht	string \| ArrayBuffer \| TypedArray \| DataView \| Blob		Die zu sendenden Daten. `string` wird als UTF-8-Text-Frame gesendet, `ArrayBuffer`, `TypedArray`, `DataView` und `Blob` als Binär-Frame.

Rückgabewert

Typ

void

Beschreibung

Kein Rückgabewert (undefined). Ob die Daten tatsächlich angekommen sind, bestätigt die Methode nicht.

Beispiele

JSON-Nachricht nach dem Verbindungsaufbau senden

const ws = new WebSocket('wss://echo.websocket.org');

ws.addEventListener('open', () => {
  // Objekte immer serialisieren
  ws.send(JSON.stringify({ type: 'hello', user: 'anna' }));
});

ws.addEventListener('message', (event) => {
  console.log('Antwort:', event.data);
});

Antwort: {"type":"hello","user":"anna"}

Sicheres Senden mit Warteschlange bis zum open-Event

const ws = new WebSocket('wss://example.com/chat');
const queue = [];

const safeSend = (payload) => {
  const msg = JSON.stringify(payload);
  if (ws.readyState === WebSocket.OPEN) {
    ws.send(msg);
  } else if (ws.readyState === WebSocket.CONNECTING) {
    queue.push(msg); // später senden
  } else {
    console.warn('Verbindung geschlossen, Nachricht verworfen');
  }
};

ws.addEventListener('open', () => {
  while (queue.length) ws.send(queue.shift());
});

safeSend({ type: 'join', room: 'allgemein' });

Binärdaten senden (ArrayBuffer und Blob)

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

ws.addEventListener('open', () => {
  // Typisiertes Array: 4 Messwerte als Float32
  const samples = new Float32Array([0.5, -0.25, 1.0, 0.75]);
  ws.send(samples);
  console.log('Gepuffert:', ws.bufferedAmount, 'Bytes');

  // Blob, z. B. aus einem Datei-Input
  const blob = new Blob(['Hallo Binärwelt'], { type: 'text/plain' });
  ws.send(blob);
});

Gepuffert: 16 Bytes

Gegendruck: bufferedAmount beim großen Upload beachten

const ws = new WebSocket('wss://example.com/stream');
const CHUNK = 64 * 1024;
const HIGH_WATER = 1024 * 1024; // 1 MiB

const sendFile = async (file) => {
  for (let offset = 0; offset < file.size; offset += CHUNK) {
    // Warten, solange der Puffer zu voll ist
    while (ws.bufferedAmount > HIGH_WATER) {
      await new Promise((r) => setTimeout(r, 50));
    }
    ws.send(file.slice(offset, offset + CHUNK));
  }
  console.log('Alle Blöcke eingereiht');
};

ws.addEventListener('open', () => {
  sendFile(new Blob([new Uint8Array(5 * 1024 * 1024)]));
});

Alle Blöcke eingereiht

// Wichtig · Fallstricke

InvalidStateError: Ein Aufruf im Zustand CONNECTING wirft eine DOMException. Sende deshalb immer erst im open-Event oder prüfe vorher readyState.
Stilles Verwerfen: Nach close() oder einem Verbindungsabbruch wirft send() keinen Fehler, die Daten gehen einfach verloren. Wenn Nachrichten zuverlässig ankommen müssen, brauchst du Bestätigungen auf Anwendungsebene (z. B. Nachrichten-IDs mit Quittung vom Server).
Kein automatischer Gegendruck: Wenn du schneller sendest, als das Netzwerk überträgt, wächst der Puffer unbegrenzt. Bei großen Datenmengen musst du bufferedAmount selbst überwachen. Die experimentelle WebSocketStream-API bietet echten Gegendruck, wird aber noch nicht breit unterstützt.
Objekte werden nicht automatisch serialisiert. Nutze JSON.stringify(), sonst kommt "[object Object]" an.
Sicherheit: Verwende in Produktion immer wss:// (TLS). Browser blockieren ws:// auf HTTPS-Seiten ohnehin als Mixed Content. Der Server muss eingehende Nachrichten validieren, denn Clients können beliebige Daten senden.
Kompatibilität: Wird in allen modernen Browsern unterstützt. In Node.js gibt es WebSocket global erst ab Version 22, davor brauchst du z. B. das Paket ws.

Siehe auch

WebSocket WebSocket.close() WebSocket.bufferedAmount WebSocket.readyState WebSocket.binaryType JSON.stringify()