介绍
钉钉H5微应用接口对接,主要涉及以下几个方面:
- 模块Config
- 工作通知
- 网页登录
- 网页前端JSSDK
- 钉钉网页布局
- 钉钉API调用
1. 模块Config
CabloyJS提供了两种方式来配置Config参数:
-
后台管理页面
:页面路径为系统应用/基础管理/认证管理
-
项目配置
:直接在项目配置文件中覆盖模块Config中的参数,从而配置与钉钉有关的信息
关于如何
覆盖模块Config
,请参见:Config
a-dingtalk/backend/src/config/config.js
- 1 // account.dingtalk
- 2 config.account.dingtalk = {
- 3 client: 'dingtalk',
- 4 // scenes
- 5 scenes: {
- 6 selfBuilt: {
- 7 title: 'AuthSelfBuiltApp',
- 8 agentId: '',
- 9 appKey: '',
- 10 appSecret: '',
- 11 message: {
- 12 token: appInfo.name,
- 13 encodingAESKey: '',
- 14 },
- 15 jssdk: {
- 16 type: 0,
- 17 jsApiList,
- 18 },
- 19 },
- 20 },
- 21 };
名称 | 说明 |
---|---|
scenes | 配置所有钉钉应用的参数,包括:钉钉内置应用、第三方应用,以及自建应用。如需访问其他应用提供的API接口,直接在scenes 添加新的配置即可 |
scenes.selfBuilt | 自建应用(H5微应用) |
2. 工作通知
模块a-dingtalk
已经对工作通知的推送机制进行了封装。比如,要向某个用户发送工作通知的消息,可以这样操作:
src/suite-vendor/test-party/modules/test-dingtalk/backend/src/service/test.js
- 1async sendAppMessage({ message, user }) {
- 2 const msg = {
- 3 msgtype: 'text',
- 4 text: {
- 5 content: message.text,
- 6 },
- 7 };
- 8 const content = {
- 9 userIds: [ user.id ],
- 10 data: { msg },
- 11 };
- 12 await this.ctx.bean.io.pushDirect({
- 13 content,
- 14 channel: { module: 'a-dingtalk', name: 'app' },
- 15 });
- 16}
名称 | 说明 |
---|---|
content.userIds | 推送的目标用户 |
content.msg | 推送的消息内容,参考发送工作通知 |
channel | 内置的推送通道 |
3. 网页登录
模块a-dingtalk
自动判断,如果当前网页处于钉钉app
中,会自动进行免登处理,然后自动进行用户认证
4. 网页前端JSSDK
模块a-dingtalk
提供了便捷的组件,可以自动注入钉钉JSSDK,并且自动进行config配置
测试模块test-dingtalk
演示了如何调用钉钉的二维码扫描操作:
src/suite-vendor/test-party/modules/test-dingtalk/front/src/pages/test/index.vue
- 1 created() {
- 2 const action = {
- 3 actionModule: 'a-dingtalk',
- 4 actionComponent: 'jssdk',
- 5 name: 'config',
- 6 };
- 7 this.$meta.util.performAction({ ctx: this, action }).then(res => {
- 8 this.dd = res && res.dd;
- 9 }).catch(e => {
- 10 this.$view.toast.show({ text: e.message });
- 11 });
- 12 },
- 13 methods: {
- 14 onPerformScanQRCode() {
- 15 this.dd.biz.util.scan({
- 16 type: 'all',
- 17 onSuccess: res => {
- 18 this.$view.toast.show({ text: res.text });
- 19 },
- 20 onFail: err => {
- 21 this.$view.toast.show({ text: err.message });
- 22 },
- 23 });
- 24 },
- 25 }
- 先通过
this.$meta.util.performAction
调用模块a-dingtalk
提供的组件,返回dd
对象 - 调用
dd
对象执行扫描二维码的钉钉接口
5. 钉钉网页布局
CabloyJS可以创建App应用
,一个App应用是菜单页面+主页+用户页面
组合。我么可以专门针对钉钉场景定义一个专属的App应用
测试模块test-dingtalk
演示了如何定制钉钉场景下的App应用:
-
App应用配置:
src/suite-vendor/test-party/modules/test-dingtalk/backend/src/config/static/app/appTest.js
-
App菜单页面配置:
src/suite-vendor/test-party/modules/test-dingtalk/backend/src/config/static/layout/layoutAppMenuTest.js
6. 钉钉API调用
模块a-dingtalk
提供了全局Bean组件dingtalk
,用于调用所有钉钉API,格式如下:
ctx.bean.dingtalk.app.{providerScene}
名称 | 说明 |
---|---|
providerScene | 场景名称,比如selfBuilt (自建应用) |
钉钉API基于
ali-sdk/node-dingtalk
。为了便于更灵活的添加新API,CabloyJS对主仓库发起了一个新分支,详细的API清单请参见:node-dingtalk
下面以JSSDK Config为例:
src/module-system/a-dingtalk/backend/src/service/jssdk.js
- 1async jsconfig({ url }) {
- 2 ...
- 3 // jsconfig
- 4 const res = await this.ctx.bean.dingtalk.app.selfBuilt.client.getJSApiConfig(url);
- 5}
7. 如何判断是否在钉钉
中
由于CabloyJS后端架构的普适性,我们有时候需要判断当前是否在钉钉中,从而做出相应的处理
7.1 通过中间件判断
可以通过中间件inDingtalk
来判断该api接口是否被钉钉
调用,如果不是则自动阻止后续逻辑的执行
src/suite-vendor/test-party/modules/test-dingtalk/backend/src/routes.js
- 1 { method: 'post', path: 'test/getMemberId', controller: test, middlewares: 'inDingtalk',
- 2 meta: {
- 3 inDingtalk: {
- 4 providerName: 'dingtalk',
- 5 providerScene: null,
- 6 },
- 7 },
- 8 },
名称 | 说明 |
---|---|
meta.inDingtalk | 中间件inDingtalk 的参数 |
providerName | 认证提供者名称,如果指定dingtalk ,表示该api只能被自建H5微应用 调用 |
providerScene | 如果认证提供者支持多个场景,这里可以指定场景名 |
7.2 通过代码判断
可以直接通过代码进行判断
- 1ctx.bean.dingtalk.util.in({ providerName, providerScene })
评论: