钉钉开发文档

开发前必读

更新时间: 2019-2-14

概述

H5微应用JSAPI为应用提供了调用原生控件的能力,帮助开发者高效使用拍照、定位等手机系统的能力,同时可以直接使用扫一扫、分享、钉盘等钉钉特有的能力,带给微应用接近原生代码的体验。此文档面向开发者介绍钉钉JSAPI如何使用及相关注意事项。

注意:钉钉微应用PC端开发和移动端开发已经统一,均可使用下面方式进行引入调用。

准备工作

钉钉提供了调试页面,供开发者在开发之前提前体验客户端提供的JSAPI功能。开发者打开钉钉,扫描调试页面二维码即可提前体验,JSAPI调试页面请点击

使用npm安装

我们推荐使用 npm 的方式进行开发,不仅可在开发环境轻松调试,也可放心地在生产环境打包部署使用,享受整个生态圈和工具链带来的诸多好处。

npm install dingtalk-jsapi --save

如果你的网络环境不佳,推荐使用 cnpm

示例代码:

import * as dd from 'dingtalk-jsapi'; // 此方式为整体加载,也可按需进行加载

浏览器引入

在浏览器中使用 script 和 link 标签直接引入文件,并使用全局变量 dd。

<script src="//g.alicdn.com/dingding/dingtalk-jsapi/2.0.57/dingtalk.open.js"></script>

不推荐使用已构建文件,这样无法按需加载,而且难以获得底层依赖模块的 bug 快速修复支持。

JSAPI鉴权配置

钉钉提供的JSAPI有很多是手机的基础能力,对这些JSAPI的调用不需要进行鉴权(即不需要进行dd.config),只需要保证在dd.ready里面调用即可。对于一些钉钉业务相关、安全相关的JSAPI的调用,需要开发者先进行鉴权然后再调用。

了解JSAPI是否需要鉴权,请查看“JSAPI列表总览”。
使用需要鉴权的JSAPI,请查看“JSAPI鉴权”流程。

调用JSAPI组件

注意:所有JSAPI组件的调用,必须在dd.ready里面执行。

dd.ready(function() {
    // dd.ready参数为回调函数,在环境准备就绪时触发,jsapi的调用需要保证在该回调函数触发后调用,否则无效。
    dd.runtime.permission.requestAuthCode({
        corpId: "corpid",
        onSuccess: function(result) {
        /*{
            code: 'hYLK98jkf0m' //string authCode
        }*/
        },
        onFail : function(err) {}
  
    });
});

通过error接口处理失败验证

dd.config验证失败会执行error函数,错误信息可以在返回的error参数中参看,下面为error信息示例:

dd.error(function(error){
       /**
        {
           errorMessage:"错误信息",// errorMessage 信息会展示出钉钉服务端生成签名使用的参数,请和您生成签名的参数作对比,找出错误的参数
           errorCode: "错误码"
        }
       **/
       alert('dd error: ' + JSON.stringify(err));
});

image

接口约定

  • 所有接口都为异步
  • 接受一个object类型的参数
  • 成功回调 onSuccess(某些异步接口的成功回调,将在事件触发时被调用,具体详情请查看相关onSuccess回调时机)
  • 失败回调 onFail
dd.命名空间.功能.方法({
    参数1: '',
    参数2: '',
    onSuccess: function(result) {
    //成功回调
    /*
    {
        //所有返回信息都输出在这里
    }*/
    },
    onFail: function(){
    //失败回调
    }
})
以上内容是否对您有帮助:
在文档使用中是否遇到以下问题(多选):
  • 内容错误
  • 更新不及时
  • 链接错误
  • 缺少代码/图片示例
  • 太简单/步骤待完善
手机号
更多建议
提交成功,感谢您的反馈!