uni.connectSocket(options) @connectsocket

名称	类型	必备	默认值	描述
url	string	是	-	开发者服务器接口地址
header	UTSJSONObject \| null	否	null	如果属性名存在，且类型为UTSJSONObject返回对应的结果，不存在返回null
protocols	Array<string> \| null	否	null	子协议数组
success	(result: ConnectSocketSuccess) => void \| null	否	null	接口调用成功的回调函数
fail	(result: ConnectSocketFail) => void \| null	否	null	接口调用失败的回调函数
complete	(result: any) => void \| null	否	null	接口调用结束的回调函数（调用成功、失败都会执行）

# ConnectSocketSuccess 的属性值

名称	类型	必备	默认值	描述
errMsg	string	是	-	-

# ConnectSocketFail 的属性值

名称	类型	必备	默认值	描述
errCode	number	是	-	错误码 - 600009 URL格式不合法
errSubject	string	是	-	统一错误主题（模块）名称
data	any \| null	否	-	错误信息中包含的数据
cause	Error \| null	否	-	源错误信息，可以包含多个错误，详见SourceError
errMsg	string	是	-	-

# ConnectSocketOptions 兼容性

	Android	iOS	web
url	3.9	4.11	-
header	3.9	4.11	-
protocols	3.9	4.11	-

# 返回值

类型
SocketTask

# SocketTask 的方法

# send(options)

通过 WebSocket 连接发送数据

# 参数

名称

类型

必填

默认值

描述

options

SendSocketMessageOptions

是

名称	类型	必备	默认值	描述
data	any	是	-	需要发送的内容
success	(result: GeneralCallbackResult) => void \| null	否	null	接口调用成功的回调函数
fail	(result: SendSocketMessageFail) => void \| null	否	null	接口调用失败的回调函数
complete	(result: any) => void \| null	否	null	接口调用结束的回调函数（调用成功、失败都会执行）

# SendSocketMessageFail 的属性值

名称	类型	必备	默认值	描述
errCode	10001 \| 10002 \| 602001	是	-	错误码 - 10001 发送数据超限，发送队列不能超过16M大小。 - 10002 websocket未连接 - 602001 websocket系统错误
errSubject	string	是	-	统一错误主题（模块）名称
data	any \| null	否	-	错误信息中包含的数据
cause	Error \| null	否	-	源错误信息，可以包含多个错误，详见SourceError
errMsg	string	是	-	-

# SendSocketMessageOptions 兼容性

	Android	iOS	web
data	3.9	4.11	-

# send 兼容性

Android	iOS	web
3.9	4.11	4.0

# 参见

参见uni-app相关文档

# close(options)

关闭 WebSocket 连接

# 参数

名称

类型

必填

默认值

描述

options

CloseSocketOptions

是

名称	类型	必备	默认值	描述
code	number \| null	否	1000	一个数字值表示关闭连接的状态号，表示连接被关闭的原因。如果这个参数没有被指定，默认的取值是1000 （表示正常连接关闭）
reason	string \| null	否	""	一个可读的字符串，表示连接被关闭的原因。这个字符串必须是不长于123字节的UTF-8 文本（不是字符）
success	(result: GeneralCallbackResult) => void \| null	否	null	接口调用成功的回调函数
fail	(result: GeneralCallbackResult) => void \| null	否	null	接口调用失败的回调函数
complete	(result: GeneralCallbackResult) => void \| null	否	null	接口调用结束的回调函数（调用成功、失败都会执行）

# CloseSocketOptions 兼容性

	Android	iOS	web
code	3.9	4.11	-
reason	3.9	4.11	-

# close 兼容性

Android	iOS	web
3.9	4.11	4.0

# 参见

参见uni-app相关文档

# onOpen(callback)

监听 WebSocket 连接打开事件

# 参数

名称

类型

必填

默认值

描述

callback

OnSocketOpenCallbackResult

是

名称	类型	必备	默认值	描述
header	any	是	-	连接成功的 HTTP 响应 Header

# OnSocketOpenCallbackResult 兼容性

	Android	iOS	web
header	3.9	4.11	-

# onOpen 兼容性

Android	iOS	web
3.9	4.11	4.0

# 参见

参见uni-app相关文档

# onClose(callback)

监听 WebSocket 连接关闭事件

# 参数

名称	类型	必填	默认值	描述
callback	(result: any) => void	是	-

# onClose 兼容性

Android	iOS	web
3.9	4.11	4.0

# 参见

