add unicloud websocket.md

docs/websocket.md

+# WebSocket
+
+> 仅支付宝云支持
+
+很多情况下需要实时进行网络互动，例如游戏、通信、金融交易和其他高吞吐量活动。
+
+WebSocket 是一种协议，可通过单个 TCP 连接在网络客户端与网络服务器之间提供全双工通信通道。WebSocket 协议使用 HTTP 协议在客户端与服务器之间建立连。
+
+## WebSocket 事件
+>
+> WebSocket 支持在云函数与云对象中使用。
+
+### connection
+>
+> 当有客户端进行连接时触发
+
+**云函数实现**
+
+```javascript
+exports.onWebsocketConnection = function (event, context) {
+    console.log("onWebsocketConnection", event, context)
+}
+```
+
+**云对象实现**
+
+```javascript
+module.exports = {
+    _onWebsocketConnection: function (event) {
+        console.log("onWebsocketConnection", event)
+    }
+}
+```
+
+**入参参数**
+
+event
+
+|参数|类型|说明|
+|---|---|---|
+|connectionId|`String`|连接ID|
+|query|`Object`|请求时的query参数|
+
+context
+
+云函数 context [参考](https://doc.dcloud.net.cn/uniCloud/cf-callfunction.html#context)
+
+### message
+>
+> 接收到客户端消息时触发
+
+**云函数实现**
+
+```javascript
+exports.onWebsocketMessage = function (event, context) {
+    console.log("onWebsocketMessage", event, context)
+}
+```
+
+**云对象实现**
+
+```javascript
+module.exports = {
+    _onWebsocketMessage: function (event) {
+        console.log("onWebsocketMessage", event)
+    }
+}
+```
+
+**入参参数**
+
+**event**
+
+|参数|类型|说明|
+|---|---|---|
+|connectionId|`String`|连接ID|
+|payload|`String` `Buffer`|消息内容|
+
+**context**
+
+云函数 context [参考](https://doc.dcloud.net.cn/uniCloud/cf-callfunction.html#context)
+
+### disConnection
+>
+> 连接断开时触发
+
+**云函数实现**
+
+```javascript
+exports.onWebsocketDisConnection = function (event, context) {
+    console.log("onWebsocketDisConnection", event, context)
+}
+```
+
+**云对象实现**
+
+```javascript
+module.exports = {
+    _onWebsocketDisConnection: function (event) {
+        console.log("onWebsocketDisConnection", event)
+    }
+}
+```
+
+**入参参数**
+
+**event**
+
+|参数|类型|说明|
+|---|---|---|
+|connectionId|`String`|连接ID|
+
+**context**
+
+云函数 context [参考](https://doc.dcloud.net.cn/uniCloud/cf-callfunction.html#context)
+
+### error
+>
+> 触发其他事件时失败后触发
+
+**云函数实现**
+
+```javascript
+exports.onWebsocketError = function (event, context) {
+    console.log("onWebsocketError", event, context)
+}
+```
+
+**云对象实现**
+
+```javascript
+module.exports = {
+    _onWebsocketError: function (event) {
+        console.log("onWebsocketError", event)
+    }
+}
+```
+
+**入参参数**
+
+**event**
+
+|参数|类型|说明|
+|---|---|---|
+|connectionId|`String`|连接ID|
+|errorMessage|`String`|错误信息|
+
+**context**
+
+云函数 context [参考](https://doc.dcloud.net.cn/uniCloud/cf-callfunction.html#context)
+
+## 云函数 uniCloud API
+
+### uniCloud.ws.send
+>
+> 从云函数/云对象中像客户端发送消息
+
+```javascript
+await uniCloud.ws.send(connectionId, sendData)
+```
+
+**参数说明**
+
+|参数|类型|说明|
+|---|---|---|
+|connectionId|`String` `Array`|客户端连接ID, 支持批量向客户端发送消息|
+|sendData|`String` `Object` `Buffer`|发送给客户端的消息内容|
+
+**示例**
+
+```javascript
+// 以云函数为例
+
+exports.onWebsocketMessage = async function (event) {
+    const { connectionId, payload } = event
+
+    // 发送给单个客户端
+    await uniCloud.ws.send(connectionId, `receive:${payload}`)
+
+    // 发送给多个客户端
+    await uniCloud.ws.send([connectionId1, connectionId2, ...], `receive:${payload}`)
+
+    // 发送给客户端对象数据
+    await uniCloud.ws.send(connectionId, {
+        receive: payload
+    })
+
+    // 发送给客户端二进制数据
+    await uniCloud.ws.send(connectionId, Buffer.from(`receive:${payload}`))
+}
+
+```
+
+### uniCloud.ws.close
+>
+> 在云函数/云对象中关闭连接
+
+```javascript
+await uniCloud.ws.close(connectionId)
+```
+
+**参数说明**
+
+|参数|类型|说明|
+|---|---|---|
+|connectionId|`String` `Array`|客户端连接ID, 支持批量关闭客户端连接|
+
+**示例**
+
+```javascript
+// 以云函数为例
+
+exports.onWebsocketMessage = async function (event) {
+    const { connectionId, payload } = event
+
+    // 关闭单个客户端连接
+    await uniCloud.ws.close(connectionId)
+
+    // 批量关闭客户端连接
+    await uniCloud.ws.close([connectionId1, connectionId2, ...])
+}
+
+```
+
+### uniCloud.ws.signedURL
+>
+> 在云函数/云对象中生成WebSocket连接地址
+
+在客户端没有使用 uniCloud SDK 时，可以通过 URL 化在云端生成 WebSocket 连接地址。
+
+```javascript
+await uniCloud.ws.signedURL(name, query)
+```
+
+**参数说明**
+
+|参数|类型|说明|
+|---|---|---|
+|name|`String`|WebSocket云函数/云对象名称|
+|query|`Object`|建立连接时需要传递的参数, 仅在 `connection` 事件中接收到|
+
+**返回值**
+
+WebSocket 连接地址
+
+**示例**
+
+```javascript
+await uniCloud.ws.signedURL("exampleWebSocket", {
+    key: "val"
+})
+```
+
+## 客户端 uniCloud API
+
+### uniCloud.connectWebSocket
+
+快速连接 WebSocket 服务
+
+```javascript
+uniCloud.connectWebSocket({
+    name: "exampleWebSocket",
+    query: {}
+})
+```
+
+**参数说明**
+
+|参数|类型|说明|
+|---|---|---|
+|name|`String`|WebSocket云函数/云对象名称|
+|query|`Object`|建立连接时需要传递的参数, 仅在 `connection` 事件中接收到|
+
+**返回值**
+
+[SocketTask](https://uniapp.dcloud.net.cn/api/request/socket-task.html)
+
+**示例**
+
+```javascript
+const exampleWebSocket = uniCloud.connectWebSocket({
+    name: "exampleWebSocket",
+    query: {
+        key: "val"
+    }
+})
+
+// 连接成功时触发
+exampleWebSocket.onOpen(event => {
+    console.log("WebSocket:open", event)
+})
+
+// 收到数据时触发
+exampleWebSocket.onMessage(event => {
+    console.log("WebSocket:message", event.data)
+})
+
+// 连接被关闭时触发
+exampleWebSocket.onClose(event) => {
+    console.log("WebSocket:close", event)
+})
+
+// 连接因错误而关闭时触发
+exampleWebSocket.onError(event => {
+    console.log("WebSocket:error", event)
+})
+
+```