简体中文
简体中文
# uni.connectSocket(OBJECT)
创建一个 WebSocket 连接。
在各个小程序平台运行时，网络相关的 API 在使用前需要配置域名白名单。
uni-app 的 socket，分全局 socket 和 socketTask。全局 socket 只能有一个，一旦被占用就无法再开启。所以不推荐使用全局 socket，一般使用 socketTask。
小程序上，socketTask 也有数量限制，具体需要参阅各家小程序文档。
注意：小程序的运行日志回显、uniPush 的小程序版，均基于 socket，都会占用 socketTask 通道数量。运行日志回显是可以关闭的，详见
# connectSocket 兼容性
| HarmonyOS |
|---|
| HBuilderX 4.23 |
OBJECT 参数说明
| 参数名 | 类型 | 必填 | 说明 | 平台差异说明 |
|---|---|---|---|---|
| url | String | 是 | 服务器接口地址 | 小程序中必须是 wss:// 协议 |
| multiple | Boolean | 否 | 是否多实例。传入 true 时，将返回一个包含 SocketTask 实例。 | 仅支付宝小程序支持 |
| header | Object | 否 | HTTP Header , header 中不能设置 Referer | 小程序、App 2.9.6+ |
| method | String | 否 | 默认是 GET，有效值：OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, CONNECT | 仅微信小程序支持 |
| protocols | Array<String> | 否 | 子协议数组 | App、H5、微信小程序、百度小程序、抖音小程序、飞书小程序、支付宝小程序 |
| success | Function | 否 | 接口调用成功的回调函数 | |
| fail | Function | 否 | 接口调用失败的回调函数 | |
| complete | Function | 否 | 接口调用结束的回调函数（调用成功、失败都会执行） |
示例代码
uni.connectSocket({
url: "wss://www.example.com/socket",
header: {
"content-type": "application/json",
},
protocols: ["protocol1"],
method: "GET",
});
返回值
如果希望返回一个 socketTask 对象，需要至少传入 success / fail / complete 参数中的一个。例如：
var socketTask = uni.connectSocket({
url: "wss://www.example.com/socket", //仅为示例，并非真实接口地址。
complete: () => {},
});
如果没有传入 success / fail / complete 参数，则会返回封装后的 Promise 对象：Promise 封装
注意事项
- 网络请求的
超时时间可以统一在manifest.json中配置 networkTimeout。 - App 平台，2.2.6 以下的版本，不支持
ArrayBuffer类型的数据收发。老版本不愿升级也可以使用 plus-websocket 插件 插件替代。 - App 平台 2.2.6 以下的版本，所有
vue页面只能使用一个websocket连接。App 下可以使用 plus-websocket 插件替代实现多连接。 - 微信小程序平台 1.7.0 及以上版本，最多可以同时存在 5 个 WebSocket 连接。老版本只支持一个 socket 连接。
- 百度小程序平台自基础库版本 1.9.4 及以后支持多个 socket 连接。老版本只支持一个 socket 连接。
- QQ 小程序、支付宝小程序平台最多支持同时存在 5 个 socket 连接。
- uni-push2.0 在 web、小程序以及 APP 的非离线模式下的底层实现都是基于一个 socket。如果你的项目需要再次使用 socket，请通过socketTask实现。
# 返回值
| 类型 |
|---|
| SocketTask |
# SocketTask 的方法
# send(options: SendSocketMessageOptions): void;
send 通过 WebSocket 连接发送数据
# send 兼容性
| HarmonyOS |
|---|
| HBuilderX 4.23 |
# 参数 HarmonyOS 兼容性
| 名称 | 类型 | 必填 | 默认值 | 兼容性 | 描述 | ||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| options | SendSocketMessageOptions | 是 | - | - | |||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||
# SendSocketMessageFail 的属性值
| 名称 | 类型 | 必填 | 默认值 | 兼容性 | 描述 |
|---|---|---|---|---|---|
| errCode | number | 是 | - | - | 错误码 |
| errSubject | string | 是 | - | - | 统一错误主题（模块）名称 |
| data | any | 否 | - | - | 错误信息中包含的数据 |
| cause | Error | 否 | - | - | 源错误信息，可以包含多个错误，详见SourceError |
| errMsg | string | 是 | - | - |
# close(options: CloseSocketOptions): void;
close 关闭 WebSocket 连接
# close 兼容性
| HarmonyOS |
|---|
| HBuilderX 4.23 |
# 参数 HarmonyOS 兼容性
| 名称 | 类型 | 必填 | 默认值 | 兼容性 | 描述 | ||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| options | CloseSocketOptions | 是 | - | - | |||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||
# onOpen(callback: (result: OnSocketOpenCallbackResult) => void): void;
onOpen 监听 WebSocket 连接打开事件
# onOpen 兼容性
| HarmonyOS |
|---|
| HBuilderX 4.23 |
# 参数 HarmonyOS 兼容性
| 名称 | 类型 | 必填 | 默认值 | 兼容性 | 描述 |
|---|---|---|---|---|---|
| callback | (result: OnSocketOpenCallbackResult) => void | 是 | - | - |
# OnSocketOpenCallbackResult 的属性值
| 名称 | 类型 | 必填 | 默认值 | 兼容性 | 描述 |
|---|---|---|---|---|---|
| header | any | 是 | - | 连接成功的 HTTP 响应 Header |
# onClose(callback: (result: any) => void): void;
onClose 监听 WebSocket 连接关闭事件
# onClose 兼容性
| HarmonyOS |
|---|
| HBuilderX 4.23 |
# 参数 HarmonyOS 兼容性
| 名称 | 类型 | 必填 | 默认值 | 兼容性 | 描述 |
|---|---|---|---|---|---|
| callback | (result: any) => void | 是 | - | - |
# onError(callback: (result: GeneralCallbackResult) => void): void;
onError 监听 WebSocket 错误
# onError 兼容性
| HarmonyOS |
|---|
| HBuilderX 4.23 |
# 参数 HarmonyOS 兼容性
| 名称 | 类型 | 必填 | 默认值 | 兼容性 | 描述 |
|---|---|---|---|---|---|
| callback | (result: GeneralCallbackResult) => void | 是 | - | - |
# onMessage(callback: (result: OnSocketMessageCallbackResult) => void): void;
onMessage 监听 WebSocket 接受到服务器的消息事件
# onMessage 兼容性
| HarmonyOS |
|---|
| HBuilderX 4.23 |
# 参数 HarmonyOS 兼容性
| 名称 | 类型 | 必填 | 默认值 | 兼容性 | 描述 |
|---|---|---|---|---|---|
| callback | (result: OnSocketMessageCallbackResult) => void | 是 | - | - |
# OnSocketMessageCallbackResult 的属性值
| 名称 | 类型 | 必填 | 默认值 | 兼容性 | 描述 |
|---|---|---|---|---|---|
| data | any | 是 | - | 服务器返回的消息, app平台从 4.61 版本开始支持ArrayBuffer |
# uni.onSocketOpen(CALLBACK)
监听 WebSocket 连接打开事件。
已废弃，使用 SocketTask 的 onOpen 替换。
平台兼容性
抖音小程序不支持
# onSocketOpen 兼容性
| HarmonyOS |
|---|
| HBuilderX 4.23 |
CALLBACK 返回参数
| 属性 | 类型 | 说明 |
|---|---|---|
| header | Object | 连接成功的 HTTP 响应 Header |
示例代码：
uni.connectSocket({
url: "wss://www.example.com/socket",
});
uni.onSocketOpen(function (res) {
console.log("WebSocket连接已打开！");
});
# uni.onSocketError(CALLBACK)
监听 WebSocket 错误。
已废弃，使用 SocketTask 的 onError 替换。
平台兼容性
抖音小程序不支持
# onSocketError 兼容性
| HarmonyOS |
|---|
| HBuilderX 4.23 |
示例代码
uni.connectSocket({
url: "wss://www.example.com/socket",
});
uni.onSocketOpen(function (res) {
console.log("WebSocket连接已打开！");
});
uni.onSocketError(function (res) {
console.log("WebSocket连接打开失败，请检查！");
});
# uni.sendSocketMessage(OBJECT)
通过 WebSocket 连接发送数据，需要先 uni.connectSocket，并在 uni.onSocketOpen 回调之后才能发送。
已废弃，使用 SocketTask 的 send 替换。
平台兼容性
抖音小程序不支持
# sendSocketMessage 兼容性
| HarmonyOS |
|---|
| HBuilderX 4.23 |
OBJECT 参数说明：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| data | String/ArrayBuffer | 是 | 需要发送的内容 |
| success | Function | 否 | 接口调用成功的回调函数 |
| fail | Function | 否 | 接口调用失败的回调函数 |
| complete | Function | 否 | 接口调用结束的回调函数（调用成功、失败都会执行） |
示例代码
var socketOpen = false;
var socketMsgQueue = [];
uni.connectSocket({
url: "wss://www.example.com/socket",
});
uni.onSocketOpen(function (res) {
socketOpen = true;
for (var i = 0; i < socketMsgQueue.length; i++) {
sendSocketMessage(socketMsgQueue[i]);
}
socketMsgQueue = [];
});
function sendSocketMessage(msg) {
if (socketOpen) {
uni.sendSocketMessage({
data: msg,
});
} else {
socketMsgQueue.push(msg);
}
}
注意事项
- 出于性能的权衡，在 Android 端底层实现上发送队列占用的内存不能超过 16M，一旦超过将导致连接被关闭。
# uni.onSocketMessage(CALLBACK)
监听 WebSocket 接受到服务器的消息事件。
已废弃，使用 SocketTask 的 onMessage 替换。
平台兼容性
抖音小程序不支持
# onSocketMessage 兼容性
| HarmonyOS |
|---|
| HBuilderX 4.23 |
CALLBACK 返回参数
| 参数 | 类型 | 说明 |
|---|---|---|
| data | String/ArrayBuffer | 服务器返回的消息 |
示例代码：
uni.connectSocket({
url: "wss://www.example.com/socket",
});
uni.onSocketMessage(function (res) {
console.log("收到服务器内容：" + res.data);
});
# uni.closeSocket(OBJECT)
关闭 WebSocket 连接。
已废弃，使用 SocketTask 的 close 替换。
平台兼容性
抖音小程序不支持
# closeSocket 兼容性
| HarmonyOS |
|---|
| HBuilderX 4.23 |
OBJECT 参数说明
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| code | Number | 否 | 一个数字值表示关闭连接的状态号，表示连接被关闭的原因。如果这个参数没有被指定，默认的取值是 1000 （表示正常连接关闭） |
| reason | String | 否 | 一个可读的字符串，表示连接被关闭的原因。这个字符串必须是不长于 123 字节的 UTF-8 文本（不是字符） |
| success | Function | 否 | 接口调用成功的回调函数 |
| fail | Function | 否 | 接口调用失败的回调函数 |
| complete | Function | 否 | 接口调用结束的回调函数（调用成功、失败都会执行） |
# uni.onSocketClose(CALLBACK)
监听 WebSocket 关闭。
已废弃，使用 SocketTask 的 onClose 替换。
平台兼容性
抖音小程序不支持
# onSocketClose 兼容性
| HarmonyOS |
|---|
| HBuilderX 4.23 |
uni.connectSocket({
url: "wss://www.example.com/socket",
});
// 注意这里有时序问题，
// 如果 uni.connectSocket 还没回调 uni.onSocketOpen，而先调用 uni.closeSocket，那么就做不到关闭 WebSocket 的目的。
// 必须在 WebSocket 打开期间调用 uni.closeSocket 才能关闭。
uni.onSocketOpen(function () {
uni.closeSocket();
});
uni.onSocketClose(function (res) {
console.log("WebSocket 已关闭！");
});
