WebSocket

この翻訳は不完全です。英語から この記事を翻訳 してください。

これは実験段階の機能です。
この機能は複数のブラウザーで開発中の状態にあります。互換性テーブルをチェックしてください。また、実験段階の機能の構文と挙動は、仕様変更に伴い各ブラウザーの将来のバージョンで変更になる可能性があることに注意してください。

WebSocket オブジェクトは、サーバーへの WebSocket 接続の作成と管理を行う API を提供します。また、接続を通してデータの送受信も行えます。

WebSocket コンストラクタは、次に示す1つの必須引数と1つのオプション引数を取ります。

WebSocket WebSocket(
  in DOMString url,
  in optional DOMString protocols
);

WebSocket WebSocket(
  in DOMString url,
  in optional DOMString[] protocols
);
url
接続する URL です。WebSocket サーバーがレスポンスを返す URL でなければなりません。
protocols Optional
1つのプロトコル文字列またはプロトコル文字列の配列を指定します。これらの文字列はサブプロトコル (sub-protocols) を指定するために使用します。1つのサーバーが複数の WebSocket サブプロトコルを実装している場合があるためです (たとえば、1つのサーバーで protocol で異なる種類のインタラクションをハンドリングできるようにしたいかもしれません)。プロトコル文字列を指定しなかった場合、空文字列が与えられたものとされます。

コンストラクタが送出する例外は、次のものです。

SECURITY_ERR
接続を試みていた対象のポートがブロックされたとき。

メソッドの概要

void close(in optional unsigned long code, in optional DOMString reason);
void send(in DOMString data);

属性

属性 説明
binaryType DOMString 接続で送信されるバイナリデータのタイプを表す文字列。この値は、DOM Blob オブジェクトが使われる場合には "blob"、ArrayBuffer オブジェクトが使われる場合には "arraybuffer" でなければなりません。
bufferedAmount unsigned long

have been queued using calls to send() but not yet transmitted to the network

send() 、データのバイト数。This value resets to zero once all queued data has been sent. This value does not reset to zero when the connection is closed; if you keep calling send(), this will continue to climb. 読み取り専用。

extensions DOMString サーバーが選択した extensions。現在、この値は、空の文字列または接続がネゴシエートした extensions のリストとなる。
onclose EventListener WebSocket 接続が readyState が CLOSED に変更された時に呼ばれるイベントリスナー。リスナーは "close" と呼ばれる CloseEvent を受け取ります。 
onerror EventListener エラーが発生した時に呼ばれるイベントリスナー。このイベントは "error" と呼ばれるシンプルなイベントである。
onmessage EventListener

WebSocket 接続がサーバーからメッセージを受信した時に呼ばれるイベントリスナー。リスナーは "message" と呼ばれる MessageEvent を受け取ります。

onopen EventListener WebSocket 接続の readyState が OPEN に変更された時に呼ばれるイベントリスナー。つまり、このとき、接続はデータの送受信ができるようになったことを意味する。このイベントは "open" 呼ばれるシンプルなイベントである。
protocol DOMString サーバーが選択した sub-protocol を表す文字列。この値は、WebSocket オブジェクトを作成する時に protocols パラメータで指定した値の1つになる。
readyState unsigned short 現在の接続の状態を表す。この属性の値は、Ready state constants のうちの1つを取る。読み取り専用
url DOMString

コンストラクタが解決した URL。常に絶対 URL となる。読み取り専用

定数

Ready state 定数

これらの定数は、WebSocket 接続の状態を記述するために、readyState 属性によって使用されます。

定数 説明
CONNECTING 0 接続はまだ開いていない。
OPEN 1 接続は開いていて、通信準備ができている。
CLOSING 2 接続を閉じる処理中。
CLOSED 3 接続は閉じられていて、開くことができない。

メソッド

close()

WebSocket の接続または接続の試行を閉じます。接続がすでに CLOSED ならば、このメソッドは何もしません。

void close(
  in optional unsigned short code,
  in optional DOMString reason
);

パラメータ

code Optional
接続が閉じられた理由を表すステータスコードを数値で与えます。このパラメータが指定されなかった場合、デフォルト値は 1000 (通常の "transaction complete" を表す) が指定されたとみなされます。使用できる値については、詳しくは CloseEvent ページの list of status codes を読んでください。
reason Optional
接続が閉じられた理由を説明する、ヒューマンリーダブルな文字列。この文字列は、UTF-8 テキストで 123 バイト (123 文字ではない) を超えてはいけません。

送出される例外

INVALID_ACCESS_ERR
無効な code が指定された。
SYNTAX_ERR
reason 文字列が長すぎるか、サロゲートのペアが足りない。

メモ: Gecko では、このメソッドは Gecko 8.0 (Firefox 8.0 / Thunderbird 8.0 / SeaMonkey 2.5) 以前にはパラメータを取りません。

send()

WebSocket 接続を利用して、データをサーバーに送信する。

void send(
  in DOMString data
);

void send(
  in ArrayBuffer data
);

void send(
  in Blob data
); 

パラメータ

data
A text string to send to the server.

送出される例外

INVALID_STATE_ERR
現在、接続が OPEN になっていない。
SYNTAX_ERR
data に欠けたサロゲートペアが含まれている。

メモ: Gecko's implementation of the send() method differs somewhat from the specification in Gecko 6.0; Gecko returns a boolean indicating whether or not the connection is still open (and, by extension, that the data was successfully queued or transmitted); this is corrected in Gecko 8.0.

As of Gecko 11.0, support for ArrayBuffer is implemented but not Blob data types.

コード例

// WebSocket を作成
const socket = new WebSocket('ws://localhost:8080');

// 接続を開く
socket.addEventListener('open', function (event) {
    socket.send('Hello Server!');
});

// メッセージを Listen する
socket.addEventListener('message', function (event) {
    console.log('Message from server', event.data);
});

仕様

仕様 ステータス コメント
The WebSocket API
WebSocket の定義
勧告候補 Initial definition

ブラウザーの互換性

機能 Chrome Edge Firefox (Gecko) Internet Explorer Opera Safari
基本サポート (有) (有) 4.0 (2.0)[1] (有) (有) (有)
Sub-protocol サポート ? ? 6.0 (6.0) ? ? ?
機能 Android Edge Firefox Mobile (Gecko) IE Mobile Opera Mobile Safari Mobile
基本サポート ? (有) 7.0 (7.0)[1] ? ? (有)
Sub-protocol サポート ? ? 7.0 (7.0) ? ? ?

[1] Starting in Gecko 6.0 (Firefox 6.0 / Thunderbird 6.0 / SeaMonkey 2.3), the constructor is prefixed; you will need to use MozWebSocket(): var mySocket = new MozWebSocket("http://www.example.com/socketserver");

Gecko では、Gecko 8.0 までは extensions 属性がサポートされていませんでした。

Gecko 11.0 (Firefox 11.0 / Thunderbird 11.0 / SeaMonkey 2.8) 以前では、send() メソッドを使用した outbound メッセージは 16 MB に制限されていました。現在は、最大 2 GB のサイズまで送信できます。

関連項目

ドキュメントのタグと貢献者

 このページの貢献者: shuuji3
 最終更新者: shuuji3,