{"id":13654370,"url":"https://github.com/tencentyun/wafer-client-sdk","last_synced_at":"2025-12-12T03:03:53.225Z","repository":{"id":58225730,"uuid":"72420519","full_name":"tencentyun/wafer-client-sdk","owner":"tencentyun","description":"Wafer - 快速构建具备弹性能力的微信小程序","archived":false,"fork":false,"pushed_at":"2018-05-28T12:42:31.000Z","size":85,"stargazers_count":338,"open_issues_count":8,"forks_count":86,"subscribers_count":55,"default_branch":"master","last_synced_at":"2024-10-09T20:32:37.779Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://github.com/tencentyun/wafer","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tencentyun.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-10-31T09:12:18.000Z","updated_at":"2024-07-12T07:50:43.000Z","dependencies_parsed_at":"2022-08-31T03:24:12.312Z","dependency_job_id":null,"html_url":"https://github.com/tencentyun/wafer-client-sdk","commit_stats":null,"previous_names":["tencentyun/weapp-client-sdk"],"tags_count":32,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tencentyun%2Fwafer-client-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tencentyun%2Fwafer-client-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tencentyun%2Fwafer-client-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tencentyun%2Fwafer-client-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tencentyun","download_url":"https://codeload.github.com/tencentyun/wafer-client-sdk/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247393551,"owners_count":20931811,"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":"2024-08-02T03:00:30.806Z","updated_at":"2025-12-12T03:03:53.145Z","avatar_url":"https://github.com/tencentyun.png","language":"JavaScript","funding_links":[],"categories":["Uncategorized","JavaScript"],"sub_categories":["Uncategorized"],"readme":"# 微信小程序客户端腾讯云增强 SDK\n\n[![Build Status](https://travis-ci.org/tencentyun/wafer-client-sdk.svg?branch=master)](https://travis-ci.org/tencentyun/wafer-client-sdk)\n[![Coverage Status](https://coveralls.io/repos/github/tencentyun/wafer-client-sdk/badge.svg?branch=master)](https://coveralls.io/github/tencentyun/wafer-client-sdk?branch=master)\n[![License](https://img.shields.io/github/license/tencentyun/wafer-client-sdk.svg)](LICENSE)\n\n本 项目是 [Wafer](https://github.com/tencentyun/wafer-solution) 的组成部分，为小程序客户端开发提供 SDK 支持会话服务和信道服务。\n\n## SDK 获取与安装\n\n解决方案[客户端 Demo](https://github.com/tencentyun/wafer-client-demo) 已经集成并使用最新版的 SDK，需要快速了解的可以从 Demo 开始。\n\n如果需要单独开始，本 SDK 已经发布为 bower 模块，可以直接安装到小程序目录中。\n\n```sh\nnpm install -g bower\nbower install wafer-client-sdk\n```\n\n安装之后，就可以使用 `require` 引用 SDK 模块：\n\n```js\nvar qcloud = require('./bower_components/wafer-client-sdk/index.js');\n```\n\n## 会话服务\n\n[会话服务](https://github.com/tencentyun/wafer-solution/wiki/%E4%BC%9A%E8%AF%9D%E6%9C%8D%E5%8A%A1)让小程序拥有会话管理能力。\n\n### 登录\n\n登录可以在小程序和服务器之间建立会话，服务器由此可以获取到用户的标识和信息。\n\n```js\nvar qcloud = require('./bower_components/qcloud-weapp-client-sdk/index.js');\n\n// 设置登录地址\nqcloud.setLoginUrl('https://199447.qcloud.la/login');\nqcloud.login({\n    success: function (userInfo) {\n        console.log('登录成功', userInfo);\n    },\n    fail: function (err) {\n        console.log('登录失败', err);\n    }\n});\n```\n本 SDK 需要配合云端 SDK 才能提供完整会话服务。通过 [setLoginUrl](#setLoginUrl) 设置登录地址，云服务器在该地址上使用云端 SDK 处理登录请求。\n\n\u003e `setLoginUrl` 方法设置登录地址之后会一直有效，因此你可以在微信小程序启动时设置。\n\n登录成功后，可以获取到当前微信用户的基本信息。\n\n### 请求\n\n如果希望小程序的网络请求包含会话，登录之后使用 [request](#request) 方法进行网络请求即可。\n\n```js\nqcloud.request({\n    url: 'http://199447.qcloud.la/user',\n    success: function (response) {\n        console.log(response);\n    },\n    fail: function (err) {\n        console.log(err);\n    }\n});\n```\n\n如果调用 `request` 之前还没有登录，则请求不会带有会话。`request` 方法也支持 `login` 参数支持在请求之前自动登录。\n\n```js\n// 使用 login 参数之前，需要设置登录地址\nqcloud.setLoginUrl('https://199447.qcloud.la/login');\nqcloud.request({\n    login: true,\n    url: 'http://199447.qcloud.la/user',\n    success: function (response) {\n        console.log(response);\n    },\n    fail: function (err) {\n        console.log(err);\n    }\n});\n```\n\n关于会话服务详细技术说明，请参考 [Wiki](https://github.com/tencentyun/wafer-solution/wiki/%E4%BC%9A%E8%AF%9D%E6%9C%8D%E5%8A%A1)。\n\n## 信道服务\n\n[信道服务](https://github.com/tencentyun/wafer-solution/wiki/%E4%BF%A1%E9%81%93%E6%9C%8D%E5%8A%A1)小程序支持利用腾讯云的信道资源使用 WebSocket 服务。\n\n```js\n// 创建信道，需要给定后台服务地址\nvar tunnel = this.tunnel = new qcloud.Tunnel('https://199447.qcloud.la/tunnel');\n\n// 监听信道内置消息，包括 connect/close/reconnecting/reconnect/error\ntunnel.on('connect', () =\u003e console.log('WebSocket 信道已连接'));\ntunnel.on('close', () =\u003e console.log('WebSocket 信道已断开'));\ntunnel.on('reconnecting', () =\u003e console.log('WebSocket 信道正在重连...'));\ntunnel.on('reconnect', () =\u003e console.log('WebSocket 信道重连成功'));\ntunnel.on('error', error =\u003e console.error('信道发生错误：', error));\n\n// 监听自定义消息（服务器进行推送）\ntunnel.on('speak', speak =\u003e console.log('收到 speak 消息：', speak));\n\n// 打开信道\ntunnel.open();\n// 发送消息\ntunnel.emit('speak', { word: \"hello\", who: { nickName: \"techird\" }});\n// 关闭信道\ntunnel.close();\n```\n\n信道服务同样需要业务服务器配合云端 SDK 支持，构造信道实例的时候需要提供业务服务器提供的信道服务地址。通过监听信道消息以及自定义消息来通过信道实现业务。\n\n关于信道使用的更完整实例，建议参考客户端 Demo 中的[三木聊天室应用源码](https://github.com/tencentyun/wafer-client-demo/blob/master/pages/chat/chat.js)。\n\n关于信道服务详细技术说明，请参考 [Wiki](https://github.com/tencentyun/wafer-solution/wiki/%E4%BF%A1%E9%81%93%E6%9C%8D%E5%8A%A1)。\n\n## API\n\n\n### setLoginUrl\n设置会话服务登录地址。\n\n#### 语法\n```js\nqcloud.setLoginUrl(loginUrl);\n```\n\n#### 参数\n|参数         |类型           |说明\n|-------------|---------------|--------------\n|loginUrl     |string         |会话服务登录地址\n\n### login\n登录，建立微信小程序会话。\n\n#### 语法\n```js\nqcloud.login(options);\n```\n\n#### 参数\n|参数         |类型           |说明\n|-------------|---------------|--------------\n|options      |PlainObject    |会话服务登录地址\n|options.success | () =\u003e void | 登录成功的回调\n|options.fail    | (error) =\u003e void | 登录失败的回调\n\n\n### request\n进行带会话的请求。\n\n#### 语法\n```js\nqcloud.request(options);\n```\n\n#### 参数\n|参数         |类型           |说明\n|-------------|---------------|--------------\n|options      |PlainObject    | 会话服务登录地址\n|options.login | bool         | 是否自动登录以获取会话，默认为 false\n|options.url   | string       | 必填，要请求的地址\n|options.data  | string、object | 可选，提交到服务器的数据，会透传到 wx.request 方法中\n|options.header | PlainObject | 请求头设置，不允许设置 Referer\n|options.method | string      | 请求的方法，默认为 GET\n|options.success | (response) =\u003e void | 登录成功的回调。\u003cul\u003e\u003cli\u003e`response.statusCode`：请求返回的状态码\u003c/li\u003e\u003cli\u003e`response.data`：请求返回的数据\u003c/li\u003e\u003c/ul\u003e\n|options.fail | (error) =\u003e void | 登录失败的回调\n|options.complete | () =\u003e void | 登录完成后回调，无论成功还是失败\n\n### Tunnel\n\n表示一个信道。由于小程序的限制，同一时间只能有一个打开的信道。\n\n#### constructor\n\n##### 语法\n```js\nvar tunnel = new Tunnel(tunnelUrl);\n```\n\n#### 参数\n|参数         |类型           |说明\n|-------------|---------------|--------------\n|tunnelUrl    |String         | 会话服务登录地址\n\n\n#### on\n监听信道上的事件。信道上事件包括系统事件和服务器推送消息。\n\n##### 语法\n```js\ntunnel.on(type, listener);\n```\n\n##### 参数\n|参数         |类型           |说明\n|-------------|---------------|--------------\n|type         |string         | 监听的事件类型\n|listener     |(message?: any) =\u003e void | 监听器，具体类型的事件发生时调用监听器。如果是消息，则会有消息内容。\n\n##### 事件\n|事件         |说明\n|-------------|-------------------------------\n|connect      |信道连接成功后回调\n|close        |信道关闭后回调\n|reconnecting |信道发生重连时回调\n|reconnected  |信道重连成功后回调\n|error        |信道发生错误后回调\n|[message]    |信道服务器推送过来的消息类型，如果消息类型和上面内置的时间类型冲突，需要在监听的时候在消息类型前加 `@`\n|\\*           |监听所有事件和消息，监听器第一个参数接收到时间或消息类型 \n\n#### open\n打开信道，建立连接。由于小程序的限制，同一时间只能有一个打开的信道。\n\n##### 语法\n```js\ntunnel.open();\n```\n\n#### emit\n向信道推送消息。\n\n##### 语法\n```js\ntunnel.emit(type, content);\n```\n\n##### 参数\n|参数         |类型           |说明\n|-------------|---------------|--------------\n|type         |string         | 要推送的消息的类型\n|content      |any            | 要推送的消息的内容\n\n#### close\n关闭信道\n\n##### 语法\n```js\ntunnel.close();\n```\n\n## LICENSE\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftencentyun%2Fwafer-client-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftencentyun%2Fwafer-client-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftencentyun%2Fwafer-client-sdk/lists"}