tencent cloud

WebSocket
最后更新时间:2025-11-26 15:32:08
WebSocket
最后更新时间: 2025-11-26 15:32:08
说明:
推荐使用 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 = false
let socketMsgQueue = []
wx.connectSocket({
url: 'test.php'
})

wx.onSocketOpen(function(res) {
socketOpen = true
for (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 设置
timeout
number
-
超时时间,单位为毫秒
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

.send

该 方法 使用方式为 SocketTask.send(Object object)
功能说明:通过 WebSocket 连接发送数据。
参数及说明:Object object。
属性
类型
默认值
必填
说明
data
string/ArrayBuffer
-
需要发送的内容
success
function
-
接口调用成功的回调函数
fail
function
-
接口调用失败的回调函数
complete
function
-
接口调用结束的回调函数(调用成功、失败都会执行)

本页内容是否解决了您的问题?
您也可以 联系销售 提交工单 以寻求帮助。

文档反馈