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

返回值：

示例：

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

參數：

示例：

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

參數：

示例：

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

參數：

返回值：

示例：

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

參數：

示例：

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

參數：

返回值：

示例：

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

參數：

示例：

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

參數：

示例：

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

參數：

返回值：

示例：

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

參數：

示例：

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

參數：

示例：

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

參數：

示例：

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

參數：

示例：

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

on('close')

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

訂閱WebSocket的關閉事件，使用callback方式作為異步方法。

系統能力 ：SystemCapability.Communication.NetStack

參數：

示例：

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

參數：

示例：

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

on('error')

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

訂閱WebSocket的Error事件，使用callback方式作為異步方法。

系統能力 ：SystemCapability.Communication.NetStack

參數：

示例：

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

參數：

示例：

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

WebSocketRequestOptions

建立WebSocket連接時，可選參數的類型和說明。

系統能力 ：以下各項對應的系統能力均為SystemCapability.Communication.NetStack。

WebSocketCloseOptions

關閉WebSocket連接時，可選參數的類型和說明。

系統能力 ：以下各項對應的系統能力均為SystemCapability.Communication.NetStack。

close錯誤碼說明

發送給服務端的錯誤碼可以自行定義，下面的列表僅供參考。

系統能力 ：以下各項對應的系統能力均為SystemCapability.Communication.NetStack。

審核編輯 黃宇