
简体中文
注意事项
uni.onSocketOpen、uni.onSocketError、uni.sendSocketMessage、uni.onSocketMessage、uni.closeSocket、uni.onSocketClose 操作的是应用全局范围创建的第一个 WebSocket 连接,当应用中存在多个 WebSocket 连接时,不能通过以上方法进行操作管理。这时需要通过 uni.connectSocket 返回的 SocketTask 对象的 onOpen、onError、send、onMessage、close、onClose 方法进行操作。
为了有更好的兼容性,不要使用 uni 上已废弃的 uni.onSocketOpen、uni.onSocketError、uni.sendSocketMessage、uni.onSocketMessage、uni.closeSocket、uni.onSocketClose 等方法。
创建一个 WebSocket 连接。
Web | 微信小程序 | Android | iOS | iOS uni-app x UTS 插件 | HarmonyOS |
---|---|---|---|---|---|
4.0 | 4.41 | 3.91 | 4.11 | 4.11 | 4.61 |
名称 | 类型 | 必填 | 默认值 | 兼容性 | 描述 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
options | ConnectSocketOptions | 是 | - | - | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
名称 | 类型 | 必备 | 默认值 | 兼容性 | 描述 |
---|---|---|---|---|---|
errMsg | string | 是 | - | - |
名称 | 类型 | 必备 | 默认值 | 兼容性 | 描述 |
---|---|---|---|---|---|
errCode | number | 是 | - | - | 错误码 - 600009 URL格式不合法 |
errSubject | string | 是 | - | - | 统一错误主题(模块)名称 |
data | any | 否 | - | - | 错误信息中包含的数据 |
cause | Error | 否 | - | - | 源错误信息,可以包含多个错误,详见SourceError |
errMsg | string | 是 | - | - |
类型 |
---|
SocketTask |
send 通过 WebSocket 连接发送数据
Web | 微信小程序 | Android | iOS | iOS uni-app x UTS 插件 | HarmonyOS |
---|---|---|---|---|---|
4.0 | 4.41 | 3.91 | 4.11 | 4.11 | 4.61 |
名称 | 类型 | 必填 | 默认值 | 兼容性 | 描述 | ||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
options | SendSocketMessageOptions | 是 | - | - | |||||||||||||||||||||||||||||||
|
名称 | 类型 | 必备 | 默认值 | 兼容性 | 描述 | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
errCode | number | 是 | - | - | 错误码 | ||||||||||||
| |||||||||||||||||
errSubject | string | 是 | - | - | 统一错误主题(模块)名称 | ||||||||||||
data | any | 否 | - | - | 错误信息中包含的数据 | ||||||||||||
cause | Error | 否 | - | - | 源错误信息,可以包含多个错误,详见SourceError | ||||||||||||
errMsg | string | 是 | - | - |
close 关闭 WebSocket 连接
Web | 微信小程序 | Android | iOS | iOS uni-app x UTS 插件 | HarmonyOS |
---|---|---|---|---|---|
4.0 | 4.41 | 3.91 | 4.11 | 4.11 | 4.61 |
名称 | 类型 | 必填 | 默认值 | 兼容性 | 描述 | ||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
options | CloseSocketOptions | 是 | - | - | |||||||||||||||||||||||||||||||||||||
|
onOpen 监听 WebSocket 连接打开事件
Web | 微信小程序 | Android | iOS | iOS uni-app x UTS 插件 | HarmonyOS |
---|---|---|---|---|---|
4.0 | 4.41 | 3.91 | 4.11 | 4.11 | 4.61 |
名称 | 类型 | 必填 | 默认值 | 兼容性 | 描述 |
---|---|---|---|---|---|
callback | (result: OnSocketOpenCallbackResult) => void | 是 | - | - |
名称 | 类型 | 必备 | 默认值 | 兼容性 | 描述 |
---|---|---|---|---|---|
header | any | 是 | - | 连接成功的 HTTP 响应 Header |
onClose 监听 WebSocket 连接关闭事件
Web | 微信小程序 | Android | iOS | iOS uni-app x UTS 插件 | HarmonyOS |
---|---|---|---|---|---|
4.0 | 4.41 | 3.91 | 4.11 | 4.11 | 4.61 |
名称 | 类型 | 必填 | 默认值 | 兼容性 | 描述 |
---|---|---|---|---|---|
callback | (result: any) => void | 是 | - | - |
onError 监听 WebSocket 错误
Web | 微信小程序 | Android | iOS | iOS uni-app x UTS 插件 | HarmonyOS |
---|---|---|---|---|---|
4.0 | 4.41 | 3.91 | 4.11 | 4.11 | 4.61 |
名称 | 类型 | 必填 | 默认值 | 兼容性 | 描述 |
---|---|---|---|---|---|
callback | (result: GeneralCallbackResult) => void | 是 | - | - |
onMessage 监听 WebSocket 接受到服务器的消息事件
Web | 微信小程序 | Android | iOS | iOS uni-app x UTS 插件 | HarmonyOS |
---|---|---|---|---|---|
4.0 | 4.41 | 3.91 | 4.11 | 4.11 | 4.61 |
名称 | 类型 | 必填 | 默认值 | 兼容性 | 描述 |
---|---|---|---|---|---|
callback | (result: OnSocketMessageCallbackResult) => void | 是 | - | - |
名称 | 类型 | 必备 | 默认值 | 兼容性 | 描述 |
---|---|---|---|---|---|
data | any | 是 | - | 服务器返回的消息, app平台从 4.61 版本开始支持ArrayBuffer |
监听WebSocket连接打开事件。 已废弃,使用 SocketTask 的 onOpen 替换。
Web | 微信小程序 | Android | iOS | iOS uni-app x UTS 插件 | HarmonyOS |
---|---|---|---|---|---|
4.0 | 4.41 | 3.91 | 4.11 | 4.11 | 4.61 |
名称 | 类型 | 必填 | 默认值 | 兼容性 | 描述 |
---|---|---|---|---|---|
options | (result: OnSocketOpenCallbackResult) => void | 是 | - | - |
名称 | 类型 | 必备 | 默认值 | 兼容性 | 描述 |
---|---|---|---|---|---|
header | any | 是 | - | 连接成功的 HTTP 响应 Header |
监听WebSocket错误。 已废弃,使用 SocketTask 的 onError 替换。
Web | 微信小程序 | Android | iOS | iOS uni-app x UTS 插件 | HarmonyOS |
---|---|---|---|---|---|
4.0 | 4.41 | 3.91 | 4.11 | 4.11 | 4.61 |
名称 | 类型 | 必填 | 默认值 | 兼容性 | 描述 |
---|---|---|---|---|---|
callback | (result: OnSocketErrorCallbackResult) => void | 是 | - | - |
名称 | 类型 | 必备 | 默认值 | 兼容性 | 描述 |
---|---|---|---|---|---|
errMsg | string | 是 | - | 错误信息 |
通过 WebSocket 连接发送数据,需要先 uni.connectSocket,并在 uni.onSocketOpen 回调之后才能发送。 已废弃,使用 SocketTask 的 send 替换。
Web | 微信小程序 | Android | iOS | iOS uni-app x UTS 插件 | HarmonyOS |
---|---|---|---|---|---|
4.0 | 4.41 | 3.91 | 4.11 | 4.11 | 4.61 |
名称 | 类型 | 必填 | 默认值 | 兼容性 | 描述 | ||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
options | SendSocketMessageOptions | 是 | - | - | - | ||||||||||||||||||||||||||||||
|
名称 | 类型 | 必备 | 默认值 | 兼容性 | 描述 | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
errCode | number | 是 | - | - | 错误码 | ||||||||||||
| |||||||||||||||||
errSubject | string | 是 | - | - | 统一错误主题(模块)名称 | ||||||||||||
data | any | 否 | - | - | 错误信息中包含的数据 | ||||||||||||
cause | Error | 否 | - | - | 源错误信息,可以包含多个错误,详见SourceError | ||||||||||||
errMsg | string | 是 | - | - |
监听WebSocket接受到服务器的消息事件。 已废弃,使用 SocketTask 的 onMessage 替换。
Web | 微信小程序 | Android | iOS | iOS uni-app x UTS 插件 | HarmonyOS |
---|---|---|---|---|---|
4.0 | 4.41 | 3.91 | 4.11 | 4.11 | 4.61 |
名称 | 类型 | 必填 | 默认值 | 兼容性 | 描述 |
---|---|---|---|---|---|
callback | (result: OnSocketMessageCallbackResult) => void | 是 | - | - |
名称 | 类型 | 必备 | 默认值 | 兼容性 | 描述 |
---|---|---|---|---|---|
data | any | 是 | - | 服务器返回的消息, app平台从 4.61 版本开始支持ArrayBuffer |
关闭 WebSocket 连接。 已废弃,使用 SocketTask 的 close 替换。
Web | 微信小程序 | Android | iOS | iOS uni-app x UTS 插件 | HarmonyOS |
---|---|---|---|---|---|
4.0 | 4.41 | 3.91 | 4.11 | 4.11 | 4.61 |
名称 | 类型 | 必填 | 默认值 | 兼容性 | 描述 | ||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
options | CloseSocketOptions | 是 | - | - | - | ||||||||||||||||||||||||||||||||||||
|
监听WebSocket关闭。 已废弃,使用 SocketTask 的 onClose 替换。
Web | 微信小程序 | Android | iOS | iOS uni-app x UTS 插件 | HarmonyOS |
---|---|---|---|---|---|
4.0 | 4.41 | 3.91 | 4.11 | 4.11 | 4.61 |
名称 | 类型 | 必填 | 默认值 | 兼容性 | 描述 |
---|---|---|---|---|---|
callback | (result: OnSocketCloseCallbackResult) => void | 是 | - | - |
名称 | 类型 | 必备 | 默认值 | 兼容性 | 描述 |
---|---|---|---|---|---|
code | number | 是 | - | 一个数字值表示关闭连接的状态号,表示连接被关闭的原因。 | |
reason | string | 是 | - | 一个可读的字符串,表示连接被关闭的原因。 |
示例为hello uni-app x alpha分支,与最新HBuilderX Alpha版同步。与最新正式版同步的master分支示例另见
示例
<template>
<page-head title="websocket通讯示例"></page-head>
<view class="uni-padding-wrap">
<view class="uni-btn-v">
<text class="websocket-msg">{{ showMsg }}</text>
<button class="uni-btn-v" type="primary" @click="connect">
连接websocket服务
</button>
<button class="uni-btn-v" v-show="connected" type="primary" @click="send">
发送一条消息
</button>
<button class="uni-btn-v" type="primary" @click="close">
断开websocket服务
</button>
<text class="websocket-tips">发送消息后会收到一条服务器返回的消息(与发送的消息内容一致)</text>
<text class="websocket-tips">web端和小程序端uni-push功能、app-android端和app-ios端的web-view组件日志回显、app-harmony端的日志回显会占用一个socket链接,此时使用全局的socket api会引发混乱。应使用socketTask操作websocket链接。</text>
<text class="websocket-tips">小程序端日志回显功能也会占用一个socket链接,如果不希望使用此功能可以在HBuilderX控制台关闭日志回显。</text>
<button class="uni-btn-v" type="primary" @click="goSocketTask">
跳转 socketTask 示例
</button>
</view>
</view>
</template>
<script>
export default {
data() {
return {
connected: false,
connecting: false,
msg: '',
roomId: '',
platform: '',
}
},
computed: {
showMsg() : string {
if (this.connected) {
if (this.msg.length > 0) {
return '收到消息:' + this.msg
} else {
return '等待接收消息'
}
} else {
return '尚未连接'
}
},
},
onLoad() {
this.platform = uni.getDeviceInfo().platform as string
},
onUnload() {
uni.closeSocket({
code: 1000,
reason: 'close reason from client',
success: (res : any) => {
console.log('uni.closeSocket success', res)
},
fail: (err : any) => {
console.log('uni.closeSocket fail', err)
},
} as CloseSocketOptions)
uni.hideLoading()
},
methods: {
connect() {
if (this.connected || this.connecting) {
uni.showModal({
content: '正在连接或者已经连接,请勿重复连接',
showCancel: false,
})
return
}
this.connecting = true
uni.showLoading({
title: '连接中...',
})
uni.connectSocket({
url: 'wss://websocket.dcloud.net.cn',
header: null,
protocols: null,
success: (res : any) => {
// 这里是接口调用成功的回调,不是连接成功的回调,请注意
console.log('uni.connectSocket success', res)
},
fail: (err : any) => {
// 这里是接口调用失败的回调,不是连接失败的回调,请注意
console.log('uni.connectSocket fail', err)
},
})
uni.onSocketOpen((res) => {
this.connecting = false
this.connected = true
uni.hideLoading()
uni.showToast({
icon: 'none',
title: '连接成功',
})
console.log('onOpen', res)
})
uni.onSocketError((err) => {
this.connecting = false
this.connected = false
uni.hideLoading()
uni.showModal({
content: '连接失败,可能是websocket服务不可用,请稍后再试',
showCancel: false,
})
console.log('onError', err)
})
uni.onSocketMessage((res) => {
if(res.data instanceof ArrayBuffer){
var int8 = new Int8Array(res.data)
this.msg = int8.toString()
console.log('onMessage', res)
}else{
this.msg = res.data as string
console.log('onMessage', res)
}
})
uni.onSocketClose((res) => {
this.connected = false
this.msg = ''
console.log('onClose', res)
})
},
send() {
uni.sendSocketMessage({
data:
'from ' +
this.platform +
' : ' +
parseInt((Math.random() * 10000).toString()).toString(),
success: (res : any) => {
console.log(res)
},
fail: (err : any) => {
console.log(err)
},
} as SendSocketMessageOptions)
},
close() {
uni.closeSocket({
code: 1000,
reason: 'close reason from client',
success: (res : any) => {
console.log('uni.closeSocket success', res)
},
fail: (err : any) => {
console.log('uni.closeSocket fail', err)
},
} as CloseSocketOptions)
},
goSocketTask() {
uni.navigateTo({
url: '/pages/API/websocket/socketTask',
})
}
},
}
</script>
<style>
.uni-btn-v {
padding: 5px 0;
}
.uni-btn-v {
margin: 10px 0;
}
.websocket-msg {
padding: 40px 0px;
text-align: center;
font-size: 14px;
line-height: 40px;
color: #666666;
}
.websocket-tips {
padding: 10px 0px;
text-align: center;
font-size: 14px;
line-height: 24px;
color: #666666;
}
</style>
名称 | 类型 | 必备 | 默认值 | 兼容性 | 描述 |
---|---|---|---|---|---|
errMsg | string | 是 | - | 错误信息 |