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, macht diese Methode nichts.

Hinweis: Der Vorgang zum Schließen der Verbindung beginnt mit einem closing handshake, und die close() Methode verwirft keine zuvor gesendeten Nachrichten, bevor der closing handshake beginnt; selbst wenn der Benutzeragent noch damit beschäftigt ist, diese Nachrichten zu senden, beginnt der Handshake erst, nachdem die Nachrichten gesendet wurden.

Syntax

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

Parameter

code Optional

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

  • Wenn nicht angegeben, wird der Schließcode für die Verbindung automatisch auf 1000 für eine normale Schließung gesetzt; andernfalls auf einen anderen Standardwert im Bereich 1001-1015, der den tatsächlichen Grund für die Schließung der Verbindung angibt.
  • Wenn angegeben, überschreibt der Wert dieses code-Parameters die automatische Einstellung des Schließcodes für die 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

Ein String, der einen benutzerdefinierten WebSocket-Verbindungs-Schließungsgrund bietet (eine kurze, für Menschen lesbare Erklärung für die Schließung). Der Wert darf nicht länger als 123 Bytes (in UTF-8 kodiert) sein.

Hinweis: Da UTF-8 zwei bis vier Bytes verwendet, um nicht-ASCII-Zeichen zu kodieren, würde ein 123-Zeichen-langer 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
# ref-for-dom-websocket-close①

Browser-Kompatibilität

Siehe auch

  • RFC 6455 (die WebSocket-Protokoll-Spezifikation)