一、先找到对应 JSAPI
开发前先在钉钉开放平台查阅目标 API 文档：
- JSAPI 鉴权：https://open.dingtalk.com/document/orgapp/jsapi-authentication
- 打开聊天 API：https://open.dingtalk.com/document/development/jsapi-open-chat-by-user-id
- 在线调试工具：https://open.dingtalk.com/tools/explorer/jsapi
鉴权规则：https://open.dingtalk.com/document/orgapp/jsapi-authentication
二、安装 dingtalk-jsapi 依赖
npm i dingtalk-jsapi钉钉的「官方接口工具包」
在工作台打开的 H5 本质是一个普通网页，网页本身不能直接调用钉钉的功能，
必须通过这个 SDK 桥接。
没有这个包 → 什么钉钉能力都用不了。
且它兼容多端（PC 钉钉 / 手机钉钉 / 钉钉开发者工具）。
最常见的使用场景
javascript
import dd from 'dingtalk-jsapi' // 就是这个包
dd.ready(() => {
// 1. 获取用户信息 → 实现免登
dd.biz.user.get().then(res => {
console.log('当前钉钉用户', res)
})
// 2. 调用扫码
dd.biz.util.scan({
type: 'qrCode'
}).then(res => {
console.log('扫码结果', res)
})
})三、钉钉登录
钉钉项目内所有的接口都需要鉴权
javascript
dd.runtime.permission.requestAuthCode它是钉钉 H5 免登的「第一步」------ 用来获取临时授权码 code，有了这个 code，才能拿到钉钉用户信息，实现自动登录。
-
向钉钉客户端申请「临时授权码」 调用这个 API，钉钉会直接返回一个一次性临时 code （5 分钟过期）→ 这个 code 就是用户的临时身份证
-
专门用于【钉钉免登】 你不能直接用它拿用户信息必须把 code 传给后端 ，后端再去钉钉服务器换真实用户信息
-
必须在钉钉环境里才能用 浏览器里直接调用会报错，只能在手机钉钉 / PC 钉钉 / 钉钉开发者工具里用
前端（ H5）
javascriptimport * as dd from "dingtalk-jsapi"; // 1. 调用这个 API → 拿临时 code dd.runtime.permission.requestAuthCode({ corpId: "你的钉钉企业ID", // 必须填 onSuccess: (res) => { const code = res.code; // 拿到临时授权码 // 2. 把 code 发给后端 axios.post("/api/dingtalk/login", { code }) .then(user => { // 后端返回用户信息 → 完成登录 }) } })
后端（服务器）
- 拿
code+appkey+appsecret（创建的应用里面查看）- 请求钉钉接口 → 换取用户 userid
- 再拿 userid → 获取用户姓名、手机号、部门等完整信息
- 返回给前端 → 自动登录成功
和 dd.biz.user.get 的区别
| API | 作用 | 权限 | 使用场景 |
|---|---|---|---|
| dd.runtime.permission.requestAuthCode | 获取临时 code → 做免登 | 无需申请权限 | 登录必用 |
| dd.biz.user.get | 获取用户基础信息 | 需要申请权限 | 已登录后获取信息 |
免登 = 必须用 requestAuthCode没有它，你的 H5 就不能实现「打开应用自动登录」。
✅【应用打开时】拿一次 code
✅ 后端兑换成【业务 Token】
✅ 之后所有接口都只带 Token
3.JSAPI 签名（dd.config）
官方链接：
https://open.dingtalk.com/document/development/jsapi-open-chat-by-user-id
https://open.dingtalk.com/document/orgapp/jsapi-authentication
corpId：
应用凭证
打开聊天需要权限配置，必须先调用dd.config，否则会报错。
且后端必须进行 JSAPI鉴权 ！！！很重要
我这里直接取值后端接口返回的鉴权完成的数据 jsapiConfig
javascript
// url 处理 钉钉签名必须用 # 之前的 URL
const url = window.location.href.split('#')[0]
// 获取 config
const config = await jsapiConfig({ url })
dd.config({
agentId: config.agentId,
corpId: config.corpId,
timeStamp: config.timeStamp,
nonceStr: config.nonceStr,
signature: config.signature,
jsApiList: ['biz.chat.openSingleChat'], // 老版本写法
})
dd.ready(() => {
// alert('钉钉鉴权成功！')
})
dd.error((err) => {
console.error('钉钉鉴权失败', err)
alert('鉴权失败：' + JSON.stringify(err))
})
} catch (e) {
console.error('获取钉钉鉴权配置失败', e)
alert('获取钉钉鉴权配置失败' + e)
}
jsApiList: ['openChatByUserId'], // 新版本这么写！
biz.chat.openSingleChat 已废弃但是暂时还是可以用
在需要调用聊天对话框的位置
javascript
dd.openChatByUserId({
corpId: '企业corpId',
userId: '要打开的用户ID', // 替换成真实userId
success: () => {
console.log('打开单聊成功')
},
fail: (err) => {
console.error('打开失败', err)
}
});注意点：
后端必须进行 JSAPI鉴权 ！！！很重要
dd.config的时候：当前网页的URL，是不包含#及其后面部分。
必须是当前页面的 location.href 的原内容，请勿提前进行encode/urlencode处理，否则会引起编码不一致最终导致签名校验失败
传给后端授权的url与钉钉开发平台里配置的【应用首页地址】域名必须一致
必须是下图配置的url（地址不同无法授权）
这个网址可以调试