跳到主要内容

钉钉 JS-API

钉钉提供了丰富的JSAPI能力，例如原生弹框、设备信息、扫描等能力，宜搭开发者可以利用钉钉原生提供的API能力提供更好的用户体验。

警告

调用钉钉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) { }
    });
  }
}

钉钉端内的展示效果如下所示：

警告

由于很多钉钉JSAPI要求必须端内调用，因此在调用钉钉JSAPI时，需要提前先判断一下是否在钉钉端内，判断代码如下所示：

export function isDingTalk() {
  return window.navigator && /dingtalk/i.test(window.navigator.userAgent)
}

API列表​

容器​

接口说明JSAPI名称是否需要鉴权AndroidIOSPC
获取容器版本号dd.version不需要支持支持不支持

弹框​

接口说明JSAPI名称是否需要鉴权AndroidIOSPC
alertdevice.notification.alert不需要支持支持支持
confirmdevice.notification.confirm不需要支持支持支持
promptdevice.notification.prompt不需要支持支持支持
手机震动device.notification.vibrate不需要支持支持不支持
toastdevice.notification.toast不需要支持支持支持
actionsheetdevice.notification.actionSheet不需要支持支持支持
显示加载device.notification.showPreloader不需要支持支持不支持
隐藏加载device.notification.hidePreloader不需要支持支持不支持
modal弹浮层device.notification.modal不需要支持支持不支持
extendModaldevice.notification.extendModal不需要支持支持不支持
多选组件biz.util.multiSelect不需要支持支持不支持

摇一摇​

接口说明JSAPI名称是否需要鉴权AndroidIOSPC
启动摇一摇device.accelerometer.watchShake不需要支持支持不支持
停止摇一摇device.accelerometer.clearShake不需要支持支持不支持

设备​

接口说明JSAPI名称是否需要鉴权AndroidIOSPC
获取网络类型device.connection.getNetworkType不需要支持支持不支持
获取wifi状态device.base.getWifiStatus不需要支持支持不支持
获取手机基础信息device.base.getPhoneInfo不需要支持支持不支持
获取uuiddevice.base.getUUID需要支持支持不支持
获取热点接入信息device.base.getInterface需要支持支持不支持
读取NFC芯片内容device.nfc.nfcRead不需要支持不支持不支持
NFC数据写入device.nfc.nfcWrite需要支持不支持不支持
打开iOS系统设置device.base.openSystemSetting不需要不支持支持不支持
打开Android系统设置device.base.openSystemSetting不需要支持不支持不支持

日期&月历​

接口说明JSAPI名称是否需要鉴权AndroidIOSPC
日期选择器biz.util.datepicker不需要支持支持不支持
时间选择器biz.util.timepicker不需要支持支持不支持
日期及时间选择器biz.util.datetimepicker不需要支持支持不支持
月历组件：选择某天biz.calendar.chooseOneDay不需要支持支持不支持
月历组件：选择某时间biz.calendar.chooseDateTime不需要支持支持不支持
月历组件：选择某天biz.calendar.chooseHalfDay不需要支持支持不支持
月历组件：选择日期区间biz.calendar.chooseInterval不需要支持支持不支持

导航栏​

接口说明JSAPI名称是否需要鉴权AndroidIOSPC
设置导航栏颜色拼接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名称是否需要鉴权AndroidIOSPC
输入框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名称是否需要鉴权AndroidIOSPC
获取微应用免登授权码runtime.permission.requestAuthCode不需要支持支持支持
获取微应用反馈式操作的临时授权码runtime.permission.requestOperateAuthCode需要支持支持支持

扫码​

接口说明JSAPI名称是否需要鉴权AndroidIOSPC
扫条形码、二维码biz.util.scan不需要支持支持不支持
扫名片biz.util.scanCard需要支持支持不支持

存储​

接口说明JSAPI名称是否需要鉴权AndroidIOSPC
设置存储信息util.domainStorage.setItem不需要支持支持不支持
获取存储信息util.domainStorage.getItem不需要支持支持不支持
删除存储信息util.domainStorage.removeItem不需要支持支持不支持

地图​

接口说明JSAPI名称是否需要鉴权AndroidIOSPC
获取当前地理位置信息（单次定位）device.geolocation.get需要支持支持不支持
连续获取当前地理位置信息（持续定位）device.geolocation.start需要支持支持不支持
停止连续定位device.geolocation.stop需要支持支持不支持
批量连续定位状态device.geolocation.status不需要支持支持不支持
地图定位biz.map.locate需要支持支持不支持
地图页面支持搜索biz.map.search需要支持支持不支持
展示位置biz.map.view需要支持支持不支持

业务​

接口说明JSAPI名称是否需要鉴权AndroidIOSPC
分享biz.util.share不需要支持支持不支持
下拉控件biz.util.chosen不需要支持支持不支持
复制到粘贴板biz.clipboardData.setData需要支持支持不支持
打开应用biz.microApp.openApp不需要支持支持不支持

文件​

接口说明JSAPI名称是否需要鉴权AndroidIOSPC
批量检测本地文件是否存在biz.util.isLocalFileExist不需要不支持不支持支持
打开本地文件biz.util.openLocalFile不需要不支持不支持支持
下载文件biz.util.downLoadFile不需要不支持不支持支持

图片​

接口说明JSAPI名称是否需要鉴权AndroidIOSPC
图片预览biz.util.previewImage不需要支持支持支持

