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

これは実験的な機能です。本番で使用する前にブラウザー実装状況をチェックしてください。

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

send() の呼び出しで使う、キューされたデータのバイト数です。ネットワークにはまだ送信されていません。キューされたデータが全て送信されると、この値は0にリセットされます。接続が閉じられても、この値は0にリセットされません。(接続が閉じた状態で) send() を呼び出し続けると、この値は増加し続けます。 読み取り専用。

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 ページのステータスコード一覧を読んでください。
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 の接続を通してサーバーに送信します。その際、データに含めるバイト数に応じて bufferedAmount の値を増加させます。データが送信できない場合 (例えば、バッファーしたいが、バッファーがいっぱいな場合) 、ソケットは自動的に閉じられます。

void send(
  in DOMString data
);

void send(
  in ArrayBuffer data
);

void send(
  in Blob data
); 

パラメータ

data
サーバーに送信するデータです。次のどれかに当てはまります。
USVString
テキスト文字列です。文字列は UTF-8 形式でバッファーに追加されます。bufferedAmount の値は UTF-8 の文字列を表すのに必要なバイト数に応じて増加します。
ArrayBuffer
型付き配列オブジェクトで使われる基本的なバイナリデータを送信することができます。そのバイナリデータの中身はバッファーの中にキューされ、bufferedAmount の値は必要なバイト数に応じて増加します。
Blob
ブロブの生データをエンキューする Blob を指定し、バイナリフレームに送信します。bufferedAmount の値は生データのサイズに応じて増加します。
ArrayBufferView
あらゆるJavaScript の型付き配列オブジェクトをバイナリフレームとして送信することができます。バイナリデータの中身はバッファーにエンキューされます。bufferedAmount の値は必要なバイト数に応じて増加します。

 

発生する例外

INVALID_STATE_ERR
現在、接続が OPEN になっていません。
SYNTAX_ERR
ペアでないサロゲートを含んだ文字列が渡されています。

メモ: Gecko の send() メソッドの実装は Gecko 6.0 の仕様と少々異なります。Gecko は、接続がまだ開いているかどうか (さらに言うと、データがキューされたか送信されたか) に関わらず boolean を返します。これは Gecko 8.0 で修正されました。

Gecko 11.0 現在, ArrayBuffer のサポートは実装されていますが、 Blob データ型はまだです。

コード例

// 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);
});

仕様

仕様 ステータス コメント
Unknown
WebSocket の定義
不明 Initial definition

ブラウザーの互換性

現在、互換性データを可読形式の JSON フォーマットに置き換えているところです。 この互換性一覧は古い形式を使っており、これに含まれるデータの置き換えが済んでいません。 手助けしていただける場合は、こちらから!

機能 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 のサイズまで送信できます。

関連項目

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

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