EventSource

Baseline Widely available *

This feature is well established and works across many devices and browser versions. It’s been available across browsers since ⁨2020年1月⁩.

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

EventSource インターフェイスは、サーバー送信イベントのウェブコンテンツのインターフェイスです。

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

コネクションが開かれた後、サーバーからの着信メッセージは、イベントという形式でコードに配信されます。着信メッセージにイベントフィールドがある場合、発生するイベントは、イベントフィールドの値と同じになります。イベントフィールドが存在しない場合、一般的なmessage イベントが発行されます。

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

警告:HTTP/2 上で使用されていない場合、 SSE は開いている接続の最大数に制限を受けます。この制限はブラウザーごとにあり、とても低い数 (6) に設定されているため、さまざまなタブを開くために特別な痛みを伴うことがあります。この問題は、Chrome とFirefox で「修正予定なし」と表示されています。この制限はブラウザー＋ドメインごとなので、www.example1.com への SSE 接続をすべてのタブで 6 つ、www.example2.com. への SSE 接続をさらに 6 つ開くことができることを意味しています（Stackoverflow より）。 HTTP/2 を使用している場合、同時のHTTP ストリーム の最大数はサーバーとクライアントの間で交渉されます（既定値は 100）。

コンストラクター

EventSource(): 指定した URL からサーバーが（オプションで資格情報モードで）送信するイベントを処理するためのEventSource を新規に作成します。

インスタンスプロパティ

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

EventSource.readyState読取専用: 数値で、コネクションの状態を表します。取りうる値はCONNECTING (0)、OPEN (1)、CLOSED (2) です。
EventSource.url読取専用: 文字列で、ソースの URL を表します。
EventSource.withCredentials読取専用: 論理値で、EventSource オブジェクトがオリジン間 (CORS) 資格情報を設定してインスタンス化されたか (true)、設定されずにインスタンス化されたか (false、既定値) を示します。

メソッド

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

EventSource.close(): コネクションを切断して、readyState 属性をCLOSED に設定します。すでに切断されている場合は何も行いません。

イベント

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

さらに、イベントソース自身がイベントフィールドを持つメッセージを送信し、その値をキーにしたアドホックイベントを作成することもできます。

例

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

const evtSource = new EventSource("sse.php");const eventList = document.querySelector("ul");evtSource.onmessage = (e) => {  const newElement = document.createElement("li");  newElement.textContent = `message: ${e.data}`;  eventList.appendChild(newElement);};

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

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

名前付きのイベントを待ち受けするには、送信されるイベントの種類ごとにリスナーが必要になります。

const sse = new EventSource("/api/v1/sse");/* * これは以下のようなイベントのみを待ち受けします。 * * event: notice * data: useful data * id: someid */sse.addEventListener("notice", (e) => {  console.log(e.data);});/* * 同様に、これは `event: update` というフィールドを持つ * イベントを待ち受けます。 */sse.addEventListener("update", (e) => {  console.log(e.data);});/* * "message" というイベントは特別なケースで、 * イベントフィールドを持たないイベントや、特定の型である * `event: message` を持つイベントを捕捉します。それは、 * 他のイベント型では発生しません。 */sse.addEventListener("message", (e) => {  console.log(e.data);});