WebSocket: close()-Methode
Baseline
Weitgehend verfügbar
Diese Funktion ist gut etabliert und funktioniert auf vielen Geräten und in vielen Browserversionen. Sie ist seit Juli 2015 browserübergreifend verfügbar.
Hinweis: Diese Funktion ist in Web Workers verfügbar.
Die Methode WebSocket.close() schließt die WebSocket-Verbindung oder einen Verbindungsversuch, sofern vorhanden. Wenn die Verbindung bereits CLOSED ist, bewirkt diese Methode nichts.
Hinweis:
Das Schließen der Verbindung beginnt mit einem Closing Handshake. Die Methode close() verwirft zuvor gesendete Nachrichten nicht, bevor dieser Handshake beginnt. Selbst wenn der User Agent noch damit beschäftigt ist, diese Nachrichten zu senden, beginnt der Handshake erst, nachdem sie gesendet wurden.
Syntax
close()
close(code)
close(code, reason)
Parameter
codeOptional-
Ein ganzzahliger Wert für einen WebSocket-Verbindungsschließcode, der den Grund für das Schließen angibt:
- Wenn kein Wert angegeben wird, enthält der an den Server gesendete Close-Frame keinen Statuscode, und der Server behandelt den Schließcode als
1005(„No Status Received“). Dercodedes daraus resultierendenclose-Ereignisses wird aus der Antwort des Servers übernommen. Üblicherweise ist er ebenfalls1005, da Server den empfangenen Statuscode normalerweise zurückgeben; der Server kann jedoch einen anderen Code senden. Wenn die Verbindung nicht ordnungsgemäß geschlossen wird, wird der Code auf einen anderen Standardwert gesetzt, beispielsweise1006. - Wenn ein Wert angegeben wird, überschreibt dieser
code-Parameter die automatische Festlegung des Schließcodes für die Verbindung und legt stattdessen einen benutzerdefinierten Code fest. Der Wert muss eine ganze Zahl sein: entweder1000oder ein benutzerdefinierter Code Ihrer Wahl im Bereich3000–4999. Wenn Sie einen Wert fürcodeangeben, sollten Sie auch einen Wert fürreasonangeben.
- Wenn kein Wert angegeben wird, enthält der an den Server gesendete Close-Frame keinen Statuscode, und der Server behandelt den Schließcode als
reasonOptional-
Eine Zeichenfolge mit einem benutzerdefinierten Grund für das Schließen der WebSocket-Verbindung (eine kurze, für Menschen lesbare Erklärung für das Schließen). Der Wert darf UTF-8-codiert höchstens 123 Byte lang sein.
Hinweis: Da UTF-8 für die Codierung von Zeichen außerhalb von ASCII zwei bis vier Byte verwendet, würde ein 123 Zeichen langer
reason-Wert mit Nicht-ASCII-Zeichen die Grenze von 123 Byte überschreiten.Wenn Sie einen Wert für
reasonangeben, sollten Sie auch einen Wert fürcodeangeben.
Rückgabewert
Keiner (undefined).
Ausnahmen
InvalidAccessErrorDOMException-
Wird ausgelöst, wenn
codeweder die ganze Zahl1000noch eine ganze Zahl im Bereich3000–4999ist. SyntaxErrorDOMException-
Wird ausgelöst, wenn der UTF-8-codierte Wert von
reasonlänger als 123 Byte ist.
Spezifikationen
| Spezifikation |
|---|
| WebSockets> # dom-websocket-close> |
Browser-Kompatibilität
Siehe auch
- RFC 6455 (die Spezifikation des WebSocket-Protokolls)