EventSource

翻译不完整。 请帮助我们翻译这篇文章!

EventSource 是服务器推送的一个网络事件接口。一个EventSource实例会对HTTP服务开启一个持久化的连接,以text/event-stream 格式发送事件, 会一直保持开启直到被要求关闭。

一旦连接开启,来自服务端传入的消息会以事件的形式分发至你代码中。如果接收消息中有一个事件字段,触发的事件与事件字段的值相同。如果没有事件字段存在,则将触发通用事件。

与 WebSockets,不同的是,服务端推送是单向的。数据信息被单向从服务端到客户端分发. 当不需要以消息形式将数据从客户端发送到服务器时,这使它们成为绝佳的选择。例如,对于处理社交媒体状态更新,新闻提要或将数据传递到客户端存储机制(如IndexedDB或Web存储)之类的,EventSource无疑是一个有效方案。

构造函数

EventSource()
以指定的 USVString 创建一个新的 EventSource

属性

此接口从其父接口 EventTarget 继承属性。

EventSource.onerror
是一个 EventHandler,当发生错误时被调用,并且在此对象上派发 error 事件。
EventSource.onmessage
是一个 EventHandler,当收到一个 message 事件,即消息来自源头时被调用。
EventSource.onopen
是一个 EventHandler,当收到一个 open 事件,即连接刚打开时被调用。
EventSource.readyState 只读
一个 unsigned short 值,代表连接状态。可能值是 CONNECTING (0), OPEN (1), 或者 CLOSED (2)。
EventSource.url 只读
一个DOMString,代表事件源的 URL。

事件接收器

EventSource.onerror
Is an EventHandler called when an error occurs and the error event is dispatched on an EventSource object.
EventSource.onmessage
Is an EventHandler called when a message event is received, that is when a message is coming from the source.
EventSource.onopen
Is an EventHandler called when an open event is received, that is when the connection was just opened.

方法

此接口从其父接口 EventTarget 继承方法。

EventSource.close()
如果存在,则关闭连接,并且设置 readyState 属性为 CLOSED。如果连接已经被关闭,此方法不会再进行任何操作。

事件

error
Fired when a connection to an event source failed to open.
message
Fired when data is received from an event source.
open
Fired when a connection to an event source has opened.

Additionally, the event source itself may send messages with an event field, which will create ad-hoc events keyed to that value.

示例

In this basic example, an EventSource is created to receive unnamed events from the server; a page with the name sse.php is responsible for generating the events.

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

Each received event causes our EventSource object's onmessage event handler to be run. It, in turn, creates a new <li> element and writes the message's data into it, then appends the new element to the list element already in the document.

Note: You can find a full example on GitHub — see Simple SSE demo using PHP.

To listen to named events, you'll require a listener for each type of event sent.

  const sse = new EventSource('/api/v1/sse');

  /* This will listen only for events 
   * similar to the following:
   * 
   * event: notice
   * data: useful data
   * id: someid
   *
   */
  sse.addEventListener("notice", function(e) { 
    console.log(e.data)
  })

  /* Similarly, this will listen for events 
   * with the field `event: update`
   */
  sse.addEventListener("update", function(e) {
    console.log(e.data)
  })

  /* The event "message" is a special case, as it
   * will capture events without an event field
   * as well as events that have the specific type
   * `event: message` It will not trigger on any
   * other event type.
   */
  sse.addEventListener("message", function(e) {
    console.log(e.data)
  })
  

规范

规范 状态
HTML Living Standard
EventSource
Living Standard

浏览器兼容性

Update compatibility data on GitHub
DesktopMobile
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewChrome for AndroidFirefox for AndroidOpera for AndroidSafari on iOSSamsung Internet
EventSourceChrome Full support 6Edge Full support 79Firefox Full support 6IE No support NoOpera Full support 11Safari Full support 5WebView Android Full support ≤37Chrome Android Full support 18Firefox Android Full support 45Opera Android Full support 11Safari iOS Full support 5Samsung Internet Android Full support 1.0
EventSource() constructorChrome Full support 9Edge Full support 79Firefox Full support 6IE No support NoOpera Full support 11Safari Full support 5WebView Android Full support YesChrome Android Full support 18Firefox Android Full support 45Opera Android Full support 12Safari iOS Full support 5Samsung Internet Android Full support 1.0
closeChrome Full support 6Edge Full support 79Firefox Full support 6IE No support NoOpera Full support YesSafari Full support 5WebView Android Full support YesChrome Android Full support 18Firefox Android Full support 45Opera Android Full support 12Safari iOS Full support 5Samsung Internet Android Full support 1.0
error eventChrome Full support 6Edge Full support 79Firefox Full support 6IE No support NoOpera Full support YesSafari Full support 5WebView Android Full support YesChrome Android Full support 18Firefox Android Full support 45Opera Android Full support 12Safari iOS Full support 5Samsung Internet Android Full support 1.0
message eventChrome Full support 6Edge Full support 79Firefox Full support 6IE No support NoOpera Full support YesSafari Full support 5WebView Android Full support YesChrome Android Full support 18Firefox Android Full support 45Opera Android Full support 12Safari iOS Full support 5Samsung Internet Android Full support 1.0
onerrorChrome Full support 6Edge Full support 79Firefox Full support 6IE No support NoOpera Full support YesSafari Full support 5WebView Android Full support YesChrome Android Full support 18Firefox Android Full support 45Opera Android Full support 12Safari iOS Full support 5Samsung Internet Android Full support 1.0
onmessageChrome Full support 6Edge Full support 79Firefox Full support 6IE No support NoOpera Full support YesSafari Full support 5WebView Android Full support YesChrome Android Full support 18Firefox Android Full support 45Opera Android Full support 12Safari iOS Full support 5Samsung Internet Android Full support 1.0
onopenChrome Full support 6Edge Full support 79Firefox Full support 6IE No support NoOpera Full support YesSafari Full support 5WebView Android Full support YesChrome Android Full support 18Firefox Android Full support 45Opera Android Full support 12Safari iOS Full support 5Samsung Internet Android Full support 1.0
open eventChrome Full support 6Edge Full support 79Firefox Full support 6IE No support NoOpera Full support YesSafari Full support 5WebView Android Full support YesChrome Android Full support 18Firefox Android Full support 45Opera Android Full support 12Safari iOS Full support 5Samsung Internet Android Full support 1.0
readyStateChrome Full support 6Edge Full support 79Firefox Full support 6IE No support NoOpera Full support YesSafari Full support 5WebView Android Full support YesChrome Android Full support 18Firefox Android Full support 45Opera Android Full support 12Safari iOS Full support 5Samsung Internet Android Full support 1.0
urlChrome Full support 6Edge Full support 79Firefox Full support 6IE No support NoOpera Full support YesSafari Full support 5WebView Android Full support YesChrome Android Full support 18Firefox Android Full support 45Opera Android Full support 12Safari iOS Full support 5Samsung Internet Android Full support 1.0
withCredentialsChrome Full support 6Edge Full support 79Firefox Full support 6IE No support NoOpera Full support YesSafari Full support 5WebView Android Full support YesChrome Android Full support 18Firefox Android Full support 45Opera Android Full support 12Safari iOS Full support 5Samsung Internet Android Full support 1.0
Available in workersChrome Full support YesEdge Full support 79Firefox Full support 53IE No support NoOpera Full support YesSafari Full support YesWebView Android Full support YesChrome Android Full support YesFirefox Android Full support 53Opera Android Full support YesSafari iOS Full support YesSamsung Internet Android Full support Yes

Legend

Full support  
Full support
No support  
No support

参见