钉钉H5开发问题总结

H5内安装依赖

方式一：使用npm引入（推荐）

npm install dingtalk-jsapi --save
//页面内引用：
import * as dd from "dingtalk-jsapi";

方式二：使用cdn引入（不推荐）

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

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

调用API

调用readNFC，读取NFC芯片内容

dd.readNFC({
  success: (res) => {
    const { content } = res;
  },
  fail: () => {},
  complete: () => {},
});

success返回对象示例：

{ "content": "0103BC25" }

API鉴权

部分api方法因为安全原因，需要先进行鉴权，鉴权需要一些参数只能通过服务端去获取，然后H5通过接口的方式拿到，根据拿到的数据去调用鉴权接口

dd.config({
  agentId: configResult.item.agentId, // 必填，微应用ID
  corpId: configResult.item.corpId, // 必填，企业ID
  timeStamp: configResult.item.timeStamp, // 必填，生成签名的时间戳
  nonceStr: configResult.item.nonceStr, // 必填，自定义固定字符串。
  signature: configResult.item.signature, // 必填，签名
  type: 0, // 选填。0表示微应用的jsapi,1表示服务窗的jsapi；不填默认为0。该参数从dingtalk.js的0.8.3版本开始支持
  jsApiList: ["nfcReadCardNumber"], // 必填，需要使用的jsapi列表，注意：不要带dd。
});
dd.error(function (err) {
  console.log("鉴权报错了");
}); // 该方法必须带上，用来捕获鉴权出现的异常信息，否则不方便排查出现的问题
dd.ready(function () {
  console.log("nfc接口鉴权成功~");
  // 此处调用JSAPI方法
  this.getNFCNumberMethod();
});

嵌入小程序中的H5

尽管钉钉提供了web-view容器，让H5嵌入小程序变得异常简单，但是当嵌入钉钉小程序中，绝大部分H5的JSAPI都无穿透小程序，此时需要H5和原生小程序外壳进行通讯，让小程序调用对应API方法，将获得的数据再传递给H5

1. 判断当前H5的运行环境，首先过滤掉钉钉环境和非IOS环境

isDingding() {
  let ua = navigator.userAgent.toLowerCase();
  return /DingTalk/i.test(ua);
},
isIOS() {
  const u = navigator.userAgent;
  return !!u.match(/\(i[^;]+;( U;)? CPU.+Mac OS X/);
},
if (this.isDingding() && !this.isIOS()) {
  // 此处再进行第二步的判断
}

2. 如果是在内嵌在钉钉小程序中，则与小程序进行通信，让小程序调用对应的JSAPI

如果是普通H5，则非鉴权接口可以直接调用JSAPI，鉴权接口则需要先进行鉴权

if (
  navigator.userAgent.toLowerCase().indexOf("dingtalk") > -1 &&
  (navigator.userAgent.toLowerCase().indexOf("miniprogram") > -1 ||
    navigator.userAgent.toLowerCase().indexOf("dd-web") > -1)
) {
  console.log("此时的入口是钉钉小程序~~~~~~");
  dd.postMessage({
    type: "add",
    token: getAccessToken(),
    deviceName: "所有设备",
    deviceCode: "",
  });
  dd.onMessage = function (e) {
    console.log("接收到了小程序传递过来的卡号信息");
    console.log(e);
    if (e.sendToWebView && e.sendToWebView.content) {
      _this.handlerNFC(e.sendToWebView.content);
    }
  };
} else {
  console.log("此时的入口是钉钉H5~~~~~~");
  // 参考上面的调用API代码
}

小程序

原生小程序应该在web-view容器组件上进行消息事件的监听

<web-view a:if="{{showWebview}}" src="{{url}}" onMessage="onMessage"></web-view>

onMessage({detail}){
  if(detail.type  === 'delete'){
    // some code
  } else if ( detail.type  === 'add' ) {
    console.log("H5传来:" ,detail);
    // 调用对应的JSAPI
    // some code
  }
},

小程序中安装JSAPI包

有些比较新的方法，原生小程序也是不支持的，此时可以在小程序中安装对应JSAPI，然后像在H5中那样进行调用

1. 钉钉小程序项目内创建node_modules文件夹
2. 在创建的node_modules文件夹目录下，安装dingtalk-jsapi npm install dingtalk-jsapi --save
3. 在钉钉小程序app.js文件头部，添加以下代码： import 'dingtalk-jsapi/entry/mobile';
4. 小程序index.js文件头部，添加以下代码 import complexPicker from 'dingtalk-jsapi/api/biz/contact/complexPicker';
5. 在axml文件中定义触发
6. 在js文件中定义触发对应的逻辑

参考： open.dingtalk.康么/document/orgapp/steps