开发文档
WebSocket更新时间：2025-12-17 15:55:04
基础信息说明
功能概述：创建WebSocket对象
| 项目 | 说明 |
| 版本要求 | 无 |
| 前提条件 | 目标 URL 可访问、网络权限已配置、运行环境支持 WebSocket（webview、cocos runtime和unity runtime均支持） |
| 使用限制 | URL 必须为 ws:// 或 wss:// 协议；wss:// 需有效证书 |
| 相关教程 | 参考 MDN: WebSocket |
参数说明
ws = new WebSocket(url, protocols)
| 属性名 | 类型 | 默认值（如有） | 必填 | 说明 |
| url | String | - | 是 | 请求 URL，必须为 ws:// 或 wss:// |
| protocols | String| String[] | - | 否 | 子协议或子协议数组，用于协商特定应用层协议 |
返回值说明
new WebSocket() 同步构造，返回连接对象；连接建立与关闭通过异步事件驱动。
| 属性名 | 类型 | 说明 |
| ws.url | String | 连接的 URL |
| ws.protocol | String | 服务器选择的子协议 |
| ws.extensions | String | 服务器选择的扩展（若有） |
| ws.readyState | Number | 当前连接状态 |
| ws.binaryType | String | 二进制数据类型：'blob' 或 'arraybuffer' |
| ws.bufferedAmount | Number | 尚未发送到服务器的字节数（队列中的待发送量） |
| ws.onopen | Function(Event event) | 连接成功事件回调 |
| ws.onmessage | Function(MessageEvent event) | 接收消息事件回调（event.data 为消息体） |
| ws.onerror | Function(Event event) | 错误事件回调 |
| ws.onclose | Function(CloseEvent event) | 连接关闭事件回调（含 code、reason、wasClean） |
WebSocket 方法说明
| 方法名 | 类型 | 说明 |
| ws.send | (data: string| ArrayBufferLike | Blob | ArrayBufferView): void | 向服务器发送数据；支持 string、Blob、ArrayBuffer、ArrayBufferView（如 Uint8Array、DataView）；不支持直接发送普通对象，需序列化为字符串或转换为二进制；binaryType 仅影响接收类型；大数据建议分片并关注 bufferedAmount |
| ws.close | (code?: number, reason?: string): void | 关闭连接；未指定 code 时通常使用 1000（Normal Closure）。1005 为保留码，仅用于表示未接收状态码，不用于发送；reason 为 UTF-8 字符串（≤ 123 字节） |
回调结果说明
- 触发时机：
- onopen：握手成功并建立连接后触发（readyState = 1）。
- onmessage：收到服务器消息时触发，event.data 为文本或二进制。
- onerror：连接或传输过程中发生错误时触发。
- onclose：连接关闭时触发，提供关闭细节。
回调成功
onopen 成功形态
| 属性名 | 类型 | 说明 |
| event | Event | 事件对象；可通过 event.target === ws 获取实例 |
onmessage 成功形态
| 属性名 | 类型 | 说明 |
| event | MessageEvent | 消息事件；event.data 为字符串、Blob 或包含二进制的 ArrayBuffer/TypedArray |
onclose 关闭形态
| 属性名 | 类型 | 说明 |
| code | Number | 服务器或客户端的关闭状态码 |
| reason | String | 关闭原因（UTF-8，≤ 123 字节） |
| wasClean | Boolean | 是否正常关闭 |
回调失败
onerror 失败形态
| 属性名 | 类型 | 说明 |
| event | Event | 错误事件；错误细节依赖运行环境与网络栈，通常需结合日志排查 |
示例代码
// 建立连接并发送/接收消息（本地 Echo 服务）
const ws = new WebSocket('ws://127.0.0.1:8081')
ws.binaryType = 'arraybuffer'
ws.onopen = function (event) {
console.log('WebSocket opened:', ws.protocol, ws.extensions)
ws.send('Hello server!')
}
ws.onmessage = function (event) {
console.log('Message received:', event.data)
}
ws.onerror = function (event) {
console.error('WebSocket error:', event)
}
ws.onclose = function (event) {
console.log('WebSocket closed:', event.code, event.reason, event.wasClean)
}
// 关闭连接（可选）
// ws.close(1000, 'normal close')注意事项
- 协议与证书：wss:// 需要有效证书与正确的域名配置；自签证书可能导致连接失败。
- 流控：bufferedAmount 表示尚未发送的字节数；若过大，需考虑节流与拆包策略。
上一篇:键盘
下一篇:数据请求
文档内容是否有帮助？
有帮助
无帮助