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

構文

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

引数

url

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

protocols 省略可

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

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

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

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

例外

SyntaxError DOMException

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

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

例

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

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

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

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

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

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

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

仕様書

ブラウザーの互換性

関連情報

• RFC 6455 （WebSocket プロトコル仕様書）