文档中心

导入模块

收起
自动换行
深色代码主题
复制
import { webSocket } from '@kit.NetworkKit';

webSocket.createWebSocket

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

createWebSocket(): WebSocket

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

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力：SystemCapability.Communication.NetStack

返回值：

展开

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

示例：

收起
自动换行
深色代码主题
复制
let ws: webSocket.WebSocket = webSocket.createWebSocket();

WebSocket

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

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

connect

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

connect(url: string, callback: AsyncCallback<boolean>): void

根据URL地址，建立一个WebSocket连接，使用callback异步回调。

说明

callback中返回的boolean值仅表示连接请求创建是否成功。如需感知WebSocket是否连接成功，需要在调用该接口前调用on('open')订阅open事件。

需要权限：ohos.permission.INTERNET

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力：SystemCapability.Communication.NetStack

注意

URL地址长度不能超过1024个字符，否则会连接失败。从API version 15开始，URL地址长度限制由1024修改为2048。从API version 26开始，URL地址长度限制由2048修改为8196。

参数：

展开

参数名	类型	必填	说明
url	string	是	建立WebSocket连接的URL地址。
callback	AsyncCallback<boolean>	是	回调函数。true:连接请求创建成功；false:连接请求创建失败。

错误码：

以下错误码的详细介绍参见webSocket错误码和通用错误码。

展开

错误码ID	错误信息
401	Parameter error.
201	Permission denied.
2302001	Websocket url error. 适用版本：12+
2302002	Websocket certificate file does not exist. 适用版本：12+
2302003	Websocket connection already exists. 适用版本：12+
2302998	It is not allowed to access this domain. 适用版本：12+
2302999	Websocket other unknown error. 适用版本：10+

示例：