打开新页面​

接口说明JSAPI名称是否需要鉴权AndroidIOSPC
打开应用内页面biz.util.open需要支持支持支持
打开目标页面biz.util.openLink不需要支持支持支持
打开模态框biz.util.openModal不需要不支持不支持支持
打开侧边面板biz.util.openSlidePanel不需要不支持不支持支持
打开链接打开音视频链接需要支持支持支持

电话​

接口说明JSAPI名称是否需要鉴权AndroidIOSPC
拨打钉钉电话biz.telephone.call需要支持支持不支持
通用电话拨打biz.telephone.showCallMenu需要支持支持不支持
检查某企业的办公电话开通状态biz.telephone.checkBizCall需要支持支持不支持
拨打单人电话选项（可定制）biz.telephone.quickCallList需要支持支持支持

发钉​

接口说明JSAPI名称是否需要鉴权AndroidIOSPC
DING 2.0 发钉biz.ding.create需要支持支持支持
DING 1.0 发钉biz.ding.post需要不支持不支持支持

通讯录选人​

接口说明JSAPI名称是否需要鉴权AndroidIOSPC
PC端选择企业内部的人biz.contact.choose需要不支持不支持支持
选取手机通讯录biz.contact.chooseMobileContacts需要支持支持不支持
选择部门和人biz.contact.complexPicker需要支持支持支持
选择部门信息biz.contact.departmentsPicker需要支持支持支持
创建企业群biz.contact.createGroup需要支持支持不支持
设定规则选人biz.contact.setRule需要支持支持不支持

角色​

接口说明JSAPI名称是否需要鉴权AndroidIOSPC
选择角色组或角色biz.contact.rolesPicker需要支持支持不支持

外部联系人​

接口说明JSAPI名称是否需要鉴权AndroidIOSPC
选择外部联系人biz.contact.externalComplexPicker需要支持支持不支持
编辑外部联系人biz.contact.externalEditForm需要支持支持不支持

自定义联系人​

接口说明JSAPI名称是否需要鉴权AndroidIOSPC
单选自定义联系人biz.customContact.choose需要支持支持支持
多选自定义联系人biz.customContact.multipleChoose需要支持支持支持

会话​

接口说明JSAPI名称是否需要鉴权AndroidIOSPC
获取会话信息biz.chat.pickConversation需要支持支持支持
根据corpid选择会话biz.chat.chooseConversationByCorpId需要支持支持支持
打开与某个用户的单聊会话biz.chat.openSingleChat需要支持支持不支持
根据chatId跳转到对应会话biz.chat.toConversation需要支持支持不支持

钉盘​

接口说明JSAPI名称是否需要鉴权AndroidIOSPC
保存文件到钉盘biz.cspace.saveFile需要支持支持不支持
预览钉盘文件biz.cspace.preview需要支持支持支持
选取钉盘目录biz.cspace.chooseSpaceDir需要支持支持不支持
上传附件到钉盘/从钉盘选择文件biz.util.uploadAttachment需要支持支持支持

音频接口​

接口说明JSAPI名称是否需要鉴权AndroidIOSPC
开始录音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名称是否需要鉴权AndroidIOSPC
发起视频会议biz.conference.videoConfCall需要支持支持支持

在线课堂​

接口说明JSAPI名称是否需要鉴权AndroidIOSPC
发起在线课堂biz.live.startClassRoom需要不支持不支持支持

支付​

接口说明JSAPI名称是否需要鉴权AndroidIOSPC
支付接口biz.alipay.pay需要支持支持不支持

数据加解密​

接口说明JSAPI名称是否需要鉴权AndroidIOSPC
数据加密biz.util.encrypt需要支持支持不支持
数据解密biz.util.decrypt需要支持支持不支持

转屏横屏​

接口说明JSAPI名称是否需要鉴权AndroidIOSPC
微应用页面支持转屏拼接dd_orientation=auto参数不需要支持支持不支持
微应用页面支持横屏拼接dd_orientation参数不需要支持支持不支持
微应用页面全屏展示拼接dd_full_screen=true参数不需要支持支持不支持
微应用页面导航栏透明拼接dd_nav_translucent=true参数不需要支持支持不支持
旋转屏幕device.screen.rotateView不需要支持支持不支持
重置旋转屏幕device.screen.resetView不需要支持支持不支持

授权​

接口说明JSAPI名称是否需要鉴权AndroidIOSPC
授权获取审批实例数据biz.auth.requestAuthInfo需要支持支持不支持
服务窗-获取用户授权biz.auth.requestAuthInfo需要支持支持不支持
服务窗-单聊消息授权biz.auth.requestAuthInfo需要支持支持不支持

办公电话​

接口说明JSAPI名称是否需要鉴权AndroidIOSPC
查询企业是否已开办公电话biz.conference.getCloudCallInfo需要支持支持支持
发起办公电话呼叫biz.conference.createCloudCall需要支持支持支持
查询话单列表biz.conference.getCloudCallList需要支持支持支持

专属钉钉​

接口说明JSAPI名称是否需要鉴权AndroidIOSPC
获取钉钉客户端是否为专属钉钉biz.realm.getUserExclusiveInfo不需要支持支持支持
Copyright © 2023钉钉（中国）信息技术有限公司和／或其关联公司浙ICP备18037475号-4