WebSocket: close()-Methode

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since July 2015.

Hinweis: Diese Funktion ist in Web Workers verfügbar.

Die WebSocket.close()-Methode schließt die WebSocket-Verbindung oder den Verbindungsversuch, falls vorhanden. Wenn die Verbindung bereits CLOSED ist, tut diese Methode nichts.

Hinweis: Der Prozess des Schließens der Verbindung beginnt mit einem Schließhandshake, und die close()-Methode verwirft keine zuvor gesendeten Nachrichten, bevor dieser Schließhandshake beginnt; auch wenn der Benutzeragent noch damit beschäftigt ist, diese Nachrichten zu senden, wird der Handshake erst gestartet, nachdem die Nachrichten gesendet wurden.

Syntax

js
close()
close(code)
close(code, reason)

Parameter

code Optional

Ein ganzzahliger WebSocket-Verbindungsschlusscode, der einen Grund für die Schließung angibt:

  • Wenn nicht angegeben, wird der Verbindung automatisch ein Schlusscode zugewiesen: 1000 für eine normale Schließung oder ansonsten ein anderer Standardwert im Bereich 1001-1015, der den tatsächlichen Grund für die Beendigung der Verbindung angibt.
  • Wenn angegeben, überschreibt der Wert dieses code-Parameters die automatische Festlegung des Schlusscodes der Verbindung und setzt stattdessen einen benutzerdefinierten Code. Der Wert muss eine Ganzzahl sein: entweder 1000 oder ein benutzerdefinierter Code Ihrer Wahl im Bereich 3000-4999. Wenn Sie einen code-Wert angeben, sollten Sie auch einen reason-Wert angeben.
reason Optional

Eine Zeichenkette, die einen benutzerdefinierten Grund für die Beendigung der WebSocket-Verbindung (eine prägnante und menschenlesbare Erklärung für die Schließung) liefert. Der Wert darf nicht länger als 123 Byte (in UTF-8 kodiert) sein.

Hinweis: Da UTF-8 zwei bis vier Bytes benötigt, um beliebige nicht-ASCII-Zeichen zu kodieren, würde ein 123-Zeichen reason-Wert, der nicht-ASCII-Zeichen enthält, das 123-Byte-Limit überschreiten.

Wenn Sie einen reason-Wert angeben, sollten Sie auch einen code-Wert angeben.

Rückgabewert

Keiner (undefined).

Ausnahmen

InvalidAccessError DOMException

Wird ausgelöst, wenn code weder eine Ganzzahl gleich 1000 noch eine Ganzzahl im Bereich 3000 – 4999 ist.

SyntaxError DOMException

Wird ausgelöst, wenn der in UTF-8 kodierte reason-Wert länger als 123 Bytes ist.

Spezifikationen

Specification
WebSockets Standard
# ref-for-dom-websocket-close①

Browser-Kompatibilität

BCD tables only load in the browser

Siehe auch

  • RFC 6455 (die WebSocket-Protokollspezifikation)