• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# WebSocket连接
2
3>![](public_sys-resources/icon-note.gif) **说明：**
4>本模块首批接口从API version 6开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
5>
6
7使用WebSocket建立服务器与客户端的双向连接，需要先通过[createWebSocket](#websocketcreatewebsocket)方法创建[WebSocket](#websocket)对象，然后通过[connect](#connect)方法连接到服务器。当连接成功后，客户端会收到[open](#onopen)事件的回调，之后客户端就可以通过[send](#send)方法与服务器进行通信。当服务器发信息给客户端时，客户端会收到[message](#onmessage)事件的回调。当客户端不要此连接时，可以通过调用[close](#close)方法主动断开连接，之后客户端会收到[close](#onclose)事件的回调。
8
9若在上述任一过程中发生错误，客户端会收到[error](#onerror)事件的回调。
10
11
12## 导入模块
13
14```js
15import webSocket from '@ohos.net.webSocket';
16```
17
18## 完整示例
19
20```js
21import webSocket from '@ohos.net.webSocket';
22
23var defaultIpAddress = "ws://";
24let ws = webSocket.createWebSocket();
25ws.on('open', (err, value) => {
26    console.log("on open, status:" + value['status'] + ", message:" + value['message']);
27    // 当收到on('open')事件时，可以通过send()方法与服务器进行通信
28    ws.send("Hello, server!", (err, value) => {
29        if (!err) {
30            console.log("send success");
31        } else {
32            console.log("send fail, err:" + JSON.stringify(err));
33        }
34    });
35});
36ws.on('message', (err, value) => {
37    console.log("on message, message:" + value);
38    // 当收到服务器的`bye`消息时（此消息字段仅为示意，具体字段需要与服务器协商），主动断开连接
39    if (value === 'bye') {
40        ws.close((err, value) => {
41            if (!err) {
42                console.log("close success");
43            } else {
44                console.log("close fail, err is " + JSON.stringify(err));
45            }
46        });
47    }
48});
49ws.on('close', (err, value) => {
50    console.log("on close, code is " + value.code + ", reason is " + value.reason);
51});
52ws.on('error', (err) => {
53    console.log("on error, error:" + JSON.stringify(err));
54});
55ws.connect(defaultIpAddress, (err, value) => {
56    if (!err) {
57        console.log("connect success");
58    } else {
59        console.log("connect fail, err:" + JSON.stringify(err));
60    }
61});
62```
63
64## webSocket.createWebSocket
65
66createWebSocket\(\): WebSocket
67
68创建一个WebSocket，里面包括建立连接、关闭连接、发送数据和订阅/取消订阅WebSocket连接的打开事件、接收到服务器消息事件、关闭事件和错误事件。
69
70**系统能力**：SystemCapability.Communication.NetStack
71
72**返回值：**
73
74| 类型                                | 说明                                                         |
75| :---------------------------------- | :----------------------------------------------------------- |
76| [WebSocket](#websocket) | 返回一个WebSocket对象，里面包括connect、send、close、on和off方法。 |
77
78**示例：**
79
80```js
81let ws = webSocket.createWebSocket();
82```
83
84
85## WebSocket
86
87在调用WebSocket的方法前，需要先通过[webSocket.createWebSocket](#websocketcreatewebsocket)创建一个WebSocket。
88
89### connect
90
91connect\(url: string, callback: AsyncCallback<boolean\>\): void
92
93根据URL地址，建立一个WebSocket连接，使用callback方式作为异步方法。
94
95**需要权限**：ohos.permission.INTERNET
96
97**系统能力**：SystemCapability.Communication.NetStack
98
99**参数：**
100
101| 参数名   | 类型                     | 必填 | 说明                         |
102| -------- | ------------------------ | ---- | ---------------------------- |
103| url      | string                   | 是   | 建立WebSocket连接的URL地址。 |
104| callback | AsyncCallback\<boolean\> | 是   | 回调函数。                   |
105
106
107**示例：**
108
109```js
110let ws = webSocket.createWebSocket();
111let url = "ws://"
112ws.connect(url, (err, value) => {
113	if (!err) {
114		console.log("connect success");
115	} else {
116		console.log("connect fail, err:" + JSON.stringify(err))
117	}
118});
119```
120
121
122### connect
123
124connect\(url: string, options: WebSocketRequestOptions, callback: AsyncCallback<boolean\>\): void
125
126根据URL地址和header，建立一个WebSocket连接，使用callback方式作为异步方法。
127
128**需要权限**：ohos.permission.INTERNET
129
130**系统能力**：SystemCapability.Communication.NetStack
131
132**参数：**
133
134| 参数名   | 类型                     | 必填 | 说明                                                    |
135| -------- | ------------------------ | ---- | ------------------------------------------------------- |
136| url      | string                   | 是   | 建立WebSocket连接的URL地址。                            |
137| options  | WebSocketRequestOptions  | 是   | 参考[WebSocketRequestOptions](#websocketrequestoptions)。 |
138| callback | AsyncCallback\<boolean\> | 是   | 回调函数。                                              |
139
140
141**示例：**
142
143```js
144let ws = webSocket.createWebSocket();
145let url = "ws://"
146ws.connect(url, {
147	header: {
148		"key": "value",
149		"key2": "value2"
150	}
151}, (err, value) => {
152	if (!err) {
153		console.log("connect success");
154	} else {
155		console.log("connect fail, err:" + JSON.stringify(err))
156	}
157});
158```
159
160
161### connect
162
163connect\(url: string, options?: WebSocketRequestOptions\): Promise<boolean\>
164
165根据URL地址和header，建立一个WebSocket连接，使用Promise方式作为异步方法。
166
167**需要权限**：ohos.permission.INTERNET
168
169**系统能力**：SystemCapability.Communication.NetStack
170
171**参数：**
172
173| 参数名  | 类型                    | 必填 | 说明                                                    |
174| ------- | ----------------------- | ---- | ------------------------------------------------------- |
175| url     | string                  | 是   | 建立WebSocket连接的URL地址。                            |
176| options | WebSocketRequestOptions | 否   | 参考[WebSocketRequestOptions](#websocketrequestoptions)。 |
177
178**返回值：**
179
180| 类型               | 说明                              |
181| :----------------- | :-------------------------------- |
182| Promise\<boolean\> | 以Promise形式返回建立连接的结果。 |
183
184**示例：**
185
186```js
187let ws = webSocket.createWebSocket();
188let url = "ws://"
189let promise = ws.connect(url);
190promise.then((value) => {
191	console.log("connect success")
192}).catch((err) => {
193	console.log("connect fail, error:" + JSON.stringify(err))
194});
195```
196
197
198### send
199
200send\(data: string | ArrayBuffer, callback: AsyncCallback<boolean\>\): void
201
202通过WebSocket连接发送数据，使用callback方式作为异步方法。
203
204**需要权限**：ohos.permission.INTERNET
205
206**系统能力**：SystemCapability.Communication.NetStack
207
208**参数：**
209
210| 参数名   | 类型                     | 必填 | 说明         |
211| -------- | ------------------------ | ---- | ------------ |
212| data     | string \| ArrayBuffer <sup>8+</sup> | 是   | 发送的数据。 |
213| callback | AsyncCallback\<boolean\> | 是   | 回调函数。   |
214
215**示例：**
216
217```js
218let ws = webSocket.createWebSocket();
219let url = "ws://"
220ws.connect(url, (err, value) => {
221	ws.send("Hello, server!", (err, value) => {
222		if (!err) {
223			console.log("send success");
224		} else {
225			console.log("send fail, err:" + JSON.stringify(err))
226		}
227	});
228});
229```
230
231
232### send
233
234send\(data: string | ArrayBuffer\): Promise<boolean\>
235
236通过WebSocket连接发送数据，使用Promise方式作为异步方法。
237
238**需要权限**：ohos.permission.INTERNET
239
240**系统能力**：SystemCapability.Communication.NetStack
241
242**参数：**
243
244| 参数名 | 类型   | 必填 | 说明         |
245| ------ | ------ | ---- | ------------ |
246| data     | string \| ArrayBuffer <sup>8+</sup> | 是   | 发送的数据。 |
247
248**返回值：**
249
250| 类型               | 说明                              |
251| :----------------- | :-------------------------------- |
252| Promise\<boolean\> | 以Promise形式返回发送数据的结果。 |
253
254**示例：**
255
256```js
257let ws = webSocket.createWebSocket();
258let url = "ws://"
259ws.connect(url, (err, value) => {
260	let promise = ws.send("Hello, server!");
261	promise.then((value) => {
262		console.log("send success")
263	}).catch((err) => {
264		console.log("send fail, error:" + JSON.stringify(err))
265	});
266});
267```
268
269
270### close
271
272close\(callback: AsyncCallback<boolean\>\): void
273
274关闭WebSocket连接，使用callback方式作为异步方法。
275
276**需要权限**：ohos.permission.INTERNET
277
278**系统能力**：SystemCapability.Communication.NetStack
279
280**参数：**
281
282| 参数名   | 类型                     | 必填 | 说明       |
283| -------- | ------------------------ | ---- | ---------- |
284| callback | AsyncCallback\<boolean\> | 是   | 回调函数。 |
285
286**示例：**
287
288```js
289let ws = webSocket.createWebSocket();
290let url = "ws://"
291ws.close((err, value) => {
292	if (!err) {
293		console.log("close success")
294	} else {
295		console.log("close fail, err is " + JSON.stringify(err))
296	}
297});
298```
299
300
301### close
302
303close\(options: WebSocketCloseOptions, callback: AsyncCallback<boolean\>\): void
304
305根据可选参数code和reason，关闭WebSocket连接，使用callback方式作为异步方法。
306
307**需要权限**：ohos.permission.INTERNET
308
309**系统能力**：SystemCapability.Communication.NetStack
310
311**参数：**
312
313| 参数名   | 类型                     | 必填 | 说明                                                  |
314| -------- | ------------------------ | ---- | ----------------------------------------------------- |
315| options  | WebSocketCloseOptions    | 是   | 参考[WebSocketCloseOptions](#websocketcloseoptions)。 |
316| callback | AsyncCallback\<boolean\> | 是   | 回调函数。                                            |
317
318**示例：**
319
320```js
321let ws = webSocket.createWebSocket();
322let url = "ws://"
323ws.close({
324	code: 1000,
325	reason: "your reason"
326}, (err, value) => {
327	if (!err) {
328		console.log("close success")
329	} else {
330		console.log("close fail, err is " + JSON.stringify(err))
331	}
332});
333```
334
335
336### close
337
338close\(options?: WebSocketCloseOptions\): Promise<boolean\>
339
340根据可选参数code和reason，关闭WebSocket连接，使用Promise方式作为异步方法。
341
342**需要权限**：ohos.permission.INTERNET
343
344**系统能力**：SystemCapability.Communication.NetStack
345
346**参数：**
347
348| 参数名  | 类型                  | 必填 | 说明                                                  |
349| ------- | --------------------- | ---- | ----------------------------------------------------- |
350| options | WebSocketCloseOptions | 否   | 参考[WebSocketCloseOptions](#websocketcloseoptions)。 |
351
352**返回值：**
353
354| 类型               | 说明                              |
355| :----------------- | :-------------------------------- |
356| Promise\<boolean\> | 以Promise形式返回关闭连接的结果。 |
357
358**示例：**
359
360```js
361let ws = webSocket.createWebSocket();
362let url = "ws://"
363let promise = ws.close({
364	code: 1000,
365	reason: "your reason"
366});
367promise.then((value) => {
368	console.log("close success")
369}).catch((err) => {
370	console.log("close fail, err is " + JSON.stringify(err))
371});
372```
373
374
375### on\('open'\)
376
377on\(type: 'open', callback: AsyncCallback<Object\>\): void
378
379订阅WebSocket的打开事件，使用callback方式作为异步方法。
380
381**系统能力**：SystemCapability.Communication.NetStack
382
383**参数：**
384
385| 参数名   | 类型                    | 必填 | 说明                          |
386| -------- | ----------------------- | ---- | ----------------------------- |
387| type     | string                  | 是   | 'open'：WebSocket的打开事件。 |
388| callback | AsyncCallback\<Object\> | 是   | 回调函数。                    |
389
390
391**示例：**
392
393```js
394let ws = webSocket.createWebSocket();
395ws.on('open', (err, value) => {
396	console.log("on open, status:" + value['status'] + ", message:" + value['message']);
397});
398```
399
400
401### off\('open'\)
402
403off\(type: 'open', callback?: AsyncCallback<Object\>\): void
404
405取消订阅WebSocket的打开事件，使用callback方式作为异步方法。
406
407>![](public_sys-resources/icon-note.gif) **说明：**
408>可以指定传入on中的callback取消一个订阅，也可以不指定callback清空所有订阅。
409
410**系统能力**：SystemCapability.Communication.NetStack
411
412**参数：**
413
414| 参数名   | 类型                    | 必填 | 说明                          |
415| -------- | ----------------------- | ---- | ----------------------------- |
416| type     | string                  | 是   | 'open'：WebSocket的打开事件。 |
417| callback | AsyncCallback\<Object\> | 否   | 回调函数。                    |
418
419**示例：**
420
421```js
422let ws = webSocket.createWebSocket();
423let callback1 = (err, value) => {
424	console.log("on open, status:" + value['status'] + ", message:" + value['message']);
425}
426ws.on('open', callback1);
427// 可以指定传入on中的callback取消一个订阅，也可以不指定callback清空所有订阅
428ws.off('open', callback1);
429```
430
431
432### on\('message'\)
433
434on\(type: 'message', callback: AsyncCallback<string | ArrayBuffer\>\): void
435
436订阅WebSocket的接收到服务器消息事件，使用callback方式作为异步方法。
437
438>![](public_sys-resources/icon-note.gif) **说明：**
439>AsyncCallback中的数据可以是字符串\(API 6\)或ArrayBuffer\(API 8\)。
440
441**系统能力**：SystemCapability.Communication.NetStack
442
443**参数：**
444
445| 参数名   | 类型                    | 必填 | 说明                                         |
446| -------- | ----------------------- | ---- | -------------------------------------------- |
447| type     | string                  | 是   | 'message'：WebSocket的接收到服务器消息事件。 |
448| callback | AsyncCallback\<string \| ArrayBuffer <sup>8+</sup>\> | 是   | 回调函数。                                   |
449
450
451**示例：**
452
453```js
454let ws = webSocket.createWebSocket();
455ws.on('message', (err, value) => {
456	console.log("on message, message:" + value);
457});
458```
459
460
461### off\('message'\)
462
463off\(type: 'message', callback?: AsyncCallback<string | ArrayBuffer\>\): void
464
465取消订阅WebSocket的接收到服务器消息事件，使用callback方式作为异步方法。
466
467>![](public_sys-resources/icon-note.gif) **说明：**
468>AsyncCallback中的数据可以是字符串\(API 6\)或ArrayBuffer\(API 8\)。
469>可以指定传入on中的callback取消一个订阅，也可以不指定callback清空所有订阅。
470
471**系统能力**：SystemCapability.Communication.NetStack
472
473**参数：**
474
475| 参数名   | 类型                                                | 必填 | 说明                                         |
476| -------- | --------------------------------------------------- | ---- | -------------------------------------------- |
477| type     | string                                              | 是   | 'message'：WebSocket的接收到服务器消息事件。 |
478| callback | AsyncCallback\<string \|ArrayBuffer <sup>8+</sup>\> | 否   | 回调函数。                                   |
479
480**示例：**
481
482```js
483let ws = webSocket.createWebSocket();
484ws.off('message');
485```
486
487
488### on\('close'\)
489
490on\(type: 'close', callback: AsyncCallback<\{ code: number, reason: string \}\>\): void
491
492订阅WebSocket的关闭事件，使用callback方式作为异步方法。
493
494**系统能力**：SystemCapability.Communication.NetStack
495
496**参数：**
497
498| 参数名   | 类型                                            | 必填 | 说明                           |
499| -------- | ----------------------------------------------- | ---- | ------------------------------ |
500| type     | string                                          | 是   | 'close'：WebSocket的关闭事件。 |
501| callback | AsyncCallback<{ code: number, reason: string }> | 是   | 回调函数。                     |
502
503**示例：**
504
505```js
506let ws = webSocket.createWebSocket();
507ws.on('close', (err, value) => {
508	console.log("on close, code is " + value.code + ", reason is " + value.reason);
509});
510```
511
512
513### off\('close'\)
514
515off\(type: 'close', callback?: AsyncCallback<\{ code: number, reason: string \}\>\): void
516
517取消订阅WebSocket的关闭事件，使用callback方式作为异步方法。
518
519>![](public_sys-resources/icon-note.gif) **说明：**
520>可以指定传入on中的callback取消一个订阅，也可以不指定callback清空所有订阅。
521
522**系统能力**：SystemCapability.Communication.NetStack
523
524**参数：**
525
526| 参数名   | 类型                                            | 必填 | 说明                           |
527| -------- | ----------------------------------------------- | ---- | ------------------------------ |
528| type     | string                                          | 是   | 'close'：WebSocket的关闭事件。 |
529| callback | AsyncCallback<{ code: number, reason: string }> | 否   | 回调函数。                     |
530
531
532**示例：**
533
534```js
535let ws = webSocket.createWebSocket();
536ws.off('close');
537```
538
539
540### on\('error'\)
541
542on\(type: 'error', callback: ErrorCallback\): void
543
544订阅WebSocket的Error事件，使用callback方式作为异步方法。
545
546**系统能力**：SystemCapability.Communication.NetStack
547
548**参数：**
549
550| 参数名   | 类型          | 必填 | 说明                            |
551| -------- | ------------- | ---- | ------------------------------- |
552| type     | string        | 是   | 'error'：WebSocket的Error事件。 |
553| callback | ErrorCallback | 是   | 回调函数。                      |
554
555
556**示例：**
557
558```js
559let ws = webSocket.createWebSocket();
560ws.on('error', (err) => {
561	console.log("on error, error:" + JSON.stringify(err))
562});
563```
564
565
566### off\('error'\)
567
568off\(type: 'error', callback?: ErrorCallback\): void
569
570取消订阅WebSocket的Error事件，使用callback方式作为异步方法。
571
572>![](public_sys-resources/icon-note.gif) **说明：**
573>可以指定传入on中的callback取消一个订阅，也可以不指定callback清空所有订阅。
574
575**系统能力**：SystemCapability.Communication.NetStack
576
577**参数：**
578
579| 参数名   | 类型          | 必填 | 说明                            |
580| -------- | ------------- | ---- | ------------------------------- |
581| type     | string        | 是   | 'error'：WebSocket的Error事件。 |
582| callback | ErrorCallback | 否   | 回调函数。                      |
583
584**示例：**
585
586```js
587let ws = webSocket.createWebSocket();
588ws.off('error');
589```
590
591
592## WebSocketRequestOptions
593
594建立WebSocket连接时，可选参数的类型和说明。
595
596**系统能力**：以下各项对应的系统能力均为SystemCapability.Communication.NetStack。
597
598| 参数名 | 类型   | 必填 | 说明                                                         |
599| ------ | ------ | ---- | ------------------------------------------------------------ |
600| header | Object | 否   | 建立WebSocket连接可选参数，代表建立连接时携带的HTTP头信息。参数内容自定义，也可以不指定。 |
601
602
603## WebSocketCloseOptions
604
605关闭WebSocket连接时，可选参数的类型和说明。
606
607**系统能力**：以下各项对应的系统能力均为SystemCapability.Communication.NetStack。
608
609| 参数名 | 类型   | 必填 | 说明                                                         |
610| ------ | ------ | ---- | ------------------------------------------------------------ |
611| code   | number | 否   | 错误码，关闭WebSocket连接时的可选参数，可根据实际情况来填。默认值为1000。 |
612| reason | string | 否   | 原因值，关闭WebSocket连接时的可选参数，可根据实际情况来填。默认值为空字符串（""）。 |
613
614## close错误码说明
615
616发送给服务端的错误码可以自行定义，下面的列表仅供参考。
617
618**系统能力**：以下各项对应的系统能力均为SystemCapability.Communication.NetStack。
619
620| 值        | 说明               |
621| :-------- | :----------------- |
622| 1000      | 正常关闭           |
623| 1001      | 服务器主动关闭     |
624| 1002      | 协议错误           |
625| 1003      | 无法处理的数据类型 |
626| 1004~1015 | 保留值             |
627
628