EventSource

EventSource インターフェイスは、 Server-sent event のウェブコンテンツのインターフェイスです。 EventSource インターフェイスは、 HTTP サーバーとの間で永続的なコネクションを開き、イベントtext/event-stream の形式で受け取ります。コネクションは EventSource.close() (en-US) を呼び出して閉じられるまで開いたままになります。

いったんコネクションが開かれると、サーバーから入って来るメッセージは message イベントの形でコードに配信されます。

WebSocket とは異なり、 Server-sent event は単一方向です。つまり、データメッセージはサーバーからクライアント (たとえばユーザーのウェブブラウザー) に向けて、一方向に配信されます。これは、メッセージの形でクライアントからサーバーにデータを送る必要がない場合には良い選択です。例えば、 EventSource はソーシャルメディアの状況アップデートやニュースフィードのようなものを扱ったり、クライアント側ストレージ (IndexedDBweb storage など) の仕組みにデータを配信したりするアプローチに有用です。

コンストラクター

EventSource()
指定された URL と、オプション資格情報モードから Server-sent event の受信を扱うために、新しい EventSource を生成します。

プロパティ

このインターフェイスは、親である EventTarget からプロパティを継承します。

EventSource.readyState (en-US) 読取専用
接続の状態を表す数値です。許容値は CONNECTING (0)、OPEN (1)、CLOSED (2) です。
EventSource.url (en-US) 読取専用
ソースの URL を表す DOMString です。
EventSource.withCredentials (en-US) 読取専用
Boolean で、 EventSource オブジェクトがオリジン間 (CORS) 資格情報を設定してインスタンス化されたか (true)、設定されずにインスタンス化されたか (false、既定値) を示します。

イベントハンドラー

EventSource.onerror
エラーが発生して、EventSource オブジェクトで error (en-US) イベントが発生したときに呼び出される EventHandler です。
EventSource.onmessage
message (en-US) イベントを受け取ったとき、すなわち発信元からメッセージが到着したときに呼び出される EventHandler です。
EventSource.onopen (en-US)
open (en-US) イベントを受け取ったとき、すなわち接続を開始したときに呼び出される EventHandler です。

メソッド

このインターフェイスは、親である EventTarget からメソッドを継承します。

EventSource.close() (en-US)
接続を切断して、 readyState 属性を CLOSED に設定します。すでに切断されている場合は何も行いません。

イベント

error (en-US)
イベントソースへのコネクションを開くことに失敗したときに発生します。
message (en-US)
イベントソースからデータを受信したときに発生します。
open (en-US)
イベントソースへのコネクションが開かれたときに発生します。

この基本的な例では、 EventSource を生成してサーバーからイベントを受け取ります。 sse.php という名前のページがイベントを生成する責任を負います。

var evtSource = new EventSource('sse.php');
var eventList = document.querySelector('ul');

evtSource.onmessage = function(e) {
  var newElement = document.createElement("li");

  newElement.textContent = "message: " + e.data;
  eventList.appendChild(newElement);
}

受信されたそれぞれのイベントは、 EventSource オブジェクトの onmessage イベントハンドラーを実行させます。ここでは、新しい <li> 要素を生成してその中にメッセージのデータを書き込み、この要素を文書の中にある既存のリスト要素に追加します。

メモ: この例の全容が GitHub にあります。Simple SSE demo using PHP をご覧ください。

仕様書

仕様書 備考
HTML Living Standard
EventSource の定義
現行の標準

Browser compatibility

BCD tables only load in the browser

関連情報