收起
自动换行
深色代码主题
复制
import { webSocket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let ws = webSocket.createWebSocket();
let url = "ws://";
ws.connect(url, (err: BusinessError, value: boolean) => {
  if (!err) {
    console.info("connect success")
  } else {
    console.error(`connect fail. Code: ${err.code}, message: ${err.message}`)
  }
});

connect

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

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

根据URL地址，建立一个WebSocket连接，使用callback异步回调。

说明

callback中返回的boolean值仅表示连接请求创建是否成功。如需感知WebSocket是否连接成功，需要在调用该接口前调用on('open')订阅open事件。

需要权限：ohos.permission.INTERNET

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力：SystemCapability.Communication.NetStack

注意

URL地址长度不能超过1024个字符，否则会连接失败。从API version 15开始，URL地址长度限制由1024修改为2048。从API version 26开始，URL地址长度限制由2048修改为8196。

参数：

展开

参数名	类型	必填	说明
url	string	是	建立WebSocket连接的URL地址。
options	WebSocketRequestOptions	是	参考WebSocketRequestOptions。
callback	AsyncCallback<boolean>	是	回调函数。true:连接请求创建成功；false:连接请求创建失败。

错误码：

以下错误码的详细介绍参见webSocket错误码和通用错误码。

展开

错误码ID	错误信息
401	Parameter error.
201	Permission denied.
2302001	Websocket url error. 适用版本：12+
2302002	Websocket certificate file does not exist. 适用版本：12+
2302003	Websocket connection already exists. 适用版本：12+
2302998	It is not allowed to access this domain. 适用版本：12+
2302999	Websocket other unknown error. 适用版本：10+

示例：

收起
自动换行
深色代码主题
复制
import { webSocket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

// 示例1：
let ws = webSocket.createWebSocket();
let options: webSocket.WebSocketRequestOptions | undefined;
if (options !=undefined) {
  options.header = {
     name1: "value1",
     name2: "value2",
     name3: "value3"
  };
  options.caPath = "";
}
let url = "ws://"
ws.connect(url, options, (err: BusinessError, value: Object) => {
  if (!err) {
    console.info("connect success")
  } else {
    console.error(`connect fail. Code: ${err.code}, message: ${err.message}`)
  }
});

// 示例2：
let url = "ws://"
let ws = webSocket.createWebSocket();
let options: webSocket.WebSocketRequestOptions = {
  minSupportTlsProtocol: webSocket.TlsProtocol.TLS_V_1_1
};
ws.connect(url, options, (err: BusinessError, value: Object) => {
  if (!err) {
    console.info("connect success")
  } else {
    console.error(`connect fail. Code: ${err.code}, message: ${err.message}`)
  }
});

connect

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

connect(url: string, options?: WebSocketRequestOptions): Promise<boolean>

根据URL地址和header，建立一个WebSocket连接。使用Promise异步回调。

说明

callback中返回的boolean值仅表示连接请求创建是否成功。如需感知WebSocket是否连接成功，需要在调用该接口前调用on('open')订阅open事件。

需要权限：ohos.permission.INTERNET

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力：SystemCapability.Communication.NetStack

注意

URL地址长度不能超过1024个字符，否则会连接失败。从API version 15开始，URL地址长度限制由1024修改为2048。从API version 26开始，URL地址长度限制由2048修改为8196。

参数：

展开

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

返回值：

展开

类型	说明
Promise<boolean>	回调函数。true:连接请求创建成功；false:连接请求创建失败。

错误码：

以下错误码的详细介绍参见webSocket错误码和通用错误码。

展开

错误码ID	错误信息
401	Parameter error.
201	Permission denied.
2302001	Websocket url error. 适用版本：12+
2302002	Websocket certificate file does not exist. 适用版本：12+
2302003	Websocket connection already exists. 适用版本：12+
2302998	It is not allowed to access this domain. 适用版本：12+
2302999	Websocket other unknown error. 适用版本：10+

示例：

收起
自动换行
深色代码主题
复制
import { webSocket } from '@kit.NetworkKit';

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

send

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

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

通过WebSocket连接发送数据，使用callback异步回调。

需要权限：ohos.permission.INTERNET

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力：SystemCapability.Communication.NetStack

参数：

展开

参数名	类型	必填	说明
data	string \| ArrayBuffer	是	发送的数据。 API 6及更早版本仅支持string类型。API 8起同时支持string和ArrayBuffer类型。最大支持发送5242864字节数据(即5 * 1024 * 1024 - 16)，超过该大小会返回401错误码。
callback	AsyncCallback<boolean>	是	回调函数。true:发送请求创建成功；false:发送请求创建失败。

参数名

类型

必填

说明

data

string | ArrayBuffer

是

发送的数据。

API 6及更早版本仅支持string类型。API 8起同时支持string和ArrayBuffer类型。最大支持发送5242864字节数据(即5 * 1024 * 1024 - 16)，超过该大小会返回401错误码。

callback

AsyncCallback<boolean>

是

回调函数。true:发送请求创建成功；false:发送请求创建失败。

错误码：

以下错误码的详细介绍参见通用错误码。

展开

错误码ID	错误信息
401	Parameter error.
201	Permission denied.

示例：

收起
自动换行
深色代码主题
复制
import { webSocket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let ws = webSocket.createWebSocket();
let url = "ws://"
class OutValue {
  status: number = 0
  message: string = ""
}
ws.connect(url, (err: BusinessError, value: boolean) => {
    if (!err) {
      console.info("connect success")
    } else {
      console.error(`connect fail. Code: ${err.code}, message: ${err.message}`)
    }
});
ws.on('open', (err: BusinessError, value: Object) => {
  console.info("on open, status:" + (value as OutValue).status + ", message:" + (value as OutValue).message)
    ws.send("Hello, server!", (err: BusinessError, value: boolean) => {
    if (!err) {
      console.info("send success")
    } else {
      console.error(`send fail. Code: ${err.code}, message: ${err.message}`)
    }
  });
});

说明

send接口必须在监听到open事件后才可以调用。

send

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

send(data: string | ArrayBuffer): Promise<boolean>

通过WebSocket连接发送数据。使用Promise异步回调。

需要权限：ohos.permission.INTERNET

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力：SystemCapability.Communication.NetStack

参数：

展开

参数名	类型	必填	说明
data	string \| ArrayBuffer	是	发送的数据。 API 6及更早版本仅支持string类型。API 8起同时支持string和ArrayBuffer类型。最大支持发送5242864字节数据(即5 * 1024 * 1024 - 16)，超过该大小会返回401错误码。

参数名

类型

必填

说明

data

string | ArrayBuffer

是

发送的数据。

API 6及更早版本仅支持string类型。API 8起同时支持string和ArrayBuffer类型。最大支持发送5242864字节数据(即5 * 1024 * 1024 - 16)，超过该大小会返回401错误码。

返回值：

展开

类型	说明
Promise<boolean>	以Promise形式返回发送数据的结果。true:发送请求创建成功；false:发送请求创建失败。

错误码：

以下错误码的详细介绍参见通用错误码。

展开

错误码ID	错误信息
401	Parameter error.
201	Permission denied.

示例：

收起
自动换行
深色代码主题
复制
import { webSocket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let ws = webSocket.createWebSocket();
let url = "ws://"
class OutValue {
  status: number = 0
  message: string = ""
}
ws.connect(url, (err: BusinessError, value: boolean) => {
    if (!err) {
      console.info("connect success")
    } else {
      console.error("connect fail. Code: ${err.code}, message: ${err.message}")
    }
});

ws.on('open', (err: BusinessError, value: Object) => {
  console.info("on open, status:" + (value as OutValue).status + ", message:" + (value as OutValue).message)
  let promise = ws.send("Hello, server!");
  promise.then((value: boolean) => {
    console.info("send success")
  }).catch((err:string) => {
    console.error("send fail, error:" + JSON.stringify(err))
  });
});

说明

send接口必须在监听到open事件后才可以调用。

close

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

close(callback: AsyncCallback<boolean>): void

关闭WebSocket连接，使用callback异步回调。

需要权限：ohos.permission.INTERNET

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力：SystemCapability.Communication.NetStack

参数：

展开

参数名	类型	必填	说明
callback	AsyncCallback<boolean>	是	回调函数。true:关闭请求创建成功；false:关闭请求创建失败。

错误码：

以下错误码的详细介绍参见通用错误码。

展开

错误码ID	错误信息
401	Parameter error.
201	Permission denied.

示例：

收起
自动换行
深色代码主题
复制
import { webSocket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let ws = webSocket.createWebSocket();
ws.close((err: BusinessError) => {
  if (!err) {
    console.info("close success")
  } else {
    console.error(`close fail. Code: ${err.code}, message: ${err.message}`)
  }
});

close

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

close(options: WebSocketCloseOptions, callback: AsyncCallback<boolean>): void

根据参数options，关闭WebSocket连接，使用callback异步回调。

需要权限：ohos.permission.INTERNET

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力：SystemCapability.Communication.NetStack

参数：

展开

参数名	类型	必填	说明
options	WebSocketCloseOptions	是	参考WebSocketCloseOptions。
callback	AsyncCallback<boolean>	是	回调函数。true:关闭请求创建成功；false:关闭请求创建失败。

错误码：

以下错误码的详细介绍参见通用错误码。

展开

错误码ID	错误信息
401	Parameter error.
201	Permission denied.

示例：

收起
自动换行
深色代码主题
复制
import { webSocket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let ws = webSocket.createWebSocket();

let options: webSocket.WebSocketCloseOptions | undefined;
if (options != undefined) {
    options.code = 1000
    options.reason = "your reason"
}
ws.close(options, (err: BusinessError) => {
    if (!err) {
        console.info("close success")
    } else {
        console.error(`close fail. Code: ${err.code}, message: ${err.message}`)
    }
});

close

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

close(options?: WebSocketCloseOptions): Promise<boolean>

根据可选参数code和reason，关闭WebSocket连接。使用Promise异步回调。

需要权限：ohos.permission.INTERNET

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力：SystemCapability.Communication.NetStack

参数：

展开

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

返回值：

展开

类型	说明
Promise<boolean>	以Promise形式返回关闭连接的结果。true:关闭请求创建成功；false:关闭请求创建失败。

错误码：

以下错误码的详细介绍参见通用错误码。

展开

错误码ID	错误信息
401	Parameter error.
201	Permission denied.

示例：

收起
自动换行
深色代码主题
复制
import { webSocket } from '@kit.NetworkKit';

let ws = webSocket.createWebSocket();
let options: webSocket.WebSocketCloseOptions | undefined;
if (options != undefined) {
    options.code = 1000
    options.reason = "your reason"
}
let promise = ws.close();
promise.then((value: boolean) => {
    console.info("close success")
}).catch((err:string) => {
    console.error("close fail, error:" + JSON.stringify(err))
});

on('open')

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

on(type: 'open', callback: AsyncCallback<Object>): void

订阅WebSocket的打开事件，使用callback异步回调。该事件用于指示WebSocket是否连接成功。该接口需要在调用connect发起连接请求前调用。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力：SystemCapability.Communication.NetStack

参数：

展开

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

示例：

收起
自动换行
深色代码主题
复制
import { webSocket } from '@kit.NetworkKit';
import { BusinessError, Callback } from '@kit.BasicServicesKit';

let ws= webSocket.createWebSocket();
class OutValue {
  status: number = 0
  message: string = ""
}
ws.on('open', (err: BusinessError, value: Object) => {
  console.info("on open, status:" + (value as OutValue).status + ", message:" + (value as OutValue).message)
});

off('open')

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

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

取消订阅WebSocket的打开事件，使用callback异步回调。

说明

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

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力：SystemCapability.Communication.NetStack

参数：

展开

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

示例：

收起
自动换行
深色代码主题
复制
import { webSocket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let ws = webSocket.createWebSocket();
class OutValue {
  status: number = 0
  message: string = ""
}
let callback1 = (err: BusinessError, value: Object) => {
 console.info("on open, status:" + ((value as OutValue).status + ", message:" + (value as OutValue).message))
}
ws.on('open', callback1);
// 可以指定传入on中的callback取消一个订阅，也可以不指定callback清空所有订阅。
ws.off('open', callback1);

on('openInfo')

Phone26.0.0+PC/2in126.0.0+Tablet26.0.0+TV26.0.0+Wearable26.0.0+

on(type: 'openInfo', callback: AsyncCallback<WebSocketOpenInfo>): void

订阅WebSocket的打开信息事件，使用callback异步回调。该事件用于获取WebSocket连接成功后的详细信息。该接口需要在调用connect发起连接请求前调用。

起始版本： 26.0.0

系统能力： SystemCapability.Communication.NetStack

模型约束： 此接口仅可在Stage模型下使用。

参数：

展开

参数名	类型	必填	说明
type	string	是	订阅的事件类型。'openInfo'：WebSocket的打开信息事件。
callback	AsyncCallback<WebSocketOpenInfo>	是	回调函数。返回WebSocket连接的详细信息。

示例：

收起
自动换行
深色代码主题
复制
import { webSocket } from '@kit.NetworkKit';
import { BusinessError, Callback } from '@kit.BasicServicesKit';

let ws = webSocket.createWebSocket();
ws.on('openInfo', (err: BusinessError, value: webSocket.WebSocketOpenInfo) => {
  if (value?.protocol != undefined) {
    console.info(`on openInfo exist protocol: status: ${value.status}, message: ${value.message}, protocol: ${value.protocol}`);
  } else {
    console.info(`on openInfo , status: ${value.status}, message: ${value.message}, protocol: ${value.protocol}`);
  }
});

off('openInfo')

Phone26.0.0+PC/2in126.0.0+Tablet26.0.0+TV26.0.0+Wearable26.0.0+

off(type: 'openInfo', callback?: AsyncCallback<WebSocketOpenInfo>): void

取消订阅WebSocket的打开信息事件，使用callback异步回调。

说明

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

起始版本： 26.0.0

系统能力： SystemCapability.Communication.NetStack

模型约束： 此接口仅可在Stage模型下使用。

参数：

展开

参数名	类型	必填	说明
type	string	是	取消订阅的事件类型。'openInfo'：WebSocket的打开信息事件。
callback	AsyncCallback<WebSocketOpenInfo>	否	回调函数。

示例：

收起
自动换行
深色代码主题
复制
import { webSocket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let ws = webSocket.createWebSocket();
let callback1 = (err: BusinessError, value: webSocket.WebSocketOpenInfo) => {
  if (value?.protocol != undefined) {
    console.info(`on openInfo exist protocol: status: ${value.status}, message: ${value.message}, protocol: ${value.protocol}`);
  } else {
    console.info(`on openInfo , status: ${value.status}, message: ${value.message}, protocol: ${value.protocol}`);
  }
}
ws.on('openInfo', callback1);
// 可以指定传入on中的callback取消一个订阅，也可以不指定callback清空所有订阅。
ws.off('openInfo', callback1);

on('message')

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

on(type: 'message', callback: AsyncCallback<string | ArrayBuffer>): void

订阅WebSocket的接收服务器消息事件，使用callback异步回调。

说明

AsyncCallback中的数据可以是字符串（API version 6开始支持）或ArrayBuffer（API version 8开始支持）。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力：SystemCapability.Communication.NetStack

参数：

展开

参数名	类型	必填	说明
type	string	是	订阅的事件类型。'message'：WebSocket的接收服务器消息事件。
callback	AsyncCallback<string \| ArrayBuffer ⁸⁺>	是	回调函数。

示例：

收起
自动换行
深色代码主题
复制
import { webSocket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let ws = webSocket.createWebSocket();
ws.on('message', (err: BusinessError<void>, value: string | ArrayBuffer) => {
  console.info("on message, message:" + value)
});

off('message')

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

off(type: 'message', callback?: AsyncCallback<string | ArrayBuffer>): void

取消订阅WebSocket的接收服务器消息事件，使用callback异步回调。

说明

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

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

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力：SystemCapability.Communication.NetStack

参数：

展开

参数名	类型	必填	说明
type	string	是	取消订阅的事件类型。'message'：WebSocket的接收到服务器消息事件。
callback	AsyncCallback<string \|ArrayBuffer ⁸⁺>	否	回调函数。

示例：

收起
自动换行
深色代码主题
复制
import { webSocket } from '@kit.NetworkKit';

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

on('close')

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

on(type: 'close', callback: AsyncCallback<CloseResult>): void

订阅WebSocket的关闭事件，使用callback异步回调。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力：SystemCapability.Communication.NetStack

参数：

展开

参数名	类型	必填	说明
type	string	是	订阅的事件类型。'close'：WebSocket的关闭事件。
callback	AsyncCallback<CloseResult>	是	回调函数。 close：close错误码，reason：错误码说明

参数名

类型

必填

说明

type

string

是

订阅的事件类型。'close'：WebSocket的关闭事件。

callback

AsyncCallback<CloseResult>

是

回调函数。

close：close错误码，reason：错误码说明

示例：

收起
自动换行
深色代码主题
复制
import { webSocket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

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

off('close')

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

off(type: 'close', callback?: AsyncCallback<CloseResult>): void

取消订阅WebSocket的关闭事件，使用callback异步回调。

说明

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

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力：SystemCapability.Communication.NetStack

参数：

展开

参数名	类型	必填	说明
type	string	是	取消订阅的事件类型。'close'：WebSocket的关闭事件。
callback	AsyncCallback<CloseResult>	否	回调函数。 close：close错误码，reason：错误码说明

参数名

类型

必填

说明

type

string

是

取消订阅的事件类型。'close'：WebSocket的关闭事件。

callback

AsyncCallback<CloseResult>

否

回调函数。

close：close错误码，reason：错误码说明

示例：

收起
自动换行
深色代码主题
复制
import { webSocket } from '@kit.NetworkKit';

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

on('error')

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

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

订阅WebSocket的Error事件，使用callback异步回调。

关于error事件回调的错误码说明：WebSocket的本质是HTTP协议升级，若服务器同意升级，服务器会返回101。状态码表示协议从HTTP切换为WebSocket协议（触发open回调），而如果服务器拒绝了升级或出现其他异常，则返回200，表示服务器只是将请求当作普通的HTTP请求来处理。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力：SystemCapability.Communication.NetStack

参数：

展开

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

示例：

收起
自动换行
深色代码主题
复制
import { webSocket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let ws = webSocket.createWebSocket();
ws.on('error', (err: BusinessError) => {
  console.error(`on error. Code: ${err.code}, message: ${err.message}`)
});

off('error')

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

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

取消订阅WebSocket的Error事件，使用callback异步回调。

说明

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

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力：SystemCapability.Communication.NetStack

参数：

展开

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

示例：

收起
自动换行
深色代码主题
复制
import { webSocket } from '@kit.NetworkKit';

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

on('dataEnd')¹¹⁺

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

on(type: 'dataEnd', callback: Callback<void>): void

订阅WebSocket的数据接收结束事件，使用callback异步回调。

系统能力：SystemCapability.Communication.NetStack

参数：

展开

参数名	类型	必填	说明
type	string	是	订阅的事件类型。'dataEnd'：WebSocket的数据接收结束事件。
callback	Callback<void>	是	回调函数。

示例：

收起
自动换行
深色代码主题
复制
import { webSocket } from '@kit.NetworkKit';

let ws = webSocket.createWebSocket();
ws.on('dataEnd', () => {
  console.info("on dataEnd")
});

off('dataEnd')¹¹⁺

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

off(type: 'dataEnd', callback?: Callback<void>): void

取消订阅WebSocket的数据接收结束事件，使用callback异步回调。

说明

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

系统能力：SystemCapability.Communication.NetStack

参数：

展开

参数名	类型	必填	说明
type	string	是	取消订阅的事件类型。'dataEnd'：WebSocket的数据接收结束事件。
callback	Callback<void>	否	回调函数。

示例：

收起
自动换行
深色代码主题
复制
import { webSocket } from '@kit.NetworkKit';

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

on('headerReceive')¹²⁺

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

on(type: 'headerReceive', callback: Callback<ResponseHeaders>): void

订阅HTTP Response Header事件，使用callback异步回调。

系统能力：SystemCapability.Communication.NetStack

参数：

展开

参数名	类型	必填	说明
type	string	是	订阅的事件类型。'headerReceive'：WebSocket的headerReceive事件。
callback	Callback<ResponseHeaders>	是	回调函数，返回订阅事件。

示例：

收起
自动换行
深色代码主题
复制
import { webSocket } from '@kit.NetworkKit';

let ws = webSocket.createWebSocket();
ws.on('headerReceive', (data) => {
  console.info("on headerReceive " + JSON.stringify(data))
});

off('headerReceive')¹²⁺

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

off(type: 'headerReceive', callback?: Callback<ResponseHeaders>): void

取消订阅HTTP Response Header事件，使用callback异步回调。

说明

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

系统能力：SystemCapability.Communication.NetStack

参数：

展开

参数名	类型	必填	说明
type	string	是	取消订阅的事件类型。'headerReceive'：WebSocket的headerReceive事件。
callback	Callback<ResponseHeaders>	否	回调函数，返回订阅事件。

示例：

收起
自动换行
深色代码主题
复制
import { webSocket } from '@kit.NetworkKit';

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

webSocket.createWebSocketServer¹⁹⁺

Phone19+PC/2in119+Tablet19+TV19+Wearable19+

createWebSocketServer(): WebSocketServer

创建一个WebSocketServer对象，包括启动服务、发送数据、关闭连接、列出客户端信息、停止服务，订阅/取消订阅webSocket连接的连接事件、接收到客户端消息事件、关闭事件和错误事件。

说明

从API version 23开始支持全设备使用，之前仅支持TV设备使用。

系统能力： SystemCapability.Communication.NetStack

返回值：

展开

类型	说明
WebSocketServer	返回一个WebSocketServer对象，里面包括start、listAllConnections、send、close、stop、on和off方法。

示例：

收起
自动换行
深色代码主题
复制
let ws: webSocket.WebSocketServer = webSocket.createWebSocketServer();

WebSocketServer¹⁹⁺

Phone19+PC/2in119+Tablet19+TV19+Wearable19+

在调用WebSocketServer方法前，需要先通过webSocket.createWebSocketServer创建一个WebSocketServer。

start¹⁹⁺

Phone19+PC/2in119+Tablet19+TV19+Wearable19+

start(config: WebSocketServerConfig): Promise<boolean>

配置config参数，启动服务端service。使用Promise异步回调。

说明

在多次调用该接口时，应避免监听同一端口。

需要权限： ohos.permission.INTERNET

系统能力： SystemCapability.Communication.NetStack

参数：

展开

参数名	类型	必填	说明
config	WebSocketServerConfig	是	启动websocketServer服务器。

返回值：

展开

类型	说明
Promise<boolean>	promise对象。返回true表示服务器启动成功；返回false表示服务启动失败。

错误码：

以下错误码的详细介绍请参见通用错误码和webSocket错误码。

展开

错误码ID	错误信息
201	Permission denied.
2302002	Websocket certificate file does not exist.
2302004	Can't listen on the given NIC.
2302005	Can't listen on the given Port.
2302007	Websocket port already occupied. 适用版本：24+
2302999	Websocket other unknown error.

示例：

收起
自动换行
深色代码主题
复制
import { webSocket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let localServer: webSocket.WebSocketServer;
let config: webSocket.WebSocketServerConfig = {
  serverPort: 8080, // 监听端口
  maxConcurrentClientsNumber: 10,
  maxConnectionsForOneClient: 10,
}

localServer = webSocket.createWebSocketServer();
localServer.start(config).then((success: boolean) => {
  if (success) {
    console.info('webSocket server start success');
  } else {
    console.error('websocket server start failed');
  }
}).catch((error: BusinessError) => {
  console.error(`Failed to start. Code: ${error.code}, message: ${error.message}`);
});

send¹⁹⁺

Phone19+PC/2in119+Tablet19+TV19+Wearable19+

send(data: string | ArrayBuffer, connection: WebSocketConnection): Promise<boolean>

通过WebSocket连接发送数据。使用Promise异步回调。

说明

send接口必须在监听到connect事件后才可以调用。

需要权限： ohos.permission.INTERNET

系统能力： SystemCapability.Communication.NetStack

参数：

展开

参数名	类型	必填	说明
data	string \| ArrayBuffer	是	服务端发送消息的数据，同时支持string（字符串）和ArrayBuffer（二进制）类型。最大支持发送5242864字节数据(即5 * 1024 * 1024 - 16)，超过该大小会返回401错误码。
connection	WebSocketConnection	是	发送的客户端信息。

返回值：

展开

类型	说明
Promise<boolean>	promise对象。返回true表示发送请求创建成功；返回false表示发送请求创建失败。

错误码：

以下错误码的详细介绍请参见通用错误码和webSocket错误码。

展开

错误码ID	错误信息
201	Permission denied.
2302006	websocket connection does not exist.

示例：

收起
自动换行
深色代码主题
复制
import { webSocket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let localServer: webSocket.WebSocketServer;
let config: webSocket.WebSocketServerConfig = {
  serverPort: 8080, // 监听端口
  maxConcurrentClientsNumber: 10,
  maxConnectionsForOneClient: 10,
}

localServer = webSocket.createWebSocketServer();
localServer.start(config).then((success: boolean) => {
  if (success) {
    console.info('webSocket server start success');
  } else {
    console.error('websocket server start failed');
  }
}).catch((error: BusinessError) => {
  console.error(`Failed to start. Code: ${error.code}, message: ${error.message}`);
});

localServer.on('connect', async (connection: webSocket.WebSocketConnection) => {
  console.info(`New client connected! Client ip: ${connection.clientIP}, Client port: ${connection.clientPort}`);
  // 当收到on('connect')事件时，可以通过send()方法与客户端进行通信
  localServer.send("Hello, I'm server!", connection).then((success: boolean) => {
    if (success) {
      console.info('message send successfully');
    } else {
      console.error('message send failed');
    }
  }).catch((error: BusinessError) => {
    console.error(`message send failed, Code: ${error.code}, message: ${error.message}`);
  });
});

listAllConnections¹⁹⁺

Phone19+PC/2in119+Tablet19+TV19+Wearable19+

listAllConnections(): WebSocketConnection[]

获取与服务端连接的所有客户端信息。

需要权限： ohos.permission.INTERNET

系统能力：SystemCapability.Communication.NetStack

说明

该接口为异步调用，返回结果需通过await关键字等待异步操作完成，以确保正确获取到所有客户端连接信息。

返回值：

展开

类型	说明
WebSocketConnection[]	以字符串数组形式返回所有客户端的信息。

错误码：

以下错误码的详细介绍请参见通用错误码。

展开

错误码ID	错误信息
201	Permission denied.

示例：

收起
自动换行
深色代码主题
复制
import { webSocket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let connections: webSocket.WebSocketConnection[] = [];
let localServer: webSocket.WebSocketServer;
let config: webSocket.WebSocketServerConfig = {
  serverPort: 8080, // 监听端口
  maxConcurrentClientsNumber: 10,
  maxConnectionsForOneClient: 10,
}

localServer = webSocket.createWebSocketServer();
localServer.start(config).then((success: boolean) => {
  if (success) {
    console.info('webSocket server start success');
  } else {
    console.error('websocket server start failed');
  }
}).catch((error: BusinessError) => {
  console.error(`Failed to start. Code: ${error.code}, message: ${error.message}`);
});

localServer.on('connect', async (connection: webSocket.WebSocketConnection) => {
  console.info(`New client connected! Client ip: ${connection.clientIP}, Client port: ${connection.clientPort}`);
  try {
    connections = await localServer.listAllConnections();
    if (connections.length === 0) {
      console.info('client list is empty');
    } else {
      console.info(`client list cnt: ${connections.length}, client connections list is: ${connections}`);
    }
  } catch (error) {
    console.error(`Failed to listAllConnections. Code: ${error.code}, message: ${error.message}`);
  }
});

close¹⁹⁺

Phone19+PC/2in119+Tablet19+TV19+Wearable19+

close(connection: WebSocketConnection, options?: webSocket.WebSocketCloseOptions): Promise<boolean>

关闭指定websocket连接。使用Promise异步回调。

需要权限：ohos.permission.INTERNET

系统能力：SystemCapability.Communication.NetStack

参数：

展开

参数名	类型	必填	说明
connection	WebSocketConnection	是	客户端信息，包括客户端的ip地址和端口号port。
options	webSocket.WebSocketCloseOptions	否	关闭WebSocket连接时，可选参数的类型和说明。 - 错误码默认：200。原因值默认：Websocket connect failed。

参数名

类型

必填

说明

connection

WebSocketConnection

是

客户端信息，包括客户端的ip地址和端口号port。

options

webSocket.WebSocketCloseOptions

否

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

- 错误码默认：200。原因值默认：Websocket connect failed。

返回值：

展开

类型	说明
Promise<boolean>	promise对象。返回true表示关闭请求创建成功；返回false表示关闭请求创建失败。

错误码：

以下错误码的详细介绍请参见通用错误码和webSocket错误码。

展开

错误码ID	错误信息
201	Permission denied.
2302006	websocket connection does not exist.

示例：

收起
自动换行
深色代码主题
复制
import { webSocket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let localServer: webSocket.WebSocketServer;
let config: webSocket.WebSocketServerConfig = {
  serverPort: 8080, // 监听端口
  maxConcurrentClientsNumber: 10,
  maxConnectionsForOneClient: 10,
}

localServer = webSocket.createWebSocketServer();
localServer.start(config).then((success: boolean) => {
  if (success) {
    console.info('webSocket server start success');
  } else {
    console.error('websocket server start failed');
  }
}).catch((error: BusinessError) => {
  console.error(`Failed to start. Code: ${error.code}, message: ${error.message}`);
});

localServer.on('connect', (connection: webSocket.WebSocketConnection) => {
  console.info(`New client connected! Client ip: ${connection.clientIP}, Client port: ${connection.clientPort}`);
  localServer.close(connection).then((success: boolean) => {
    if (success) {
      console.info('close client successfully');
    } else {
      console.error('close client failed');
    }
  });
});

stop¹⁹⁺

Phone19+PC/2in119+Tablet19+TV19+Wearable19+

stop(): Promise<boolean>

停止服务端服务。使用Promise异步回调。

需要权限：ohos.permission.INTERNET

系统能力：SystemCapability.Communication.NetStack

返回值：

展开

类型	说明
Promise<boolean>	promise对象。返回true表示停止服务端service请求创建成功；返回false表示停止服务端service请求创建失败。

错误码：

以下错误码的详细介绍请参见通用错误码。

展开

错误码ID	错误信息
201	Permission denied.

示例：

收起
自动换行
深色代码主题
复制
import { webSocket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let localServer: webSocket.WebSocketServer;
let config: webSocket.WebSocketServerConfig = {
  serverPort: 8080, // 监听端口
  maxConcurrentClientsNumber: 10,
  maxConnectionsForOneClient: 10,
}

localServer = webSocket.createWebSocketServer();
localServer.start(config).then((success: boolean) => {
  if (success) {
    console.info('webSocket server start success');
  } else {
    console.error('websocket server start failed');
  }
}).catch((error: BusinessError) => {
  console.error(`Failed to start. Code: ${error.code}, message: ${error.message}`);
});

localServer.stop().then((success: boolean) => {
  if (success) {
    console.info('server stop service successfully');
  } else {
    console.error('server stop service failed');
  }
});

on('connect')¹⁹⁺

Phone19+PC/2in119+Tablet19+TV19+Wearable19+

on(type: 'connect', callback: Callback<WebSocketConnection>): void

订阅WebSocketServer的连接事件（客户端与服务端建链成功），使用callback异步回调。

系统能力：SystemCapability.Communication.NetStack

参数：

展开

参数名	类型	必填	说明
type	string	是	事件回调类型，支持的事件为'connect'，当onconnect()调用完成，客户端与服务端建链成功。
callback	Callback<WebSocketConnection>	是	回调函数。连接的客户端信息。

示例：

收起
自动换行
深色代码主题
复制
import { webSocket } from '@kit.NetworkKit';
import { BusinessError, Callback } from '@kit.BasicServicesKit';

let localServer = webSocket.createWebSocketServer();
localServer.on('connect', (connection: webSocket.WebSocketConnection) => {
  console.info(`New client connected! Client ip: ${connection.clientIP}, Client port: ${connection.clientPort}`);
});

off('connect')¹⁹⁺

Phone19+PC/2in119+Tablet19+TV19+Wearable19+

off(type: 'connect', callback?: Callback<WebSocketConnection>): void

取消订阅WebSocketServer的连接事件（客户端与服务端建链成功），使用callback异步回调。

说明

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

系统能力：SystemCapability.Communication.NetStack

参数：

展开

参数名	类型	必填	说明
type	string	是	事件回调类型，支持的事件为'connect'，当offconnect()调用完成，取消监听连接事件成功。
callback	Callback<WebSocketConnection>	否	回调函数。连接的客户端信息。

示例：

收起
自动换行
深色代码主题
复制
import { webSocket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let localServer = webSocket.createWebSocketServer();
localServer.off('connect');

on('messageReceive')¹⁹⁺

Phone19+PC/2in119+Tablet19+TV19+Wearable19+

on(type: 'messageReceive', callback: Callback<WebSocketMessage>): void

订阅WebSocketServer的接收客户端消息的事件，使用callback异步回调。

系统能力：SystemCapability.Communication.NetStack

参数：

展开

参数名

类型

必填

说明

type

string

是

事件回调类型，支持的事件为'messageReceive'，当onmessageReceive()调用完成，接收到客户端消息成功。

callback

Callback<WebSocketMessage>

是

回调函数。

clientconnection:客户端信息，data:客户端发送的数据消息。

示例：

收起
自动换行
深色代码主题
复制
import { webSocket } from '@kit.NetworkKit';
import { BusinessError, Callback } from '@kit.BasicServicesKit';

let localServer = webSocket.createWebSocketServer();
localServer.on('messageReceive', (message: webSocket.WebSocketMessage) => {
  console.info(`on message received, client: ${message.clientConnection}, data: ${message.data}`);
});

off('messageReceive')¹⁹⁺

Phone19+PC/2in119+Tablet19+TV19+Wearable19+

off(type: 'messageReceive', callback?: Callback<WebSocketMessage>): void

取消订阅WebSocketServer的接收到客户端消息事件，使用callback异步回调。

说明

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

系统能力：SystemCapability.Communication.NetStack

参数：

展开

参数名

类型

必填

说明

type

string

是

事件回调类型，支持的事件为'messageReceive'，当offmessageReceive()调用完成，取消订阅接收客户端消息成功。

callback

Callback<WebSocketMessage>

否

从指定客户端接收到的消息，包括客户端的信息和数据。

- clientconnection：客户端信息。

- data：客户端发送的消息。

示例：

收起
自动换行
深色代码主题
复制
import { webSocket } from '@kit.NetworkKit';
import { BusinessError, Callback } from '@kit.BasicServicesKit';

let localServer = webSocket.createWebSocketServer();
localServer.off('messageReceive');

on('close')¹⁹⁺

Phone19+PC/2in119+Tablet19+TV19+Wearable19+

on(type: 'close', callback: ClientConnectionCloseCallback): void

订阅WebSocketServer的关闭事件，使用callback异步回调。

系统能力：SystemCapability.Communication.NetStack

参数：

展开

参数名

类型

必填

说明

type

string

是

事件回调类型，支持的事件为'close'，当onclose()调用完成，连接关闭成功。

callback

ClientConnectionCloseCallback

是

回调函数。

close：close错误码；reason：错误码说明。

示例：

收起
自动换行
深色代码主题
复制
import { webSocket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let localServer = webSocket.createWebSocketServer();
localServer.on('close', (clientConnection: webSocket.WebSocketConnection, closeReason: webSocket.CloseResult) => {
  console.info(`client close, client: ${clientConnection}, closeReason: Code: ${closeReason.code}, reason: ${closeReason.reason}`);
});

off('close')¹⁹⁺

Phone19+PC/2in119+Tablet19+TV19+Wearable19+

off(type: 'close', callback?: ClientConnectionCloseCallback): void

取消订阅WebSocketServer的关闭事件，使用callback异步回调。

说明

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

系统能力：SystemCapability.Communication.NetStack

参数：

展开

参数名

类型

必填

说明

type

string

是

事件回调类型，支持的事件为'close'，当offclose()调用完成，取消订阅连接关闭事件成功。

callback

ClientConnectionCloseCallback

否

回调函数。

close：close错误码；reason：错误码说明。

示例：

收起
自动换行
深色代码主题
复制
import { webSocket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let localServer = webSocket.createWebSocketServer();
localServer.off('close');

on('error')¹⁹⁺

Phone19+PC/2in119+Tablet19+TV19+Wearable19+

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

订阅WebSocketServer的Error事件，使用callback异步回调。

系统能力：SystemCapability.Communication.NetStack

参数：

展开

参数名	类型	必填	说明
type	string	是	事件回调类型，支持的事件为'error'，当onerror()调用完成，error事件发生。
callback	ErrorCallback	是	回调函数。

示例：

收起
自动换行
深色代码主题
复制
import { webSocket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let wsServer: webSocket.WebSocketServer = webSocket.createWebSocketServer();
wsServer.on('error', (err: BusinessError) => {
  console.error(`error. Code: ${err.code}, message: ${err.message}`);
});

off('error')¹⁹⁺

Phone19+PC/2in119+Tablet19+TV19+Wearable19+

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

取消订阅WebSocketServer的Error事件，使用callback异步回调。

说明

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

系统能力：SystemCapability.Communication.NetStack

参数：

展开

参数名	类型	必填	说明
type	string	是	事件回调类型，支持的事件为'error'，当offerror()调用完成，取消订阅error事件成功。
callback	ErrorCallback	否	回调函数。默认值：200。

示例：

收起
自动换行
深色代码主题
复制
import { webSocket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let localServer = webSocket.createWebSocketServer();
localServer.off('error');

WebSocketRequestOptions

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

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

系统能力：SystemCapability.Communication.NetStack

展开

名称	类型	只读	可选	说明
header	Object	否	是	建立WebSocket连接可选参数，代表建立连接时携带的HTTP头信息。参数内容自定义，也可以不指定。元服务API：从API version 11开始，该接口支持在元服务中使用。
caPath¹¹⁺	string	否	是	如果设置了此参数，系统将使用用户指定路径的CA证书，(开发者需保证该路径下CA证书的可访问性)，否则将使用系统预设CA证书，系统预设CA证书位置：/etc/ssl/certs/cacert.pem。证书路径为沙箱映射路径（开发者可通过UIAbilityContext提供的能力获取应用沙箱路径）。目前仅支持格式为pem的文本证书。
clientCert¹¹⁺	ClientCert	否	是	支持传输客户端证书。
proxy¹²⁺	ProxyConfiguration	否	是	通信过程中的代理信息，默认使用系统网络代理。
protocol¹²⁺	string	否	是	自定义Sec-WebSocket-Protocol字段，默认为""。
skipServerCertVerification²⁰⁺	boolean	否	是	是否跳过服务器证书验证。true表示跳过服务器证书验证，false表示不跳过服务器证书验证。默认为false。
pingInterval²¹⁺	number	否	是	自定义心跳检测时间，默认为30s。每pingInterval周期会发起心跳检测，设置为0则表示关闭心跳检测。最大值：30000s，最小值：0s。
pongTimeout²¹⁺	number	否	是	自定义发起心跳检测后，超时断开时间，默认为30s。发起心跳检测后若pongTimeout时间未响应则断开连接。最大值：30000s，最小值：0s。pongTimeout须小于等于pingInterval。
minSupportTlsProtocol	TlsProtocol	否	是	自定义支持的最低TLS协议版本。例如：设置该参数为TLS_V_1_1，则客户端可支持TLS协议版本有TLS1.1、TLS1.2、TLS1.3。起始版本： 26.0.0 模型约束：此接口仅可在Stage模型下使用。
supportOriginPort	boolean	否	是	Origin是WebSocket握手请求中的HTTP请求头字段，用于标识请求来源，服务端可据此进行来源校验。该参数用于控制Origin字段是否携带自定义端口号。默认值为false。设置为true时： - 调用connect接口后，若其第一个参数url中指定的协议为ws，且显式指定的端口号不是80，则Origin字段中会携带对应的端口；其他情况不携带端口号。 - 调用connect接口后，若其第一个参数url中指定的协议为wss，且显式指定的端口号不是443，则Origin字段中会携带对应的端口号；其他情况不携带端口号。设置为false时，Origin字段不会携带端口号。起始版本： 26.0.0 模型约束：此接口仅可在Stage模型下使用。

ClientCert¹¹⁺

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

客户端证书类型。

系统能力：SystemCapability.Communication.NetStack

展开

名称	类型	只读	可选	说明
certPath	string	否	否	证书路径。
keyPath	string	否	否	证书密钥的路径。
keyPassword	string	否	是	证书密钥的密码。缺省为空字符串。

ProxyConfiguration¹²⁺

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

type ProxyConfiguration = 'system' | 'no-proxy' | HttpProxy

网络代理配置信息

系统能力：SystemCapability.Communication.NetStack

展开

类型	说明
'system'	使用系统默认网络代理。
'no-proxy'	不使用网络代理。
HttpProxy	使用指定的网络代理。

WebSocketCloseOptions

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

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

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力：SystemCapability.Communication.NetStack

展开

名称	类型	只读	可选	说明
code	number	否	是	错误码，关闭WebSocket连接时的可选参数，可根据实际情况来填。传入值必须为正整数，取值范围为[1000,1015]。如果未指定错误码或传入值不在上述范围内，code将会被设置为默认值1000。
reason	string	否	是	原因值，关闭WebSocket连接时的可选参数，可根据实际情况来填。如果未指定原因值，则原因值将会被设置为默认值"CLOSE_NORMAL"。

CloseResult¹⁰⁺

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

关闭WebSocket连接时，订阅close事件得到的关闭结果。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力：SystemCapability.Communication.NetStack

展开

名称	类型	只读	可选	说明
code	number	否	否	错误码，订阅close事件得到的关闭连接的错误码。
reason	string	否	否	原因值，订阅close事件得到的关闭连接的错误原因。

ResponseHeaders¹²⁺

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

type ResponseHeaders = { [k: string]: string | string[] | undefined; }

服务器发送的响应头。

系统能力：SystemCapability.Communication.NetStack

展开

名称	类型	必填	说明
[k:string]	string \| string[] \| undefined	否	键值对形式存储。其键的类型为字符，可取任意值，其值的类型为字符、字符数组或undefined。

close错误码说明

发送给服务端的错误码必须为正整数，取值范围为[1000,1015],可以自行定义，如果未指定错误码或传入值不在上述范围内，错误码将会被设置为默认值1000。下面的列表仅供参考。

系统能力：SystemCapability.Communication.NetStack

展开

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

HttpProxy¹²⁺

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

type HttpProxy = connection.HttpProxy

网络全局代理配置信息。

系统能力：SystemCapability.Communication.NetManager.Core

展开

类型	说明
connection.HttpProxy	使用指定的网络代理。

WebSocketServerConfig¹⁹⁺

Phone19+PC/2in119+Tablet19+TV19+Wearable19+

启动服务端的service时，需要输入的配置信息和说明。

系统能力：SystemCapability.Communication.NetStack

展开

名称	类型	只读	可选	说明
serverIP	string	否	是	服务端监听特定ip地址，默认是"0.0.0.0"。
serverPort	number	否	否	服务端监听的端口号。
serverCert	ServerCert	否	是	指定服务端证书的信息，包括服务端证书文件路径和服务端证书的私钥文件路径。
protocol	string	否	是	自定义协议。
maxConcurrentClientsNumber	number	否	否	最大并发客户端数量，当达到最大数时，服务端拒绝新连接。默认最大数量为10。
maxConnectionsForOneClient	number	否	否	单个客户端的最大连接数。默认最大数量为10。

ServerCert¹⁹⁺

Phone19+PC/2in119+Tablet19+TV19+Wearable19+

指定服务端证书的信息，包括服务端证书文件路径和服务端证书的私钥文件路径。

系统能力：SystemCapability.Communication.NetStack

展开

名称	类型	只读	可选	说明
certPath	string	否	否	服务端证书文件路径。
keyPath	string	否	否	服务端证书的私钥文件路径。

WebSocketMessage¹⁹⁺

Phone19+PC/2in119+Tablet19+TV19+Wearable19+

从指定客户端接收到的消息，包括客户端的信息和数据。

系统能力：SystemCapability.Communication.NetStack

展开

名称	类型	只读	可选	说明
data	string \|ArrayBuffer	否	否	接收到的客户端发的消息数据。
clientConnection	WebSocketConnection	否	否	客户端信息，包括客户端的ip地址和端口号port。

WebSocketConnection¹⁹⁺

Phone19+PC/2in119+Tablet19+TV19+Wearable19+

客户端信息，包括客户端的ip地址和端口号port。

系统能力：SystemCapability.Communication.NetStack

展开

名称	类型	只读	可选	说明
clientIP	string	否	否	客户端的ip地址。
clientPort	number	否	否	客户端的端口号port。

ClientConnectionCloseCallback¹⁹⁺

Phone19+PC/2in119+Tablet19+TV19+Wearable19+

type ClientConnectionCloseCallback = (clientConnection: WebSocketConnection, closeReason: CloseResult) => void

关闭WebSocketServer连接时，订阅close事件得到的指定客户端的关闭结果。

系统能力：SystemCapability.Communication.NetStack

参数：

展开

参数名	类型	必填	说明
clientConnection	WebSocketConnection	是	客户端信息，包括客户端的ip地址和端口号port。
closeReason	CloseResult	是	关闭WebSocket连接时，订阅close事件得到的关闭结果。

TlsProtocol

Phone26.0.0+PC/2in126.0.0+Tablet26.0.0+TV26.0.0+Wearable26.0.0+

TLS协议类型。

起始版本： 26.0.0

系统能力： SystemCapability.Communication.NetStack

模型约束： 此接口仅可在Stage模型下使用。

展开

名称	值	说明
TLS_V_1_0	0	TLS版本号1.0。
TLS_V_1_1	1	TLS版本号1.1。
TLS_V_1_2	2	TLS版本号1.2。
TLS_V_1_3	3	TLS版本号1.3。

WebSocketOpenInfo

Phone26.0.0+PC/2in126.0.0+Tablet26.0.0+TV26.0.0+Wearable26.0.0+

WebSocket连接成功后的详细信息。

起始版本： 26.0.0

系统能力： SystemCapability.Communication.NetStack

模型约束： 此接口仅可在Stage模型下使用。

展开

名称	类型	只读	可选	说明
status	number	否	否	服务器返回的状态码。例如：101表示建链成功并升级为websocket协议。
message	string	否	否	服务器返回的状态信息。与status字段对应，例如：status=101时，该字段返回"Switching Protocols"。
protocol	string	否	是	服务器返回的协商后的协议。

@ohos.net.webSocket (WebSocket连接)

导入模块

webSocket.createWebSocket

WebSocket

connect

connect

connect

send

send

close

close

close

on('open')

off('open')

on('openInfo')

off('openInfo')

on('message')

off('message')

on('close')

off('close')

on('error')

off('error')

on('dataEnd')11+

off('dataEnd')11+

on('headerReceive')12+

off('headerReceive')12+

webSocket.createWebSocketServer19+

WebSocketServer19+

start19+

send19+

listAllConnections19+

close19+

stop19+

on('connect')19+

off('connect')19+

on('messageReceive')19+

off('messageReceive')19+

on('close')19+

off('close')19+

on('error')19+

off('error')19+

WebSocketRequestOptions

ClientCert11+

ProxyConfiguration12+

WebSocketCloseOptions

CloseResult10+

ResponseHeaders12+

close错误码说明

HttpProxy12+

WebSocketServerConfig19+

ServerCert19+

WebSocketMessage19+

WebSocketConnection19+

ClientConnectionCloseCallback19+

TlsProtocol

WebSocketOpenInfo

on('dataEnd')¹¹⁺

off('dataEnd')¹¹⁺

on('headerReceive')¹²⁺

off('headerReceive')¹²⁺

webSocket.createWebSocketServer¹⁹⁺

WebSocketServer¹⁹⁺

start¹⁹⁺

send¹⁹⁺

listAllConnections¹⁹⁺

close¹⁹⁺

stop¹⁹⁺

on('connect')¹⁹⁺

off('connect')¹⁹⁺

on('messageReceive')¹⁹⁺

off('messageReceive')¹⁹⁺

on('close')¹⁹⁺

off('close')¹⁹⁺

on('error')¹⁹⁺

off('error')¹⁹⁺

ClientCert¹¹⁺

ProxyConfiguration¹²⁺

CloseResult¹⁰⁺

ResponseHeaders¹²⁺

HttpProxy¹²⁺

WebSocketServerConfig¹⁹⁺

ServerCert¹⁹⁺

WebSocketMessage¹⁹⁺

WebSocketConnection¹⁹⁺

ClientConnectionCloseCallback¹⁹⁺