说明:
推荐使用 SocketTask 的方式去管理 webSocket 链接,每一条链路的生命周期都更加可控,同时存在多个 webSocket 的链接的情况下使用 wx 前缀的方法可能会带来一些和预期不一致的情况。
sendSocketMessage
该 API 使用方法为 wx.sendSocketMessage(Object object)
功能说明:通过 WebSocket 连接发送数据。需要先 wx.connectSocket,并在 wx.onSocketOpen 回调之后才能发送。
参数及说明:Object object。
属性 | 类型 | 默认值 | 必填 | 说明 |
data | string/ArrayBuffer | - | 是 | 需要发送的内容 |
success | function | - | 否 | 接口调用成功的回调函数 |
fail | function | - | 否 | 接口调用失败的回调函数 |
complete | function | - | 否 | 接口调用结束的回调函数(调用成功、失败都会执行) |
示例代码:
let socketOpen = falselet socketMsgQueue = []wx.connectSocket({url: 'test.php'})wx.onSocketOpen(function(res) {socketOpen = truefor (let i = 0; i < socketMsgQueue.length; i++){sendSocketMessage(socketMsgQueue[i])}socketMsgQueue = []})function sendSocketMessage(msg) {if (socketOpen) {wx.sendSocketMessage({data:msg})} else {socketMsgQueue.push(msg)}}
onSocketOpen
该 API 使用方法为 wx.onSocketOpen(function listener)
功能说明:监听 WebSocket 连接打开事件。
参数及说明:function listener,WebSocket 连接打开事件的监听函数。
属性 | 类型 | 说明 |
header | object | 连接成功的 HTTP 响应 Header |
onSocketMessage
该 API 使用方法为 wx.onSocketMessage(function listener)
功能说明:监听 WebSocket 接收到服务器的消息事件。
参数及说明:function listener,WebSocket 接收到服务器的消息事件的监听函数。
属性 | 类型 | 说明 |
data | string/ArrayBuffer | 服务器返回的消息 |
onSocketError
该 API 使用方法为 wx.onSocketError(function listener)
功能说明:监听 WebSocket 错误事件。
参数及说明:function listener,WebSocket 错误事件的监听函数。
属性 | 类型 | 说明 |
errMsg | string | 错误信息 |
onSocketClose
该 API 使用方法为 wx.onSocketClose(function listener)
功能说明:监听 WebSocket 连接关闭事件。
参数及说明:function listener,WebSocket 连接关闭事件的监听函数。
属性 | 类型 | 说明 |
code | number | 一个数字值表示关闭连接的状态号,表示连接被关闭的原因 |
reason | string | 一个可读的字符串,表示连接被关闭的原因 |
connectSocket
该 API 使用方法为 SocketTask wx.connectSocket(Object object)
功能说明:创建一个 WebSocket 连接。使用前请注意阅读微信的相关说明。
参数及说明:Object object。
属性 | 类型 | 默认值 | 必填 | 说明 |
url | string | - | 是 | 开发者服务器 wss 接口地址 |
header | Object | - | 否 | HTTP Header,Header 中不能设置 Referer |
protocols | Array.<string> | - | 否 | 子协议数组 |
tcpNoDelay | boolean | false | 否 | 建立 TCP 连接的时候的 TCP_NODELAY 设置 |
perMessageDeflate | boolean | false | 否 | 是否开启压缩扩展 |
timeout | number | - | 否 | 超时时间,单位为毫秒 |
forceCellularNetwork | boolean | false | 否 | wifi 下使用移动网络发送请求 |
success | function | - | 否 | 接口调用成功的回调函数 |
fail | function | - | 否 | 接口调用失败的回调函数 |
complete | function | - | 否 | 接口调用结束的回调函数(调用成功、失败都会执行) |
返回值:SocketTask。
并发数
1.5.0及以上版本,最多可以同时存在5个 WebSocket 连接。
1.5.0以下版本,一个小程序同时只能有一个 WebSocket 连接,如果当前已存在一个 WebSocket 连接,会自动关闭该连接,并重新创建一个 WebSocket 连接。
示例代码
wx.connectSocket({url: 'wss://example.qq.com',header:{'content-type': 'application/json'},protocols: ['protocol1']})
closeSocket
该 API 使用方法为 wx.closeSocket(Object object)
功能说明:关闭 WebSocket 连接,使用方法为。
参数及说明:Object object。
属性 | 类型 | 默认值 | 必填 | 说明 |
code | number | 1000(表示正常关闭连接) | 否 | 一个数字值表示关闭连接的状态号,表示连接被关闭的原因 |
reason | string | - | 否 | 一个可读的字符串,表示连接被关闭的原因。这个字符串必须是不长于 123 字节的 UTF-8 文本(不是字符) |
success | function | - | 否 | 接口调用成功的回调函数 |
fail | function | - | 否 | 接口调用失败的回调函数 |
complete | function | - | 否 | 接口调用结束的回调函数(调用成功、失败都会执行) |
示例代码:
wx.connectSocket({url: 'test.php'})//注意这里有时序问题,//如果 wx.connectSocket 还没回调 wx.onSocketOpen,而先调用 wx.closeSocket,那么就做不到关闭 WebSocket 的目的。//必须在 WebSocket 打开期间调用 wx.closeSocket 才能关闭。wx.onSocketOpen(function() {wx.closeSocket()})wx.onSocketClose(function(res) {console.log('WebSocket 已关闭!')})
SocketTask
.close
该 方法 使用方式为 SocketTask.close(Object object)
功能说明:关闭 WebSocket 连接。
参数及说明:Object object。
属性 | 类型 | 默认值 | 必填 | 说明 |
code | number | 1000(表示正常关闭连接) | 否 | 一个数字值表示关闭连接的状态号,表示连接被关闭的原因 |
reason | string | - | 否 | 一个可读的字符串,表示连接被关闭的原因。这个字符串必须是不长于 123 字节的 UTF-8 文本(不是字符) |
success | function | - | 否 | 接口调用成功的回调函数 |
fail | function | - | 否 | 接口调用失败的回调函数 |
complete | function | - | 否 | 接口调用结束的回调函数(调用成功、失败都会执行) |
.onClose
该 方法 使用方式为 SocketTask.onClose(function listener)
功能说明:监听 WebSocket 连接关闭事件。
参数及说明:function listener,WebSocket 连接关闭事件的监听函数。
属性 | 类型 | 说明 |
code | number | 一个数字值表示关闭连接的状态号,表示连接被关闭的原因 |
reason | string | 一个可读的字符串,表示连接被关闭的原因 |
.onError
该 方法 使用方式为 SocketTask.onError(function listener)
功能说明:监听 WebSocket 错误事件。
参数及说明:function listener,WebSocket 错误事件的监听函数。
属性 | 类型 | 说明 |
errMsg | string | 错误信息 |
.onMessage
该 方法 使用方式为 SocketTask.onMessage(function listener)
功能说明:监听 WebSocket 接收到服务器的消息事件。
参数及说明:function listener,WebSocket 接收到服务器的消息事件的监听函数。
属性 | 类型 | 说明 |
data | string/ArrayBuffer | 服务器返回的消息 |
.onOpen
该 方法 使用方式为 SocketTask.onOpen(function listener)
功能说明:监听 WebSocket 连接打开事件。
参数及说明:function listener,WebSocket 连接打开事件的监听函数。
属性 | 类型 | 说明 |
header | Object | 连接成功的 HTTP 响应 Header |
profile | Object | 网络请求过程中一些调试信息 |
profile 结构值
结构属性 | 类型 | 说明 |
fetchStart | number | 组件准备好使用 SOCKET 建立请求的时间,这发生在检查本地缓存之前 |
domainLookupStart | number | DNS 域名查询开始的时间,如果使用了本地缓存(即无 DNS 查询)或持久连接,则与 fetchStart 值相等 |
domainLookupEnd | number | DNS 域名查询完成的时间,如果使用了本地缓存(即无 DNS 查询)或持久连接,则与 fetchStart 值相等 |
connectStart | number | 开始建立连接的时间,如果是持久连接,则与 fetchStart 值相等。注意如果在传输层发生了错误且重新建立连接,则这里显示的是新建立的连接开始的时间 |
connectEnd | number | 完成建立连接的时间(完成握手),如果是持久连接,则与 fetchStart 值相等。注意如果在传输层发生了错误且重新建立连接,则这里显示的是新建立的连接完成的时间。注意这里握手结束,包括安全连接建立完成、SOCKS 授权通过 |
rtt | number | 单次连接的耗时,包括 connect,tls |
handshakeCost | number | 握手耗时 |
cost | number | 上层请求到返回的耗时 |
.send
该 方法 使用方式为 SocketTask.send(Object object)
功能说明:通过 WebSocket 连接发送数据。
参数及说明:Object object。
属性 | 类型 | 默认值 | 必填 | 说明 |
data | string/ArrayBuffer | - | 是 | 需要发送的内容 |
success | function | - | 否 | 接口调用成功的回调函数 |
fail | function | - | 否 | 接口调用失败的回调函数 |
complete | function | - | 否 | 接口调用结束的回调函数(调用成功、失败都会执行) |