diff options
Diffstat (limited to 'files/vi/web/api/eventsource/index.html')
-rw-r--r-- | files/vi/web/api/eventsource/index.html | 127 |
1 files changed, 127 insertions, 0 deletions
diff --git a/files/vi/web/api/eventsource/index.html b/files/vi/web/api/eventsource/index.html new file mode 100644 index 0000000000..36a35382dd --- /dev/null +++ b/files/vi/web/api/eventsource/index.html @@ -0,0 +1,127 @@ +--- +title: EventSource +slug: Web/API/EventSource +tags: + - API + - Communications + - EventSource + - Interface + - NeedsTranslation + - Reference + - Server Sent Events + - Server-sent events + - TopicStub + - messaging +translation_of: Web/API/EventSource +--- +<div>{{APIRef("Server Sent Events")}}</div> + +<p><span class="seoSummary">The <strong><code>EventSource</code></strong> interface is web content's interface to <a href="/en-US/docs/Web/API/Server-sent_events">server-sent events</a>. An <code>EventSource</code> instance opens a persistent connection to an <a href="/en-US/docs/Web/HTTP">HTTP</a> server, which sends <a href="/en-US/docs/Web/API/Document_Object_Model/Events">events</a> in <code>text/event-stream</code> format.</span> The connection remains open until closed by calling {{domxref("EventSource.close()")}}.</p> + +<p>Once the connection is opened, incoming messages from the server are delivered to your code in the form of {{event("message")}} events.</p> + +<p>Unlike <a href="/en-US/docs/Web/API/WebSockets_API">WebSockets</a>, server-sent events are unidirectional; that is, data messages are delivered in one direction, from the server to the client (such as a user's web browser). That makes them an excellent choice when there's no need to send data from the client to the server in message form. For example, <code>EventSource</code> is a useful approach for handling things like social media status updates, news feeds, or delivering data into a <a href="/en-US/docs/Learn/JavaScript/Client-side_web_APIs/Client-side_storage">client-side storage</a> mechanism like <a href="/en-US/docs/Web/API/IndexedDB_API">IndexedDB</a> or <a href="/en-US/docs/Web/API/Web_Storage_API">web storage</a>.</p> + +<h2 id="Constructor">Constructor</h2> + +<dl> + <dt>{{domxref("EventSource.EventSource", "EventSource()")}}</dt> + <dd>Creates a new <code>EventSource</code> to handle receiving server-sent events from a specified URL, optionally in credentials mode.</dd> +</dl> + +<h2 id="Properties">Properties</h2> + +<p><em>This interface also inherits properties from its parent, {{domxref("EventTarget")}}.</em></p> + +<dl> + <dt>{{domxref("EventSource.readyState")}} {{readonlyinline}}</dt> + <dd>A number representing the state of the connection. Possible values are <code>CONNECTING</code> (<code>0</code>), <code>OPEN</code> (<code>1</code>), or <code>CLOSED</code> (<code>2</code>).</dd> + <dt>{{domxref("EventSource.url")}} {{readonlyinline}}</dt> + <dd>A {{domxref("DOMString")}} representing the URL of the source.</dd> + <dt>{{domxref("EventSource.withCredentials")}} {{readonlyinline}}</dt> + <dd>A {{domxref("Boolean")}} indicating whether the <code>EventSource</code> object was instantiated with cross-origin (<a href="/en-US/docs/Web/HTTP/CORS">CORS</a>) credentials set (<code>true</code>), or not (<code>false</code>, the default).</dd> +</dl> + +<h3 id="Event_handlers">Event handlers</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="Methods">Methods</h2> + +<p><em>This interface also inherits methods from its parent, {{domxref("EventTarget")}}.</em></p> + +<dl> + <dt>{{domxref("EventSource.close()")}}</dt> + <dd>Closes the connection, if any, and sets the <code>readyState</code> attribute to <code>CLOSED</code>. If the connection is already closed, the method does nothing.</dd> +</dl> + +<h2 id="Events">Events</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> + +<h2 id="Examples">Examples</h2> + +<p>In this basic example, an <code>EventSource</code> is created to receive 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> + +<h2 id="Specifications">Specifications</h2> + +<table class="standard-table"> + <tbody> + <tr> + <th scope="col">Specification</th> + <th scope="col">Status</th> + </tr> + <tr> + <td>{{SpecName('HTML WHATWG', "comms.html#the-eventsource-interface", "EventSource")}}</td> + <td>{{Spec2('HTML WHATWG')}}</td> + </tr> + </tbody> +</table> + +<ul> +</ul> + +<h2 id="Browser_compatibility">Browser compatibility</h2> + +<div> + + +<p>{{Compat("api.EventSource")}}</p> +</div> + +<h2 id="See_also">See also</h2> + +<ul> + <li><a href="/en-US/docs/Web/API/Server-sent_events">Server-sent events</a></li> + <li><a href="/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events">Using server-sent events</a></li> +</ul> |