参见uni-app相关文档

# onError(callback)

监听 WebSocket 错误

# 参数

名称	类型	必填	默认值	描述
callback	(result: GeneralCallbackResult) => void	是	-

# onError 兼容性

Android	iOS	web
3.9	4.11	4.0

# 参见

参见uni-app相关文档

# onMessage(callback)

监听 WebSocket 接受到服务器的消息事件

# 参数

名称	类型	必填	默认值	描述
callback	(result: OnSocketMessageCallbackResult) => void	是	-

# OnSocketMessageCallbackResult 的属性值

名称	类型	必备	默认值	描述
data	any	是	-	服务器返回的消息

# OnSocketMessageCallbackResult 兼容性

	Android	iOS	web
data	3.9	4.11	-

# onMessage 兼容性

Android	iOS	web
3.9	4.11	4.0

# 参见

参见uni-app相关文档

# connectSocket 兼容性

Android	iOS	web
3.9	4.11	4.0

# 参见

参见uni-app相关文档

相关 Bug

# uni.onSocketOpen(options)

监听WebSocket连接打开事件。

# 参数

名称	类型	必填	默认值	描述
options	(result: OnSocketOpenCallbackResult) => void	是	-

# onSocketOpen 兼容性

Android	iOS	web
3.9	4.11	4.0

# 参见

参见uni-app相关文档

相关 Bug

# uni.onSocketError(callback)

下载文件资源到本地，客户端直接发起一个 HTTP GET 请求，返回文件的本地临时路径。

# 参数

名称	类型	必填	默认值	描述
callback	(result: OnSocketErrorCallbackResult) => void	是	-

# OnSocketErrorCallbackResult 的属性值

名称	类型	必备	默认值	描述
errMsg	string	是	-	错误信息

# onSocketError 兼容性

Android	iOS	web
3.9	4.11	4.0

# 参见

参见uni-app相关文档

相关 Bug

# uni.sendSocketMessage(options)

通过 WebSocket 连接发送数据，需要先 uni.connectSocket，并在 uni.onSocketOpen 回调之后才能发送。

# 参数

名称

类型

必填

默认值

描述

options

SendSocketMessageOptions

是

名称	类型	必备	默认值	描述
data	any	是	-	需要发送的内容
success	(result: GeneralCallbackResult) => void \| null	否	null	接口调用成功的回调函数
fail	(result: SendSocketMessageFail) => void \| null	否	null	接口调用失败的回调函数
complete	(result: any) => void \| null	否	null	接口调用结束的回调函数（调用成功、失败都会执行）

# SendSocketMessageFail 的属性值

名称	类型	必备	默认值	描述
errCode	10001 \| 10002 \| 602001	是	-	错误码 - 10001 发送数据超限，发送队列不能超过16M大小。 - 10002 websocket未连接 - 602001 websocket系统错误
errSubject	string	是	-	统一错误主题（模块）名称
data	any \| null	否	-	错误信息中包含的数据
cause	Error \| null	否	-	源错误信息，可以包含多个错误，详见SourceError
errMsg	string	是	-	-

# SendSocketMessageOptions 兼容性

	Android	iOS	web
data	3.9	4.11	-

# sendSocketMessage 兼容性

Android	iOS	web
3.9	4.11	4.0

# 参见

参见uni-app相关文档

相关 Bug

# 注意事项

出于性能的权衡，在底层实现上发送队列占用的内存不能超过16M，一旦超过将导致连接被关闭。

# uni.onSocketMessage(callback)

监听WebSocket接受到服务器的消息事件。

# 参数

名称	类型	必填	默认值	描述
callback	(result: OnSocketMessageCallbackResult) => void	是	-

# OnSocketMessageCallbackResult 的属性值

名称	类型	必备	默认值	描述
data	any	是	-	服务器返回的消息

# OnSocketMessageCallbackResult 兼容性

	Android	iOS	web
data	3.9	4.11	-

# onSocketMessage 兼容性

Android	iOS	web
3.9	4.11	4.0

# 参见

参见uni-app相关文档

相关 Bug

# uni.closeSocket(options)

关闭 WebSocket 连接。

# 参数

名称

类型

必填

默认值

描述

options

CloseSocketOptions

是

