1# WebSocket连接
2
3## 场景介绍
4
5使用WebSocket建立服务器与客户端的双向连接，需要先通过createWebSocket()方法创建WebSocket对象，然后通过connect()方法连接到服务器。当连接成功后，客户端会收到open事件的回调，之后客户端就可以通过send()方法与服务器进行通信。当服务器发信息给客户端时，客户端会收到message事件的回调。当客户端不要此连接时，可以通过调用close()方法主动断开连接，之后客户端会收到close事件的回调。
6
7若在上述任一过程中发生错误，客户端会收到error事件的回调。
8
9## 接口说明
10
11WebSocket连接功能主要由webSocket模块提供。使用该功能需要申请ohos.permission.INTERNET权限。具体接口说明如下表。
12
13| 接口名              | 描述                                      |
14| ------------------ | ----------------------------------------- |
15| createWebSocket()  | 创建一个WebSocket连接。                    |
16| connect()          | 根据URL地址，建立一个WebSocket连接。       |
17| send()             | 通过WebSocket连接发送数据。                |
18| close()            | 关闭WebSocket连接。                        |
19| on(type: 'open')   | 订阅WebSocket的打开事件。                  |
20| off(type: 'open')   | 取消订阅WebSocket的打开事件。             |
21| on(type: 'message') | 订阅WebSocket的接收到服务器消息事件。      |
22| off(type: 'message') | 取消订阅WebSocket的接收到服务器消息事件。 |
23| on(type: 'close')   | 订阅WebSocket的关闭事件。                 |
24| off(type: 'close') | 取消订阅WebSocket的关闭事件                |
25| on(type: 'error')  | 订阅WebSocket的Error事件。                 |
26| off(type: 'error') | 取消订阅WebSocket的Error事件。             |
27
28## 开发步骤
29
301. 导入需要的webSocket模块。
31
322. 创建一个WebSocket连接，返回一个WebSocket对象。
33
343. （可选）订阅WebSocket的打开、消息接收、关闭、Error事件。
35
364. 根据URL地址，发起WebSocket连接。
37
385. 使用完WebSocket连接之后，主动断开连接。
39
40```js
41import { webSocket } from '@kit.NetworkKit';
42import { BusinessError } from '@kit.BasicServicesKit';
43
44let defaultIpAddress = "ws://";
45let ws = webSocket.createWebSocket();
46ws.on('open', (err: BusinessError, value: Object) => {
47  console.log("on open, status:" + JSON.stringify(value));
48  // 当收到on('open')事件时，可以通过send()方法与服务器进行通信
49  ws.send("Hello, server!", (err: BusinessError, value: boolean) => {
50    if (!err) {
51      console.log("Message sent successfully");
52    } else {
53      console.log("Failed to send the message. Err:" + JSON.stringify(err));
54    }
55  });
56});
57ws.on('message', (err: BusinessError, value: string | ArrayBuffer) => {
58  console.log("on message, message:" + value);
59  // 当收到服务器的`bye`消息时（此消息字段仅为示意，具体字段需要与服务器协商），主动断开连接
60  if (value === 'bye') {
61    ws.close((err: BusinessError, value: boolean) => {
62      if (!err) {
63        console.log("Connection closed successfully");
64      } else {
65        console.log("Failed to close the connection. Err: " + JSON.stringify(err));
66      }
67    });
68  }
69});
70ws.on('close', (err: BusinessError, value: webSocket.CloseResult) => {
71  console.log("on close, code is " + value.code + ", reason is " + value.reason);
72});
73ws.on('error', (err: BusinessError) => {
74  console.log("on error, error:" + JSON.stringify(err));
75});
76ws.connect(defaultIpAddress, (err: BusinessError, value: boolean) => {
77  if (!err) {
78    console.log("Connected successfully");
79  } else {
80    console.log("Connection failed. Err:" + JSON.stringify(err));
81  }
82});
83```
84
85## 相关实例
86
87针对WebSocket连接的开发，有以下相关实例可供参考：
88
89- [WebSocket（ArkTS）（API9）](https://gitee.com/openharmony/applications_app_samples/tree/master/code/BasicFeature/Connectivity/WebSocket)