WebSocket连接

说明： 本模块首批接口从API version 6开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。

使用WebSocket建立服务器与客户端的双向连接，需要先通过[createWebSocket]方法创建[WebSocket]对象，然后通过[connect]方法连接到服务器。当连接成功后，客户端会收到[open]事件的回调，之后客户端就可以通过[send]方法与服务器进行通信。当服务器发信息给客户端时，客户端会收到[message]事件的回调。当客户端不要此连接时，可以通过调用[close]方法主动断开连接，之后客户端会收到[close]事件的回调。

若在上述任一过程中发生错误，客户端会收到[error]事件的回调。

导入模块

import webSocket from '@ohos.net.webSocket';

完整示例

import webSocket from '@ohos.net.webSocket';

var defaultIpAddress = "ws://";
let ws = webSocket.createWebSocket();
ws.on('open', (err, value) = > {
    console.log("on open, status:" + value['status'] + ", message:" + value['message']);
    // 当收到on('open')事件时，可以通过send()方法与服务器进行通信
    ws.send("Hello, server!", (err, value) = > {
        if (!err) {
            console.log("send success");
        } else {
            console.log("send fail, err:" + JSON.stringify(err));
        }
    });
});
ws.on('message', (err, value) = > {
    console.log("on message, message:" + value);
    // 当收到服务器的`bye`消息时（此消息字段仅为示意，具体字段需要与服务器协商），主动断开连接
    if (value === 'bye') {
        ws.close((err, value) = > {
            if (!err) {
                console.log("close success");
            } else {
                console.log("close fail, err is " + JSON.stringify(err));
            }
        });
    }
});
ws.on('close', (err, value) = > {
    console.log("on close, code is " + value.code + ", reason is " + value.reason);
});
ws.on('error', (err) = > {
    console.log("on error, error:" + JSON.stringify(err));
});
ws.connect(defaultIpAddress, (err, value) = > {
    if (!err) {
        console.log("connect success");
    } else {
        console.log("connect fail, err:" + JSON.stringify(err));
    }
});

webSocket.createWebSocket

createWebSocket(): WebSocket

创建一个WebSocket，里面包括建立连接、关闭连接、发送数据和订阅/取消订阅WebSocket连接的打开事件、接收到服务器消息事件、关闭事件和错误事件。

系统能力 ：SystemCapability.Communication.NetStack

返回值：

类型	说明
[WebSocket]	返回一个WebSocket对象，里面包括connect、send、close、on和off方法。

示例：

let ws = webSocket.createWebSocket();

WebSocket

在调用WebSocket的方法前，需要先通过[webSocket.createWebSocket]创建一个WebSocket。

connect

connect(url: string, callback: AsyncCallback): void

根据URL地址，建立一个WebSocket连接，使用callback方式作为异步方法。

需要权限 ：ohos.permission.INTERNET

系统能力 ：SystemCapability.Communication.NetStack

参数：

参数名	类型	必填	说明
url	string	是	建立WebSocket连接的URL地址。
callback	AsyncCallback	是	回调函数。

示例：

let ws = webSocket.createWebSocket();
let url = "ws://"
ws.connect(url, (err, value) = > {
	if (!err) {
		console.log("connect success");
	} else {
		console.log("connect fail, err:" + JSON.stringify(err))
	}
});

connect

connect(url: string, options: WebSocketRequestOptions, callback: AsyncCallback): void

根据URL地址和header，建立一个WebSocket连接，使用callback方式作为异步方法。

需要权限 ：ohos.permission.INTERNET

系统能力 ：SystemCapability.Communication.NetStack

参数：

参数名	类型	必填	说明
url	string	是	建立WebSocket连接的URL地址。
options	WebSocketRequestOptions	是	参考[WebSocketRequestOptions]。
callback	AsyncCallback	是	回调函数。

示例：

let ws = webSocket.createWebSocket();
let url = "ws://"
ws.connect(url, {
	header: {
		"key": "value",
		"key2": "value2"
	}
}, (err, value) = > {
	if (!err) {
		console.log("connect success");
	} else {
		console.log("connect fail, err:" + JSON.stringify(err))
	}
});

connect

connect(url: string, options?: WebSocketRequestOptions): Promise

根据URL地址和header，建立一个WebSocket连接，使用Promise方式作为异步方法。

需要权限 ：ohos.permission.INTERNET

系统能力 ：SystemCapability.Communication.NetStack

参数：

参数名	类型	必填	说明
url	string	是	建立WebSocket连接的URL地址。
options	WebSocketRequestOptions	否	参考[WebSocketRequestOptions]。

返回值：

类型	说明
Promise	以Promise形式返回建立连接的结果。

示例：

let ws = webSocket.createWebSocket();
let url = "ws://"
let promise = ws.connect(url);
promise.then((value) = > {
	console.log("connect success")
}).catch((err) = > {
	console.log("connect fail, error:" + JSON.stringify(err))
});

send

send(data: string | ArrayBuffer, callback: AsyncCallback): void

通过WebSocket连接发送数据，使用callback方式作为异步方法。

需要权限 ：ohos.permission.INTERNET