名称	类型	必备	默认值	描述
code	number \| null	否	1000	一个数字值表示关闭连接的状态号，表示连接被关闭的原因。如果这个参数没有被指定，默认的取值是1000 （表示正常连接关闭）
reason	string \| null	否	""	一个可读的字符串，表示连接被关闭的原因。这个字符串必须是不长于123字节的UTF-8 文本（不是字符）
success	(result: GeneralCallbackResult) => void \| null	否	null	接口调用成功的回调函数
fail	(result: GeneralCallbackResult) => void \| null	否	null	接口调用失败的回调函数
complete	(result: GeneralCallbackResult) => void \| null	否	null	接口调用结束的回调函数（调用成功、失败都会执行）

# CloseSocketOptions 兼容性

	Android	iOS	web
code	3.9	4.11	-
reason	3.9	4.11	-

# closeSocket 兼容性

Android	iOS	web
3.9	4.11	4.0

# 参见

参见uni-app相关文档

相关 Bug

# uni.onSocketClose(callback)

监听WebSocket关闭。

# 参数

名称	类型	必填	默认值	描述
callback	(result: OnSocketCloseCallbackResult) => void	是	-

# OnSocketCloseCallbackResult 的属性值

名称	类型	必备	默认值	描述
code	number	是	-	一个数字值表示关闭连接的状态号，表示连接被关闭的原因。
reason	string	是	-	一个可读的字符串，表示连接被关闭的原因。

# OnSocketCloseCallbackResult 兼容性

	Android	iOS	web
code	3.9	4.11	-
reason	3.9	4.11	-

# onSocketClose 兼容性

Android	iOS	web
3.9	4.11	4.0

# 参见

参见uni-app相关文档

相关 Bug

# 示例

hello uni-app x

Template

Script

<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>
    </view>
  </view>
</template>



<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: 40px 0px;
    text-align: center;
    font-size: 14px;
    line-height: 24px;
    color: #666666;
  }
</style>

# 通用类型

# GeneralCallbackResult

名称	类型	必备	默认值	描述
errMsg	string	是	-	错误信息

运营产品

uni-AD uni统计 uni发行 uni安全专题

开发者服务

问答社区开发者后台

技术文档

uni-app文档 uniCloud文档原生开发者支持文档 HBuilder文档

生态服务

插件市场 OAuth用户开放平台

关于我们： DCloud官网案例需求墙许可协议加入我们赞助我们

联系我们：商务合作：bd@dcloud.io 广告合作：uniad@dcloud.io

DCloud.io 数字天堂（北京）网络技术有限公司是

HTML5中国产业联盟发起单位

京公网安备：11010802035340号

国家信息安全等级保护三级，证书编号：11010813802-20001

# uni.connectSocket(options)

# 参数

# ConnectSocketSuccess 的属性值

# ConnectSocketFail 的属性值

# ConnectSocketOptions 兼容性

# 返回值

# SocketTask 的方法

# send(options)

# 参数

# SendSocketMessageFail 的属性值

# SendSocketMessageOptions 兼容性

# send 兼容性

# 参见

# close(options)

# 参数

# CloseSocketOptions 兼容性

# close 兼容性

# 参见

# onOpen(callback)

# 参数

# OnSocketOpenCallbackResult 兼容性

# onOpen 兼容性

# 参见

# onClose(callback)

# 参数

# onClose 兼容性

# 参见

# onError(callback)

# 参数

# onError 兼容性

# 参见

# onMessage(callback)

# 参数

# OnSocketMessageCallbackResult 的属性值

# OnSocketMessageCallbackResult 兼容性

# onMessage 兼容性

# 参见

# connectSocket 兼容性

# 参见

# uni.onSocketOpen(options)

# 参数

# onSocketOpen 兼容性

# 参见

# uni.onSocketError(callback)

# 参数

# OnSocketErrorCallbackResult 的属性值

# onSocketError 兼容性

# 参见

# uni.sendSocketMessage(options)

# 参数

# SendSocketMessageFail 的属性值

# SendSocketMessageOptions 兼容性

# sendSocketMessage 兼容性

# 参见

# 注意事项

# uni.onSocketMessage(callback)

# 参数

# OnSocketMessageCallbackResult 的属性值

# OnSocketMessageCallbackResult 兼容性

# onSocketMessage 兼容性

# 参见

# uni.closeSocket(options)

# 参数

# CloseSocketOptions 兼容性

# closeSocket 兼容性

# 参见

# uni.onSocketClose(callback)

# 参数

# OnSocketCloseCallbackResult 的属性值

# OnSocketCloseCallbackResult 兼容性

# onSocketClose 兼容性

# 参见

# 示例

# 通用类型

# GeneralCallbackResult

本页导读