WebSocket: WebSocket() コンストラクター

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.

* Some parts of this feature may have varying levels of support.

メモ: この機能はウェブワーカー内で利用可能です。

WebSocket() コンストラクターは、新しい WebSocket オブジェクトを返し、指定された WebSocket URL への接続を直ちに確立しようとします。

構文

js
new WebSocket(url)
new WebSocket(url, protocols)

引数

url

接続対象とする WebSocket サーバーの URL です。 URL のスキームには、wswsshttphttps のいずれかを使用する必要があります。 URLフラグメントを含めることはできません。 相対 URL が指定された場合、それは呼び出し元のスクリプトのベース URL に対する相対 URL となります。

protocols 省略可

クライアントが使用したいサブプロトコルを表す単一の文字列または文字列の配列を、設定の優先順に指定します。 省略した場合は、既定では空の配列、すなわち [] が使用されます。

単一のサーバーで複数の WebSocket サブプロトコルを実装し、指定した値に応じて異なる種類の操作を処理することができます。 ただし、 1 つの接続につき選択できるサブプロトコルは 1 つだけであることに注意してください。

指定できる値は、 Sec-WebSocket-Protocol HTTP ヘッダーで指定されている値です。これらは、IANA WebSocket サブプロトコル名レジストリーから選択された soapwampship などの値、またはクライアントとサーバーが共に理解できるカスタムにすることができます。

メモ: サブプロトコルがサーバーと交渉されるまで、接続は確立されません。 選択されたプロトコルは、 WebSocket.protocol から読み取ることができます。接続が確立できない場合は、空文字列となります。

例外

SyntaxError DOMException

次のような場合に発生します。

  • url の解釈に失敗した場合
  • url のスキームが ws または wss 以外であった場合
  • urlフラグメントがあった場合
  • protocols のいずれかの値が複数回現れている、または WebSocket プロトコル仕様で定義された Sec-WebSocket-Protocol フィールドの値を構成する要素の要件に一致しない場合。

下記の例では、 WebSocket への接続方法を示しています。

次のコードは、 wss スキーマを使用するURLを使用してソケットに接続する方法を示しています。

js
const wssWebSocket = new WebSocket('wss://websocket.example.org');
console.log(wssWebSocket.url); // 'wss://websocket.example.org'
... // ソケットで何かを行う
wssWebSocket.close();

HTTPS URL に接続するためのコードはほぼ同じです。 ブラウザーの基盤では、この接続は "WSS" 接続として解決されるため、 WebSocket.url には "wss:" というスキーマが存在します。

js
const httpsWebSocket = new WebSocket('https://websocket.example.org');
console.log(httpsWebSocket.url); // 'wss://websocket.example.org'
... // ソケットで何かを行う
httpsWebSocket.close();

相対 URL の解決も可能です。 絶対 URL は、呼び出されるコンテキストのベース URL に依存します。

js
relativeWebSocket = new WebSocket('/local/url');
... // ソケットで何かを行う
relativeWebSocket.close();

仕様書

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

ブラウザーの互換性

Report problems with this compatibility data on GitHub
desktopmobileserver
Chrome
Edge
Firefox
Opera
Safari
Chrome Android
Firefox for Android
Opera Android
Safari on iOS
Samsung Internet
WebView Android
WebView on iOS
Deno
Node.js
WebSocket() constructor
url parameter allows https, http, and relative URLs

Legend

Tip: you can click/tap on a cell for more information.

Full support
Full support
No support
No support
Requires a vendor prefix or different name for use.
Has more compatibility info.

関連情報

  • RFC 6455 (WebSocket プロトコル仕様書)