blob: 18444eacd11bcace70f74a1abca5cd8eedc34e23 (
plain)
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
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
|
---
title: WebSocket
slug: Web/API/WebSocket
tags:
- WebSockets
translation_of: Web/API/WebSocket
original_slug: WebSockets/WebSockets_reference/WebSocket
---
<p>{{ SeeCompatTable() }}</p>
<p>{{ draft() }}</p>
<p><code>WebSocket</code> 物件提供了建立、管理 <a href="/zh_tw/WebSockets" title="zh tw/WebSockets">WebSocket</a> 伺服器連線的 API，它也有在連線中傳送、接收資料的能力。</p>
<h2 id="Method_overview" name="Method_overview">方法一覽</h2>
<table class="standard-table">
<tbody>
<tr>
<td><code>void <a href="#close()">close</a>(in optional unsigned long code, in optional DOMString reason);</code></td>
</tr>
<tr>
<td><code>void <a href="#send">send</a>(in DOMString data);</code></td>
</tr>
</tbody>
</table>
<h2 id="Attributes" name="Attributes">屬性</h2>
<table class="standard-table">
<tbody>
<tr>
<td class="header">屬性</td>
<td class="header">形態</td>
<td class="header">描述</td>
</tr>
<tr>
<td><code>binaryType</code></td>
<td>{{ DOMXref("DOMString") }}</td>
<td>表示連線傳輸的二進制資料形態的字串，若使用 {{ domxref("Blob") }} 物件則為 "blob"，使用 <a href="/zh_tw/JavaScript_typed_arrays/ArrayBuffer" title="zh tw/JavaScript typed arrays/ArrayBuffer"><code>ArrayBuffer</code></a> 物件則為 "arraybuffer"。</td>
</tr>
<tr>
<td><code>bufferedAmount</code></td>
<td><code><a href="/en/unsigned_long" title="en/unsigned long">unsigned long</a></code></td>
<td>呼叫 <a href="#send"><code>send()</code></a> 隊列但尚未傳輸至網路上資料的位元數。連線關閉時此值不會重設為零。連續呼叫 <a href="#send"><code>send()</code></a> 會讓此值不斷上升。<strong>唯讀</strong></td>
</tr>
<tr>
<td><code>extensions</code></td>
<td>{{ DOMXref("DOMString") }}</td>
<td>伺服器選擇的擴展。目前僅有空字串或表示資料經過壓縮的 "deflate-stream"。<strong>唯讀</strong></td>
</tr>
<tr>
<td><code>onclose</code></td>
<td>{{ domxref("EventListener") }}</td>
<td>當 WebSocket 連線的 <code>readyState</code> 切換至 <code>CLOSED</code> 時呼叫的事件監聽器。監聽器接收命名為 "close" 的 <a href="/zh_tw/WebSockets/WebSockets_reference/CloseEvent" title="zh tw/WebSockets/WebSockets reference/CloseEvent"><code>CloseEvent</code></a>。</td>
</tr>
<tr>
<td><code>onerror</code></td>
<td>{{ domxref("EventListener") }}</td>
<td>當錯誤發生時呼叫的事件監聽器。事件為命名 "error" 的簡單事件。</td>
</tr>
<tr>
<td><code>onmessage</code></td>
<td>{{ domxref("EventListener") }}</td>
<td>當瀏覽器接收伺服器的訊息時呼叫的事件監聽器。監聽器接收命名為 "message" 的 <a href="/zh_tw/WebSockets/WebSockets_reference/MessageEvent" title="zh tw/WebSockets/WebSockets reference/MessageEvent"><code>MessageEvent</code></a>。</td>
</tr>
<tr>
<td><code>onopen</code></td>
<td>{{ domxref("EventListener") }}</td>
<td>當 WebSocket 連線的 <code>readyState</code> 切換至 <code>OPEN</code> 時呼叫的事件監聽器，表示連線已準備傳送、接收資料。事件為命名 "open" 的簡單事件。</td>
</tr>
<tr>
<td><code>protocol</code></td>
<td>{{ DOMXref("DOMString") }}</td>
<td>伺服器選擇的子協定，這是建立 WebSocket 物件時 <code>protocols</code> 參數裡的其中一個字串。</td>
</tr>
<tr>
<td><code>readyState</code></td>
<td><code><a href="/en/unsigned_short" title="en/unsigned short">unsigned short</a></code></td>
<td>連線的目前狀態，是就緒狀態常數的其中一個。<strong>唯讀</strong></td>
</tr>
<tr>
<td><code>url</code></td>
<td>{{ DOMXref("DOMString") }}</td>
<td>建構方法解析出來的 URL，總是絕對 URL。<strong>唯讀</strong></td>
</tr>
</tbody>
</table>
<h2 id="Constants" name="Constants">常數</h2>
<h3 id="就緒狀態常數">就緒狀態常數</h3>
<p><code>readyState</code> 屬性使用以下常數描述 WebSocket 的連線狀態。</p>
<table class="standard-table">
<tbody>
<tr>
<td class="header">常數</td>
<td class="header">值</td>
<td class="header">描述</td>
</tr>
<tr>
<td><code>CONNECTING</code></td>
<td><code>0</code></td>
<td>連線尚未打開。</td>
</tr>
<tr>
<td><code>OPEN</code></td>
<td><code>1</code></td>
<td>連線已打開，可以進行通訊。</td>
</tr>
<tr>
<td><code>CLOSING</code></td>
<td><code>2</code></td>
<td>連線正在進行關閉程序。</td>
</tr>
<tr>
<td><code>CLOSED</code></td>
<td><code>3</code></td>
<td>連線已關閉／連線不能打開。</td>
</tr>
</tbody>
</table>
<h2 id="Methods" name="Methods">方法</h2>
<h3 id="close()" name="close()">close()</h3>
<p>關閉 WebSocket 連線／連線嘗試，若連線已為 <code>CLOSED</code>，此方法沒有作用。</p>
<pre class="eval">void close(
in optional unsigned short code,
in optional DOMString reason
);
</pre>
<h6 id="Parameters" name="Parameters">參數</h6>
<dl>
<dt><code>code</code> {{ optional_inline() }}</dt>
<dd>表示狀態代碼，狀態代碼用以解釋連線關閉的原因。若未指定參數，預設值為 1000（表示正常的「事務完結（transaction complete）」關閉）。請參考 <a href="/zh_tw/WebSockets/WebSockets_reference/CloseEvent" title="zh tw/WebSockets/WebSockets reference/CloseEvent"><code>CloseEvent</code></a> 頁面的<a href="/zh_tw/WebSockets/WebSockets_reference/CloseEvent#.e7.8b.80.e6.85.8b.e4.bb.a3.e7.a2.bc" title="zh tw/WebSockets/WebSockets reference/CloseEvent#.e7.8b.80.e6.85.8b.e4.bb.a3.e7.a2.bc">狀態代碼列表</a>，有所有的合法值。</dd>
<dt><code>reason</code> {{ optional_inline() }}</dt>
<dd>解釋連線關閉原因的人類可讀字串，字串必不可大於 123 個 UTF-8 字符。</dd>
</dl>
<h6 id="可丟例外">可丟例外</h6>
<dl>
<dt><code>INVALID_ACCESS_ERR</code></dt>
<dd>指定不合法的 <code>code</code>。</dd>
<dt><code>SYNTAX_ERR</code></dt>
<dd><code>reason</code> 字串太長或是含有未配對的代理對。</dd>
</dl>
<h3 id="send()" name="send()">send()</h3>
<p>透過 WebSocket 連線傳輸資料至伺服器。</p>
<pre class="eval">void send(
in DOMString data
);
void send(
in ArrayBuffer data
);
void send(
in Blob data
);
</pre>
<h6 id="Parameters" name="Parameters">參數</h6>
<dl>
<dt><code>data</code></dt>
<dd>要傳送至伺服器的字串。</dd>
</dl>
<h6 id="可丟例外_2">可丟例外</h6>
<dl>
<dt><code>INVALID_STATE_ERR</code></dt>
<dd>目前連線不為 <code>OPEN</code>。</dd>
<dt><code>SYNTAX_ERR</code></dt>
<dd>資料為帶有未配對代理對的字串。</dd>
</dl>
<h6 id="註釋">註釋</h6>
<div class="geckoVersionNote">
<p>Gecko <code>send()</code> 方法的實作與 Gecko 6.0 的規範有差別。Gecko 回傳一個 <code>boolean</code> 以表示連線是否仍處於開啟狀態（且資料成功隊列／傳輸）。另外，此時此刻，Gecko 不支援 <code><a href="/zh_tw/JavaScript_typed_arrays/ArrayBuffer" title="zh tw/JavaScript typed arrays/ArrayBuffer">ArrayBuffer</a></code> 或 {{ domxref("Blob") }} 作為資料形態。</p>
</div>
<h2 id="See_also" name="See_also">參見</h2>
<ul>
<li><a href="/zh_tw/WebSockets/Writing_WebSocket_client_applications" title="zh_tw/WebSockets/Writing WebSocket client applications">製作 WebSocket 客戶端應用程式</a></li>
<li><a class="external" href="http://dev.w3.org/html5/websockets/" title="http://dev.w3.org/html5/websockets/">HTML5: WebSockets</a></li>
</ul>
<h2 id="瀏覽器兼容">瀏覽器兼容</h2>
{{Compat("api.WebSocket")}}
|
