1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
|
---
title: EventSource
slug: Server-sent_events/EventSource
tags:
- API
- Server-sent events
- 参考
translation_of: Web/API/EventSource
---
<p>{{APIRef("Websockets API")}}</p>
<p class="summary"><code><strong>EventSource</strong></code> 是服务器推送的一个网络事件接口。一个EventSource实例会对HTTP服务开启一个持久化的连接，以<code>text/event-stream</code> 格式发送事件, 会一直保持开启直到被要求关闭。</p>
<p>一旦连接开启，来自服务端传入的消息会以事件的形式分发至你代码中。如果接收消息中有一个事件字段，触发的事件与事件字段的值相同。如果没有事件字段存在，则将触发通用事件。</p>
<p>与 <a href="/en-US/docs/Web/API/WebSockets_API">WebSockets</a>,不同的是，服务端推送是单向的。数据信息被单向从服务端到客户端分发. 当不需要以消息形式将数据从客户端发送到服务器时，这使它们成为绝佳的选择。例如，对于处理社交媒体状态更新，新闻提要或将数据传递到客户端存储机制（如IndexedDB或Web存储）之类的，EventSource无疑是一个有效方案。</p>
<h2 id="构造函数">构造函数</h2>
<dl>
<dt>{{domxref("EventSource.EventSource", "EventSource()")}}</dt>
<dd>以指定的 {{domxref("USVString")}} 创建一个新的 <code>EventSource</code>。</dd>
</dl>
<h2 id="属性">属性</h2>
<p><em>此接口从其父接口 {{domxref("EventTarget")}} 继承属性。</em></p>
<dl>
<dt>{{domxref("EventSource.onerror")}}</dt>
<dd>是一个 {{domxref("EventHandler")}}，当发生错误时被调用，并且在此对象上派发 {{event("error")}} 事件。</dd>
<dt>{{domxref("EventSource.onmessage")}}</dt>
<dd>是一个 {{domxref("EventHandler")}}，当收到一个 {{event("message")}} 事件，即消息来自源头时被调用。</dd>
<dt>{{domxref("EventSource.onopen")}}</dt>
<dd>是一个 {{domxref("EventHandler")}}，当收到一个 {{event(" open ")}} 事件，即连接刚打开时被调用。</dd>
<dt>{{domxref("EventSource.readyState")}} {{readonlyinline}}</dt>
<dd>一个 <code>unsigned </code> <code> short</code> 值，代表连接状态。可能值是 <code>CONNECTING</code> (<code>0</code>), <code>OPEN</code> (<code>1</code>), 或者 <code>CLOSED</code> (<code>2</code>)。</dd>
<dt>{{domxref("EventSource.url")}} {{readonlyinline}}</dt>
<dd>一个{{domxref("DOMString")}}，代表事件源的 URL。</dd>
</dl>
<h3 id="事件接收器">事件接收器</h3>
<dl>
<dt>{{domxref("EventSource.onerror")}}</dt>
<dd>Is an {{domxref("EventHandler")}} called when an error occurs and the {{domxref("EventSource/error_event", "error")}} event is dispatched on an <code>EventSource</code> object.</dd>
<dt>{{domxref("EventSource.onmessage")}}</dt>
<dd>Is an {{domxref("EventHandler")}} called when a {{domxref("EventSource/message_event", "message")}} event is received, that is when a message is coming from the source.</dd>
<dt>{{domxref("EventSource.onopen")}}</dt>
<dd>Is an {{domxref("EventHandler")}} called when an {{domxref("EventSource/open_event", "open")}} event is received, that is when the connection was just opened.</dd>
</dl>
<h2 id="方法">方法</h2>
<p><em>此接口从其父接口 {{domxref("EventTarget")}} 继承方法。</em></p>
<dl>
<dt>{{domxref("EventSource.close()")}}</dt>
<dd>如果存在，则关闭连接，并且设置 <code>readyState</code> 属性为 <code>CLOSED</code>。如果连接已经被关闭，此方法不会再进行任何操作。</dd>
</dl>
<h2 id="事件">事件</h2>
<dl>
<dt>{{domxref("EventSource/error_event", "error")}}</dt>
<dd>Fired when a connection to an event source failed to open.</dd>
<dt>{{domxref("EventSource/message_event", "message")}}</dt>
<dd>Fired when data is received from an event source.</dd>
<dt>{{domxref("EventSource/open_event", "open")}}</dt>
<dd>Fired when a connection to an event source has opened.</dd>
</dl>
<p>Additionally, the event source itself may send messages with an event field, which will create ad-hoc events keyed to that value.</p>
<h2 id="示例">示例</h2>
<p>In this basic example, an <code>EventSource</code> is created to receive unnamed events from the server; a page with the name <code>sse.php</code> is responsible for generating the events.</p>
<pre class="brush: js">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);
}</pre>
<p>Each received event causes our <code>EventSource</code> object's <code>onmessage</code> event handler to be run. It, in turn, creates a new {{HTMLElement("li")}} element and writes the message's data into it, then appends the new element to the list element already in the document.</p>
<div class="note">
<p><strong>Note</strong>: You can find a full example on GitHub — see <a href="https://github.com/mdn/dom-examples/tree/master/server-sent-events">Simple SSE demo using PHP.</a></p>
</div>
<p>To listen to named events, you'll require a listener for each type of event sent.</p>
<pre class="brush: js"> 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)
})
</pre>
<h2 id="规范">规范</h2>
<table class="standard-table">
<tbody>
<tr>
<th scope="col">规范</th>
<th scope="col">状态</th>
</tr>
<tr>
<td>{{SpecName('HTML WHATWG', "comms.html#the-eventsource-interface", "EventSource")}}</td>
<td>{{Spec2('HTML WHATWG')}}</td>
</tr>
</tbody>
</table>
<h2 id="浏览器兼容性">浏览器兼容性</h2>
<p>{{Compat("api.EventSource")}}</p>
<h2 id="参见">参见</h2>
<ul>
<li><a href="/zh-CN/docs/Web/API/Server-sent_events">Server-sent events</a></li>
<li><a href="/zh-CN/Server-sent_events/Using_server-sent_events">使用 Server-sent events</a></li>
</ul>
|
