uni.connectSocket(options)

创建一个 WebSocket 连接。

connectSocket 兼容性

Web	Android	iOS
4.0	3.9	4.11

参数

名称	类型	必填	默认值	兼容性	描述
options	ConnectSocketOptions	是	-	-	-
名称 类型 必备 默认值 兼容性 描述 url string 是 - Web Android iOS - 3.9 4.11 开发者服务器接口地址 header UTSJSONObject 否 null Web Android iOS - 3.9 4.11 HTTP 请求 Header，header 中不能设置 Referer protocols Array<string> 否 null Web Android iOS - 3.9 4.11 子协议数组 success (result: ConnectSocketSuccess) => void 否 null - 接口调用成功的回调函数 fail (result: ConnectSocketFail) => void 否 null - 接口调用失败的回调函数 complete (result: any) => void 否 null - 接口调用结束的回调函数（调用成功、失败都会执行）

ConnectSocketSuccess 的属性值

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

ConnectSocketFail 的属性值

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

返回值

类型
SocketTask

SocketTask 的方法

send(options: SendSocketMessageOptions): void;

通过 WebSocket 连接发送数据

send 兼容性

Web	Android	iOS
4.0	3.9	4.11

参数

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

SendSocketMessageFail 的属性值

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

close(options: CloseSocketOptions): void;

关闭 WebSocket 连接

close 兼容性

Web	Android	iOS
4.0	3.9	4.11

参数

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

onOpen(callback: (result: OnSocketOpenCallbackResult) => void): void;

监听 WebSocket 连接打开事件

onOpen 兼容性

Web	Android	iOS
4.0	3.9	4.11

参数

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

OnSocketOpenCallbackResult 的属性值

名称	类型	必备	默认值	兼容性	描述
header	any	是	-	Web Android iOS - 3.9 4.11	连接成功的 HTTP 响应 Header

onClose(callback: (result: any) => void): void;

监听 WebSocket 连接关闭事件

onClose 兼容性

Web	Android	iOS
4.0	3.9	4.11

参数

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

onError(callback: (result: GeneralCallbackResult) => void): void;

监听 WebSocket 错误

onError 兼容性

Web	Android	iOS
4.0	3.9	4.11

参数

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

onMessage(callback: (result: OnSocketMessageCallbackResult) => void): void;

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

onMessage 兼容性

Web	Android	iOS
4.0	3.9	4.11

参数

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

OnSocketMessageCallbackResult 的属性值

名称	类型	必备	默认值	兼容性	描述
data	any	是	-	Web Android iOS - 3.9 4.11	服务器返回的消息

参见

• 相关 Bug
• 参见uni-app相关文档
• 微信小程序文档
• 支付宝小程序文档
• 百度小程序文档
• 抖音小程序文档
• 飞书小程序文档
• 钉钉小程序文档
• QQ小程序文档
• 快手小程序文档
• 京东小程序文档
• 华为快应用文档
• 360小程序文档

uni.onSocketOpen(options)

监听WebSocket连接打开事件。

onSocketOpen 兼容性

Web	Android	iOS
4.0	3.9	4.11

参数

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

参见

• 相关 Bug
• 参见uni-app相关文档
• 微信小程序文档
• 支付宝小程序文档
• 百度小程序文档
• 抖音小程序文档
• 飞书小程序文档
• 钉钉小程序文档
• QQ小程序文档
• 快手小程序文档
• 京东小程序文档
• 华为快应用文档
• 360小程序文档

uni.onSocketError(callback)

监听WebSocket错误。

onSocketError 兼容性

Web	Android	iOS
4.0	3.9	4.11

参数

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

OnSocketErrorCallbackResult 的属性值

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

参见

• 相关 Bug
• 参见uni-app相关文档
• 微信小程序文档
• 支付宝小程序文档
• 百度小程序文档
• 抖音小程序文档
• 飞书小程序文档
• 钉钉小程序文档
• QQ小程序文档
• 快手小程序文档
• 京东小程序文档
• 华为快应用文档
• 360小程序文档

uni.sendSocketMessage(options)

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

sendSocketMessage 兼容性

Web	Android	iOS
4.0	3.9	4.11

参数

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

SendSocketMessageFail 的属性值

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

参见

• 相关 Bug
• 参见uni-app相关文档
• 微信小程序文档
• 支付宝小程序文档
• 百度小程序文档
• 抖音小程序文档
• 飞书小程序文档
• 钉钉小程序文档
• QQ小程序文档
• 快手小程序文档
• 京东小程序文档
• 华为快应用文档
• 360小程序文档

注意事项

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

uni.onSocketMessage(callback)

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

onSocketMessage 兼容性

Web	Android	iOS
4.0	3.9	4.11

参数

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

OnSocketMessageCallbackResult 的属性值

名称	类型	必备	默认值	兼容性	描述
data	any	是	-	Web Android iOS - 3.9 4.11	服务器返回的消息

参见

• 相关 Bug
• 参见uni-app相关文档
• 微信小程序文档
• 支付宝小程序文档
• 百度小程序文档
• 抖音小程序文档
• 飞书小程序文档
• 钉钉小程序文档
• QQ小程序文档
• 快手小程序文档
• 京东小程序文档
• 华为快应用文档
• 360小程序文档

uni.closeSocket(options)

关闭 WebSocket 连接。

closeSocket 兼容性

Web	Android	iOS
4.0	3.9	4.11

参数

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

参见

• 相关 Bug
• 参见uni-app相关文档
• 微信小程序文档
• 支付宝小程序文档
• 百度小程序文档
• 抖音小程序文档
• 飞书小程序文档
• 钉钉小程序文档
• QQ小程序文档
• 快手小程序文档
• 京东小程序文档
• 华为快应用文档
• 360小程序文档

uni.onSocketClose(callback)

监听WebSocket关闭。

onSocketClose 兼容性

Web	Android	iOS
4.0	3.9	4.11

参数

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

OnSocketCloseCallbackResult 的属性值

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

参见

• 相关 Bug
• 参见uni-app相关文档
• 微信小程序文档
• 支付宝小程序文档
• 百度小程序文档
• 抖音小程序文档
• 飞书小程序文档
• 钉钉小程序文档
• QQ小程序文档
• 快手小程序文档
• 京东小程序文档
• 华为快应用文档
• 360小程序文档

示例

hello uni-app x

扫码体验（手机浏览器跳转到App直达页）

扫码体验

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>
      <button class="uni-btn-v" type="primary" @click="goSocketTask">
        跳转 socketTask 示例
      </button>
    </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	是	-	-	错误信息