钉钉 JS-API
钉钉提供了丰富的JSAPI能力，例如原生弹框、设备信息、扫描等能力，宜搭开发者可以利用钉钉原生提供的API能力提供更好的用户体验。
caution
调用钉钉JS-API需要注意以下事项：
- 宜搭应用中，不保证 window.dd 存在 (目前仅手机端会引入一个旧版资源)，建议用户手动引入;
- 宜搭应用中，即使不配置 dd.config 进行 JSAPI 鉴权操作，仍可调用需要鉴权后才能使用的 API。请谨慎调用;
- 调用 JSAPI 时，需要的 corpId 参数可以从
const { corpId } = window.pageConfig || {};获取;
使用指南
步骤1：异步加载钉钉JSAPI资源
由于宜搭页面中不保证 window.dd一定存在，所以保险起见，用户需要在页面的didMount生命周期中手动加载钉钉的JSAPI脚本，如下所示：
实现代码如下所示：
export function didMount() {
const script = document.createElement('script');
script.src = 'https://g.alicdn.com/dingding/dingtalk-jsapi/2.10.3/dingtalk.open.js';
document.body.appendChild(script);
}
资源引入完成后，即可通过 window.dd 调用 JSAPI 中的相关功能。
步骤2：调用钉钉JSAPI
钉钉的JSAPI加载完成后，我们便可以在动作面板中通过window.dd调用钉钉的API进行相应的操作了，如下所示：
export function isDingTalk() {
return window.navigator && /dingtalk/i.test(window.navigator.userAgent)
}
export function dingAlert() {
if (window.dd && this.isDingTalk()) {
window.dd.device.notification.alert({
message: "测试",
title: "提示",//可传空
buttonName: "收到",
onSuccess: function () {
},
onFail: function (err) { }
});
}
}
钉钉端内的展示效果如下所示：
caution
由于很多钉钉JSAPI要求必须端内调用，因此在调用钉钉JSAPI时，需要提前先判断一下是否在钉钉端内，判断代码如下所示：
export function isDingTalk() {
return window.navigator && /dingtalk/i.test(window.navigator.userAgent)
}
用户可以访问官方提供的使用钉钉JSAPI来查看效果及具体实现。
API列表
容器
| 接口说明 | JSAPI名称 | 是否需要鉴权 | Android | IOS | PC |
|---|---|---|---|---|---|
| 获取容器版本号 | dd.version | 不需要 | 支持 | 支持 | 不支持 |
弹框
| 接口说明 | JSAPI名称 | 是否需要鉴权 | Android | IOS | PC |
|---|---|---|---|---|---|
| alert | device.notification.alert | 不需要 | 支持 | 支持 | 支持 |
| confirm | device.notification.confirm | 不需要 | 支持 | 支持 | 支持 |
| prompt | device.notification.prompt | 不需要 | 支持 | 支持 | 支持 |
| 手机震动 | device.notification.vibrate | 不需要 | 支持 | 支持 | 不支持 |
| toast | device.notification.toast | 不需要 | 支持 | 支持 | 支持 |
| actionsheet | device.notification.actionSheet | 不需要 | 支持 | 支持 | 支持 |
| 显示加载 | device.notification.showPreloader | 不需要 | 支持 | 支持 | 不支持 |
| 隐藏加载 | device.notification.hidePreloader | 不需要 | 支持 | 支持 | 不支持 |
| modal弹浮层 | device.notification.modal | 不需要 | 支持 | 支持 | 不支持 |
| extendModal | device.notification.extendModal | 不需要 | 支持 | 支持 | 不支持 |
| 多选组件 | biz.util.multiSelect | 不需要 | 支持 | 支持 | 不支持 |
摇一摇
| 接口说明 | JSAPI名称 | 是否需要鉴权 | Android | IOS | PC |
|---|---|---|---|---|---|
| 启动摇一摇 | device.accelerometer.watchShake | 不需要 | 支持 | 支持 | 不支持 |
| 停止摇一摇 | device.accelerometer.clearShake | 不需要 | 支持 | 支持 | 不支持 |
设备
| 接口说明 | JSAPI名称 | 是否需要鉴权 | Android | IOS | PC |
|---|---|---|---|---|---|
| 获取网络类型 | device.connection.getNetworkType | 不需要 | 支持 | 支持 | 不支持 |
| 获取wifi状态 | device.base.getWifiStatus | 不需要 | 支持 | 支持 | 不支持 |
| 获取手机基础信息 | device.base.getPhoneInfo | 不需要 | 支持 | 支持 | 不支持 |
| 获取uuid | device.base.getUUID | 需要 | 支持 | 支持 | 不支持 |
| 获取热点接入信息 | device.base.getInterface | 需要 | 支持 | 支持 | 不支持 |
| 读取NFC芯片内容 | device.nfc.nfcRead | 不需要 | 支持 | 不支持 | 不支持 |
| NFC数据写入 | device.nfc.nfcWrite | 需要 | 支持 | 不支持 | 不支持 |
| 打开iOS系统设置 | device.base.openSystemSetting | 不需要 | 不支持 | 支持 | 不支持 |
| 打开Android系统设置 | device.base.openSystemSetting | 不需要 | 支持 | 不支持 | 不支持 |
日期&月历
| 接口说明 | JSAPI名称 | 是否需要鉴权 | Android | IOS | PC |
|---|---|---|---|---|---|
| 日期选择器 | biz.util.datepicker | 不需要 | 支持 | 支持 | 不支持 |
| 时间选择器 | biz.util.timepicker | 不需要 | 支持 | 支持 | 不支持 |
| 日期及时间选择器 | biz.util.datetimepicker | 不需要 | 支持 | 支持 | 不支持 |
| 月历组件：选择某天 | biz.calendar.chooseOneDay | 不需要 | 支持 | 支持 | 不支持 |
| 月历组件：选择某时间 | biz.calendar.chooseDateTime | 不需要 | 支持 | 支持 | 不支持 |
| 月历组件：选择某天 | biz.calendar.chooseHalfDay | 不需要 | 支持 | 支持 | 不支持 |
| 月历组件：选择日期区间 | biz.calendar.chooseInterval | 不需要 | 支持 | 支持 | 不支持 |
导航栏
| 接口说明 | JSAPI名称 | 是否需要鉴权 | Android | IOS | PC |
|---|---|---|---|---|---|
| 设置导航栏颜色 | 拼接dd_nav_bgcolor参数 | 不需要 | 支持 | 支持 | 不支持 |
| 微应用页面支持横屏 | 拼接dd_orientation参数 | 不需要 | 支持 | 支持 | 不支持 |
| 设置左侧导航按钮文本 | biz.navigation.setLeft | 不需要 | 不支持 | 支持 | 支持 |
| PC端左侧按钮点击事件 | addEventListener | 不需要 | 不支持 | 不支持 | 支持 |
| PC端左侧按钮点击事件，移除监听回调函数 | removeEventListener | 不需要 | 不支持 | 不支持 | 支持 |
| 设置导航栏标题 | biz.navigation.setTitle | 不需要 | 支持 | 支持 | 支持 |
| 标题栏添加问号图标 | biz.navigation.setIcon | 不需要 | 支持 | 支持 | 不支持 |
| 返回上一级页面 | biz.navigation.goBack | 不需要 | 支持 | 支持 | 不支持 |
| 关闭当前页面 | biz.navigation.close | 不需要 | 支持 | 支持 | 不支持 |
| 替换页面 | biz.navigation.replace | 不需要 | 支持 | 支持 | 不支持 |
| 关闭页面 | biz.navigation.quit | 不需要 | 不支持 | 不支持 | 支持 |
UI控件
| 接口说明 | JSAPI名称 | 是否需要鉴权 | Android | IOS | PC |
|---|---|---|---|---|---|
| 输入框 | ui.input.plain | 不需要 | 支持 | 支持 | 不支持 |
| 设置顶部进度条颜色 | ui.progressBar.setColors | 不需要 | 支持 | 支持 | 不支持 |
| 启用下拉刷新 | ui.pullTorefresh.enable | 不需要 | 支持 | 支持 | 不支持 |
| 禁用下拉刷新 | ui.pullToRefresh.disable | 不需要 | 支持 | 支持 | 不支持 |
| 收起下拉刷新 | ui.pullToRefresh.stop | 不需要 | 支持 | 支持 | 不支持 |
| 禁用iOS Webview弹性效果 | ui.webViewBounce.disable | 不需要 | 不支持 | 支持 | 不支持 |
| 启用iOS Webview弹性效果 | ui.webViewBounce.enable | 不需要 | 不支持 | 支持 | 不支持 |
获取免登授权码
| 接口说明 | JSAPI名称 | 是否需要鉴权 | Android | IOS | PC |
|---|---|---|---|---|---|
| 获取微应用免登授权码 | runtime.permission.requestAuthCode | 不需要 | 支持 | 支持 | 支持 |
| 获取微应用反馈式操作的临时授权码 | runtime.permission.requestOperateAuthCode | 需要 | 支持 | 支持 | 支持 |
扫码
| 接口说明 | JSAPI名称 | 是否需要鉴权 | Android | IOS | PC |
|---|---|---|---|---|---|
| 扫条形码、二维码 | biz.util.scan | 不需要 | 支持 | 支持 | 不支持 |
| 扫名片 | biz.util.scanCard | 需要 | 支持 | 支持 | 不支持 |
存储
| 接口说明 | JSAPI名称 | 是否需要鉴权 | Android | IOS | PC |
|---|---|---|---|---|---|
| 设置存储信息 | util.domainStorage.setItem | 不需要 | 支持 | 支持 | 不支持 |
| 获取存储信息 | util.domainStorage.getItem | 不需要 | 支持 | 支持 | 不支持 |
| 删除存储信息 | util.domainStorage.removeItem | 不需要 | 支持 | 支持 | 不支持 |
地图
| 接口说明 | JSAPI名称 | 是否需要鉴权 | Android | IOS | PC |
|---|---|---|---|---|---|
| 获取当前地理位置信息（单次定位） | device.geolocation.get | 需要 | 支持 | 支持 | 不支持 |
| 连续获取当前地理位置信息（持续定位） | device.geolocation.start | 需要 | 支持 | 支持 | 不支持 |
| 停止连续定位 | device.geolocation.stop | 需要 | 支持 | 支持 | 不支持 |
| 批量连续定位状态 | device.geolocation.status | 不需要 | 支持 | 支持 | 不支持 |
| 地图定位 | biz.map.locate | 需要 | 支持 | 支持 | 不支持 |
| 地图页面支持搜索 | biz.map.search | 需要 | 支持 | 支持 | 不支持 |
| 展示位置 | biz.map.view | 需要 | 支持 | 支持 | 不支持 |
业务
| 接口说明 | JSAPI名称 | 是否需要鉴权 | Android | IOS | PC |
|---|---|---|---|---|---|
| 分享 | biz.util.share | 不需要 | 支持 | 支持 | 不支持 |
| 下拉控件 | biz.util.chosen | 不需要 | 支持 | 支持 | 不支持 |
| 复制到粘贴板 | biz.clipboardData.setData | 需要 | 支持 | 支持 | 不支持 |
| 打开应用 | biz.microApp.openApp | 不需要 | 支持 | 支持 | 不支持 |
文件
| 接口说明 | JSAPI名称 | 是否需要鉴权 | Android | IOS | PC |
|---|---|---|---|---|---|
| 批量检测本地文件是否存在 | biz.util.isLocalFileExist | 不需要 | 不支持 | 不支持 | 支持 |
| 打开本地文件 | biz.util.openLocalFile | 不需要 | 不支持 | 不支持 | 支持 |
| 下载文件 | biz.util.downLoadFile | 不需要 | 不支持 | 不支持 | 支持 |
图片
| 接口说明 | JSAPI名称 | 是否需要鉴权 | Android | IOS | PC |
|---|---|---|---|---|---|
| 图片预览 | biz.util.previewImage | 不需要 | 支持 | 支持 | 支持 |
打开新页面
| 接口说明 | JSAPI名称 | 是否需要鉴权 | Android | IOS | PC |
|---|---|---|---|---|---|
| 打开应用内页面 | biz.util.open | 需要 | 支持 | 支持 | 支持 |
| 打开目标页面 | biz.util.openLink | 不需要 | 支持 | 支持 | 支持 |
| 打开模态框 | biz.util.openModal | 不需要 | 不支持 | 不支持 | 支持 |
| 打开侧边面板 | biz.util.openSlidePanel | 不需要 | 不支持 | 不支持 | 支持 |
| 打开链接 | 打开音视频链接 | 需要 | 支持 | 支持 | 支持 |
电话
| 接口说明 | JSAPI名称 | 是否需要鉴权 | Android | IOS | PC |
|---|---|---|---|---|---|
| 拨打钉钉电话 | biz.telephone.call | 需要 | 支持 | 支持 | 不支持 |
| 通用电话拨打 | biz.telephone.showCallMenu | 需要 | 支持 | 支持 | 不支持 |
| 检查某企业的办公电话开通状态 | biz.telephone.checkBizCall | 需要 | 支持 | 支持 | 不支持 |
| 拨打单人电话选项（可定制） | biz.telephone.quickCallList | 需要 | 支持 | 支持 | 支持 |
发钉
| 接口说明 | JSAPI名称 | 是否需要鉴权 | Android | IOS | PC |
|---|---|---|---|---|---|
| DING 2.0 发钉 | biz.ding.create | 需要 | 支持 | 支持 | 支持 |
| DING 1.0 发钉 | biz.ding.post | 需要 | 不支持 | 不支持 | 支持 |
通讯录选人
| 接口说明 | JSAPI名称 | 是否需要鉴权 | Android | IOS | PC |
|---|---|---|---|---|---|
| PC端选择企业内部的人 | biz.contact.choose | 需要 | 不支持 | 不支持 | 支持 |
| 选取手机通讯录 | biz.contact.chooseMobileContacts | 需要 | 支持 | 支持 | 不支持 |
| 选择部门和人 | biz.contact.complexPicker | 需要 | 支持 | 支持 | 支持 |
| 选择部门信息 | biz.contact.departmentsPicker | 需要 | 支持 | 支持 | 支持 |
| 创建企业群 | biz.contact.createGroup | 需要 | 支持 | 支持 | 不支持 |
| 设定规则选人 | biz.contact.setRule | 需要 | 支持 | 支持 | 不支持 |
角色
| 接口说明 | JSAPI名称 | 是否需要鉴权 | Android | IOS | PC |
|---|---|---|---|---|---|
| 选择角色组或角色 | biz.contact.rolesPicker | 需要 | 支持 | 支持 | 不支持 |
外部联系人
| 接口说明 | JSAPI名称 | 是否需要鉴权 | Android | IOS | PC |
|---|---|---|---|---|---|
| 选择外部联系人 | biz.contact.externalComplexPicker | 需要 | 支持 | 支持 | 不支持 |
| 编辑外部联系人 | biz.contact.externalEditForm | 需要 | 支持 | 支持 | 不支持 |
自定义联系人
| 接口说明 | JSAPI名称 | 是否需要鉴权 | Android | IOS | PC |
|---|---|---|---|---|---|
| 单选自定义联系人 | biz.customContact.choose | 需要 | 支持 | 支持 | 支持 |
| 多选自定义联系人 | biz.customContact.multipleChoose | 需要 | 支持 | 支持 | 支持 |
会话
| 接口说明 | JSAPI名称 | 是否需要鉴权 | Android | IOS | PC |
|---|---|---|---|---|---|
| 获取会话信息 | biz.chat.pickConversation | 需要 | 支持 | 支持 | 支持 |
| 根据corpid选择会话 | biz.chat.chooseConversationByCorpId | 需要 | 支持 | 支持 | 支持 |
| 打开与某个用户的单聊会话 | biz.chat.openSingleChat | 需要 | 支持 | 支持 | 不支持 |
| 根据chatId跳转到对应会话 | biz.chat.toConversation | 需要 | 支持 | 支持 | 不支持 |
钉盘
| 接口说明 | JSAPI名称 | 是否需要鉴权 | Android | IOS | PC |
|---|---|---|---|---|---|
| 保存文件到钉盘 | biz.cspace.saveFile | 需要 | 支持 | 支持 | 不支持 |
| 预览钉盘文件 | biz.cspace.preview | 需要 | 支持 | 支持 | 支持 |
| 选取钉盘目录 | biz.cspace.chooseSpaceDir | 需要 | 支持 | 支持 | 不支持 |
| 上传附件到钉盘/从钉盘选择文件 | biz.util.uploadAttachment | 需要 | 支持 | 支持 | 支持 |
音频接口
| 接口说明 | JSAPI名称 | 是否需要鉴权 | Android | IOS | PC |
|---|---|---|---|---|---|
| 开始录音 | device.audio.startRecord | 需要 | 支持 | 支持 | 不支持 |
| 停止录音 | device.audio.stopRecord | 需要 | 支持 | 支持 | 不支持 |
| 监听录音自动停止 | device.audio.onRecordEnd | 需要 | 支持 | 支持 | 不支持 |
| 下载音频 | device.audio.download | 需要 | 支持 | 支持 | 不支持 |
| 播放语音 | device.audio.play | 需要 | 支持 | 支持 | 不支持 |
| 暂停播放语音 | device.audio.pause | 需要 | 支持 | 支持 | 不支持 |
| 恢复暂停播放的语音 | device.audio.resume | 需要 | 支持 | 支持 | 不支持 |
| 停止播放音频 | device.audio.stop | 需要 | 支持 | 支持 | 不支持 |
| 监听播放自动停止 | device.audio.onPlayEnd | 需要 | 支持 | 支持 | 不支持 |
| 语音转文字 | device.audio.translateVoice | 需要 | 支持 | 支持 | 不支持 |
视频会议
| 接口说明 | JSAPI名称 | 是否需要鉴权 | Android | IOS | PC |
|---|---|---|---|---|---|
| 发起视频会议 | biz.conference.videoConfCall | 需要 | 支持 | 支持 | 支持 |
在线课堂
| 接口说明 | JSAPI名称 | 是否需要鉴权 | Android | IOS | PC |
|---|---|---|---|---|---|
| 发起在线课堂 | biz.live.startClassRoom | 需要 | 不支持 | 不支持 | 支持 |
支付
| 接口说明 | JSAPI名称 | 是否需要鉴权 | Android | IOS | PC |
|---|---|---|---|---|---|
| 支付接口 | biz.alipay.pay | 需要 | 支持 | 支持 | 不支持 |
数据加解密
| 接口说明 | JSAPI名称 | 是否需要鉴权 | Android | IOS | PC |
|---|---|---|---|---|---|
| 数据加密 | biz.util.encrypt | 需要 | 支持 | 支持 | 不支持 |
| 数据解密 | biz.util.decrypt | 需要 | 支持 | 支持 | 不支持 |
转屏横屏
| 接口说明 | JSAPI名称 | 是否需要鉴权 | Android | IOS | PC |
|---|---|---|---|---|---|
| 微应用页面支持转屏 | 拼接dd_orientation=auto参数 | 不需要 | 支持 | 支持 | 不支持 |
| 微应用页面支持横屏 | 拼接dd_orientation参数 | 不需要 | 支持 | 支持 | 不支持 |
| 微应用页面全屏展示 | 拼接dd_full_screen=true参数 | 不需要 | 支持 | 支持 | 不支持 |
| 微应用页面导航栏透明 | 拼接dd_nav_translucent=true参数 | 不需要 | 支持 | 支持 | 不支持 |
| 旋转屏幕 | device.screen.rotateView | 不需要 | 支持 | 支持 | 不支持 |
| 重置旋转屏幕 | device.screen.resetView | 不需要 | 支持 | 支持 | 不支持 |
授权
| 接口说明 | JSAPI名称 | 是否需要鉴权 | Android | IOS | PC |
|---|---|---|---|---|---|
| 授权获取审批实例数据 | biz.auth.requestAuthInfo | 需要 | 支持 | 支持 | 不支持 |
| 服务窗-获取用户授权 | biz.auth.requestAuthInfo | 需要 | 支持 | 支持 | 不支持 |
| 服务窗-单聊消息授权 | biz.auth.requestAuthInfo | 需要 | 支持 | 支持 | 不支持 |
办公电话
| 接口说明 | JSAPI名称 | 是否需要鉴权 | Android | IOS | PC |
|---|---|---|---|---|---|
| 查询企业是否已开办公电话 | biz.conference.getCloudCallInfo | 需要 | 支持 | 支持 | 支持 |
| 发起办公电话呼叫 | biz.conference.createCloudCall | 需要 | 支持 | 支持 | 支持 |
| 查询话单列表 | biz.conference.getCloudCallList | 需要 | 支持 | 支持 | 支持 |
专属钉钉
| 接口说明 | JSAPI名称 | 是否需要鉴权 | Android | IOS | PC |
|---|---|---|---|---|---|
| 获取钉钉客户端是否为专属钉钉 | biz.realm.getUserExclusiveInfo | 不需要 | 支持 | 支持 | 支持 |