系统能力 ：SystemCapability.Communication.NetStack

参数：

参数名	类型	必填	说明
data	string	ArrayBuffer 8+	是
callback	AsyncCallback	是	回调函数。

示例：

let ws = webSocket.createWebSocket();
let url = "ws://"
ws.connect(url, (err, value) = > {
	ws.send("Hello, server!", (err, value) = > {
		if (!err) {
			console.log("send success");
		} else {
			console.log("send fail, err:" + JSON.stringify(err))
		}
	});
});

send

send(data: string | ArrayBuffer): Promise

通过WebSocket连接发送数据，使用Promise方式作为异步方法。

需要权限 ：ohos.permission.INTERNET

系统能力 ：SystemCapability.Communication.NetStack

参数：

参数名	类型	必填	说明
data	string	ArrayBuffer 8+	是

返回值：

类型	说明
Promise	以Promise形式返回发送数据的结果。

示例：

let ws = webSocket.createWebSocket();
let url = "ws://"
ws.connect(url, (err, value) = > {
	let promise = ws.send("Hello, server!");
	promise.then((value) = > {
		console.log("send success")
	}).catch((err) = > {
		console.log("send fail, error:" + JSON.stringify(err))
	});
});

close

close(callback: AsyncCallback): void

关闭WebSocket连接，使用callback方式作为异步方法。

需要权限 ：ohos.permission.INTERNET

系统能力 ：SystemCapability.Communication.NetStack

参数：

参数名	类型	必填	说明
callback	AsyncCallback	是	回调函数。

示例：

let ws = webSocket.createWebSocket();
let url = "ws://"
ws.close((err, value) = > {
	if (!err) {
		console.log("close success")
	} else {
		console.log("close fail, err is " + JSON.stringify(err))
	}
});

close

close(options: WebSocketCloseOptions, callback: AsyncCallback): void

根据可选参数code和reason，关闭WebSocket连接，使用callback方式作为异步方法。

需要权限 ：ohos.permission.INTERNET

系统能力 ：SystemCapability.Communication.NetStack

参数：

参数名	类型	必填	说明
options	WebSocketCloseOptions	是	参考[WebSocketCloseOptions]。
callback	AsyncCallback	是	回调函数。

示例：

let ws = webSocket.createWebSocket();
let url = "ws://"
ws.close({
	code: 1000,
	reason: "your reason"
}, (err, value) = > {
	if (!err) {
		console.log("close success")
	} else {
		console.log("close fail, err is " + JSON.stringify(err))
	}
});

close

close(options?: WebSocketCloseOptions): Promise

根据可选参数code和reason，关闭WebSocket连接，使用Promise方式作为异步方法。

需要权限 ：ohos.permission.INTERNET

系统能力 ：SystemCapability.Communication.NetStack

参数：

参数名	类型	必填	说明
options	WebSocketCloseOptions	否	参考[WebSocketCloseOptions]。

返回值：

类型	说明
Promise	以Promise形式返回关闭连接的结果。

示例：

let ws = webSocket.createWebSocket();
let url = "ws://"
let promise = ws.close({
	code: 1000,
	reason: "your reason"
});
promise.then((value) = > {
	console.log("close success")
}).catch((err) = > {
	console.log("close fail, err is " + JSON.stringify(err))
});

on('open')

on(type: 'open', callback: AsyncCallback ): void

订阅WebSocket的打开事件，使用callback方式作为异步方法。

系统能力 ：SystemCapability.Communication.NetStack

参数：

参数名	类型	必填	说明
type	string	是	'open'：WebSocket的打开事件。
callback	AsyncCallback	是	回调函数。

示例：

let ws = webSocket.createWebSocket();
ws.on('open', (err, value) = > {
	console.log("on open, status:" + value['status'] + ", message:" + value['message']);
});

off('open')

off(type: 'open', callback?: AsyncCallback ): void

取消订阅WebSocket的打开事件，使用callback方式作为异步方法。

说明： 可以指定传入on中的callback取消一个订阅，也可以不指定callback清空所有订阅。

系统能力 ：SystemCapability.Communication.NetStack

参数：

参数名	类型	必填	说明
type	string	是	'open'：WebSocket的打开事件。
callback	AsyncCallback	否	回调函数。

示例：

let ws = webSocket.createWebSocket();
let callback1 = (err, value) = > {
	console.log("on open, status:" + value['status'] + ", message:" + value['message']);
}
ws.on('open', callback1);
// 可以指定传入on中的callback取消一个订阅，也可以不指定callback清空所有订阅
ws.off('open', callback1);

on('message')

on(type: 'message', callback: AsyncCallback): void

订阅WebSocket的接收到服务器消息事件，使用callback方式作为异步方法。

说明： AsyncCallback中的数据可以是字符串(API 6)或ArrayBuffer(API 8)。

系统能力 ：SystemCapability.Communication.NetStack

参数：

参数名	类型	必填	说明
type	string	是	'message'：WebSocket的接收到服务器消息事件。
callback	AsyncCallback	是	回调函数。

示例：

let ws = webSocket.createWebSocket();
ws.on('message', (err, value) = > {
	console.log("on message, message:" + value);
});

off('message')

off(type: 'message', callback?: AsyncCallback): void

取消订阅WebSocket的接收到服务器消息事件，使用callback方式作为异步方法。

说明： AsyncCallback中的数据可以是字符串(API 6)或ArrayBuffer(API 8)。可以指定传入on中的callback取消一个订阅，也可以不指定callback清空所有订阅。

系统能力 ：SystemCapability.Communication.NetStack

参数：

参数名	类型	必填	说明
type	string	是	'message'：WebSocket的接收到服务器消息事件。
callback	AsyncCallback	否	回调函数。

示例：

let ws = webSocket.createWebSocket();
ws.off('message');

on('close')

on(type: 'close', callback: AsyncCallback<{ code: number, reason: string }>): void

订阅WebSocket的关闭事件，使用callback方式作为异步方法。

系统能力 ：SystemCapability.Communication.NetStack

参数：

参数名	类型	必填	说明
type	string	是	'close'：WebSocket的关闭事件。
callback	AsyncCallback<{ code: number, reason: string }>	是	回调函数。

示例：

let ws = webSocket.createWebSocket();
ws.on('close', (err, value) = > {
	console.log("on close, code is " + value.code + ", reason is " + value.reason);
});

off('close')

off(type: 'close', callback?: AsyncCallback<{ code: number, reason: string }>): void

取消订阅WebSocket的关闭事件，使用callback方式作为异步方法。

说明： 可以指定传入on中的callback取消一个订阅，也可以不指定callback清空所有订阅。

系统能力 ：SystemCapability.Communication.NetStack

参数：

参数名	类型	必填	说明
type	string	是	'close'：WebSocket的关闭事件。
callback	AsyncCallback<{ code: number, reason: string }>	否	回调函数。

示例：

let ws = webSocket.createWebSocket();
ws.off('close');

on('error')

on(type: 'error', callback: ErrorCallback): void

订阅WebSocket的Error事件，使用callback方式作为异步方法。

系统能力 ：SystemCapability.Communication.NetStack

参数：

参数名	类型	必填	说明
type	string	是	'error'：WebSocket的Error事件。
callback	ErrorCallback	是	回调函数。

示例：

let ws = webSocket.createWebSocket();
ws.on('error', (err) = > {
	console.log("on error, error:" + JSON.stringify(err))
});

off('error')

off(type: 'error', callback?: ErrorCallback): void

取消订阅WebSocket的Error事件，使用callback方式作为异步方法。

说明： 可以指定传入on中的callback取消一个订阅，也可以不指定callback清空所有订阅。

系统能力 ：SystemCapability.Communication.NetStack

参数：

参数名	类型	必填	说明
type	string	是	'error'：WebSocket的Error事件。
callback	ErrorCallback	否	回调函数。

示例：

let ws = webSocket.createWebSocket();
ws.off('error');

WebSocketRequestOptions

建立WebSocket连接时，可选参数的类型和说明。

系统能力 ：以下各项对应的系统能力均为SystemCapability.Communication.NetStack。

参数名	类型	必填	说明
header	Object	否	建立WebSocket连接可选参数，代表建立连接时携带的HTTP头信息。参数内容自定义，也可以不指定。

WebSocketCloseOptions

关闭WebSocket连接时，可选参数的类型和说明。

系统能力 ：以下各项对应的系统能力均为SystemCapability.Communication.NetStack。

参数名	类型	必填	说明
code	number	否	错误码，关闭WebSocket连接时的可选参数，可根据实际情况来填。默认值为1000。
reason	string	否	原因值，关闭WebSocket连接时的可选参数，可根据实际情况来填。默认值为空字符串（""）。

close错误码说明

发送给服务端的错误码可以自行定义，下面的列表仅供参考。

系统能力 ：以下各项对应的系统能力均为SystemCapability.Communication.NetStack。

值	说明
1000	正常关闭
1001	服务器主动关闭
1002	协议错误
1003	无法处理的数据类型
1004~1015	保留值

审核编辑黄宇

声明：本文内容及配图由入驻作者撰写或者入驻合作网站授权转载。文章观点仅代表作者本人，不代表电子发烧友网立场。文章及其配图仅供工程师学习之用，如有内容侵权或者其他违规问题，请联系本站处理。举报投诉

接口

接口

+关注

关注
33

文章
9444

浏览量
156143
网络管理

网络管理

+关注

关注
0

文章
127

浏览量
29150
WebSocket

WebSocket

+关注

关注
0

文章
33

浏览量
4365
鸿蒙

鸿蒙

+关注

关注
60

文章
2858

浏览量
45355

搜索历史

鸿蒙开发网络管理：ohos.net.webSocket WebSocket连接

WebSocket连接

导入模块

完整示例

webSocket.createWebSocket

WebSocket

connect

connect

connect

send

send

close

close

close

on('open')

off('open')

on('message')

off('message')

on('close')

off('close')

on('error')

off('error')

WebSocketRequestOptions

WebSocketCloseOptions

close错误码说明

评论