{"id":26980175,"url":"https://github.com/clovu/uni.socket","last_synced_at":"2025-04-03T14:32:28.841Z","repository":{"id":154891745,"uuid":"324903505","full_name":"clovu/uni.socket","owner":"clovu","description":"uni.socket plug-in is developed based on uniapp...","archived":false,"fork":false,"pushed_at":"2021-08-24T06:08:24.000Z","size":330,"stargazers_count":7,"open_issues_count":0,"forks_count":4,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-10T06:29:13.371Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/clovu.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-12-28T03:34:34.000Z","updated_at":"2021-10-09T08:54:04.000Z","dependencies_parsed_at":"2023-07-30T08:45:30.052Z","dependency_job_id":null,"html_url":"https://github.com/clovu/uni.socket","commit_stats":null,"previous_names":["youchuantong/uni.socket","clovu/uni.socket"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clovu%2Funi.socket","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clovu%2Funi.socket/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clovu%2Funi.socket/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clovu%2Funi.socket/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/clovu","download_url":"https://codeload.github.com/clovu/uni.socket/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247018216,"owners_count":20869974,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-04-03T14:30:21.687Z","updated_at":"2025-04-03T14:32:28.824Z","avatar_url":"https://github.com/clovu.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# uni.socket 插件API文档\n\n### 使用\n\n需引入并创建一个socket实例，创建完成后你将得到一个uni.socket对象\n\n```javascript\nimport UniSocket from \"utils/uni.socket.js\"\nconst socket = new UniSocket({\n\turl: \"wss://127.0.0.1/\"\n});\n```\n\n\n\n### 参数\n\n| 参数           | 描述                                                         |\n| -------------- | ------------------------------------------------------------ |\n| url            | 服务器地址                                                   |\n| reconnection   | 发送错误时是否进行重连，默认`true`                           |\n| buffer         | 是否建立缓存池，当发送消息失败时会吧消息保存到缓存池等待下次发送 |\n| heartRate      | 系统自动与将程序心跳发送至服务端，默认60000ms                |\n| heartRateType  | 设置心跳触发的事件，默认触发`HEARTBEAT`事件                  |\n| autoEmitBuffer | 是否自动发送缓存池中的数据，默认`false`                      |\n\n\n\n### 方法\n\n#### on\n\non方法是一个为uni.socket注册自定义事件的方法，该事件将通过你服务器传回的数据触发，因此，你服务器数据返回的格式必须遵守约定。\n\n```javascript\nsocket.on('event', Function(data){\n\t// .... 在此处理服务器发给你的邮件data          \n})\n```\n\n服务器返回的数据必须遵守该格式才能保证正常使用：\n\n`{type: 'event', data: {}}`\n\n`data`未必是Object格式，它可以是任意格式，但必须拥有`type`和`data`，`tyep`是服务器与你的约定，它将去使用你注册的事件驱动，也就是说，uni.socket是通过`type`字段来进行触发你自定义的事件驱动的。\n\n如果你的第三个参数为`true`，那么uni.socket则会检查该事件驱动是否已被注册，如果未被注册，则将它进行注册，默认`false`\n\n```javascript\nsocket.on('event', Function, true);\n```\n\n\n\n#### off\n\n撤销注册的事件驱动，在uni.socket中，强制每个页面退出、关闭时调用此方法，因为uni.socket无法处理移除页面存在时注册过的事件驱动从而导致的内存泄漏。\n\n```javascript\nsocket.off('event', handler);\n```\n\n此方法支持连续注销驱动。\n\n```javascript\nsocket.off('event', handler1)('event', handler2)('event', handler3);\n```\n\n\n\n例如：\n\n```js\nexport default {\n  methods: {\n    hello() {\n      ...\n    }\n    },\n    onLoad() {\n      socket.on('hello', this.hello);\n    },\n    onUnload() {\n      // 监听页面卸载\n      // 页面退出，撤销hello，释放资源\n      socket.off('hello', this.hello);\n    }\n  }\n```\n\n\n\n#### removeEventByName\n\n移除你自定义的事件，因为是危险操作，需要开发者进行二次提交\n\n**移除自定义事件包括任何给这个事件注册的驱动**\n\n```javascript\nsocket.removeEventByName('event').then(commit =\u003e {\n  commit();\n});\n```\n\n\n\n#### addBuffer\n\n给缓存池添加数据\n\n```javascript\nsocket.addBuffer({type: 'event', data: {}})\n```\n\n\n\n#### getBuffer\n\n获取缓存池\n\n```javascript\nconst buffer = await socket.getBuffer();\n// or\nsocket.getBuffer().then(buffer =\u003e {\n\t//  ...处理你的缓存池\n});\n```\n\n\n\n#### getState\n\n获取连接状态0 表示连接中，1表示连接成功，2表示重连中，3表示失败\n\n```javascript\nconst state = await socket.getState();\n// or\nsocket.getState().then(state =\u003e {\n\t//  ...处理你状态\n});\n```\n\n\n\n#### killApp\n\n结束心跳，心跳结束后，uni.socket除了心跳发送，在下一次发送心跳时间内，其它功能正常使用，需要后端进行处理\n\n```javascript\nsocket.killApp();\n```\n\n\n\n#### close\n\n关闭与服务器的连接，注意，它不会触发`error`事件\n\n```javascript\nsocket.close();\n```\n\n\n\n#### emit\n\n给服务器发送消息\n\n```javascript\nsocket.emit('event', {msg: \"hello world\"});\n```\n\n\n\n### 关于心跳\n\nuni.socket需向服务器定时发送一次心跳，其触发的事件为`HEARTBEAT`，默认心率为60000ms，服务器可根据该事件进行处理，可修改配置进行修改触发事件`heartRateType`：\n\n```javascript\nnew UniSocket({\n\turl: \"wss://127.0.0.1/\",\n  heartRateType: \"Your event name...\"\n});\n```\n\n\n\n\u003e 关于心跳会触发两次的问题，因为uni.socket发送的时候会触发一次心跳事件，而接收到服务端心跳的时候也会触发一次心跳事件。\n\n### 系统事件\n\n虽然是系统事件，但它和你自定义的事件并无区别，只是uni.socket赋予了它们特别的使命\n\n| 事件              | 描述                                          | 返回值描述                   |\n| ----------------- | --------------------------------------------- | ---------------------------- |\n| error             | 错误事件，当socket连接发生错误时会触发        | 错误描述                     |\n| reconnectionerror | 重连过程中发生的错误                          | 错误描述                     |\n| connectioned      | 连接成功时触发                                | 无                           |\n| \\*                | 服务器给客户端发送任何消息时触发              | 客户端消息                   |\n| \\*\\*              | 后端返回的数据格式违背与UniSocket的约定时触发 | 客户端消息                   |\n| HEARTBEAT         | 每次向服务端发送一次心跳时触发                | uni.socket给你返回的垃圾消息 |\n\n\n\n\n# 使用demo\n\n若你需要查看示例，你需要启动client下的uniapp项目。项目主在main.js中使用uni.socket连接服务器，使用示例在`src/pages/index/index.vue`中\n\n\n你如果没有测试服务器代码，你也可以使用node启动server文件夹下的app.js来启动一个WebSocket服务器，它监听了1200端口\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclovu%2Funi.socket","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fclovu%2Funi.socket","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclovu%2Funi.socket/lists"}