当前位置：首页 > news >正文

钉钉企业应用开发系列：前端实现自定义右上角菜单（dd.http + Vue3）

news 2025/7/4 5:49:47

本文将围绕“如何在钉钉企业应用中自定义右上角菜单”这一主题进行讲解，并结合现代前端技术栈（Vue3 + Composition API）展示完整实现过程，帮助你快速构建具备原生交互体验的企业应用。

一、前置准备

1. 注册钉钉开发者账号并创建应用

访问钉钉开放平台
创建一个 企业内部应用
获取以下参数：
- corpId：企业唯一标识
- agentId：应用的 Agent ID

注意：确保你的应用已开启“前端接口权限”，并配置了正确的域名白名单（必须 HTTPS）

二、自定义右上角菜单的作用与原理

钉钉默认为每个页面提供了一个“...”按钮，点击后可看到一些系统默认的操作项（如刷新、复制链接等）。通过调用钉钉提供的 JSAPI 接口，我们可以覆盖这个菜单，添加我们自己的按钮和事件处理逻辑。

核心流程如下：

页面加载时调用 dd.http.get 或 dd.http.post 获取必要的数据或状态；
调用 dd.showActionSheet 或 dd.ui.setRight() 设置右上角按钮；
绑定点击事件，执行业务逻辑（如跳转页面、提交数据等）；

三、前端实现详解（基于 Vue3 + Composition API）

我们将使用钉钉提供的 JSAPI 实现自定义右上角菜单按钮，并绑定点击事件。

1. 引入钉钉 SDK

在 HTML 文件中引入钉钉官方 JSAPI：

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

2. 创建自定义菜单组件（CustomMenu.vue）

<template><div class="menu-container"><h2>欢迎使用自定义右上角菜单</h2><p>点击右上角按钮可以执行自定义操作。</p><p v-if="actionResult" style="color: green;">{{ actionResult }}</p></div>
</template><script setup>
import { ref, onMounted } from 'vue';const actionResult = ref('');onMounted(() => {if (window.dd) {// 设置右上角按钮dd.ui.setRight({show: true, // 显示按钮text: '更多', // 按钮文字onSuccess: () => {console.log("右上角按钮被点击");// 触发自定义菜单弹出dd.actionSheet({title: "请选择操作",items: ["刷新数据", "提交表单", "关于本页"],onSuccess: (result) => {const index = result.itemIndex;let selected = "";switch(index) {case 0:selected = "刷新数据";refreshData();break;case 1:selected = "提交表单";submitForm();break;case 2:selected = "关于本页";showAbout();break;default:selected = "未知操作";}actionResult.value = `您选择了：${selected}`;},onFail: (err) => {console.error("菜单弹出失败：", err);}});},onFail: (err) => {console.error("设置右上角按钮失败：", err);}});} else {console.warn("当前环境不支持钉钉 JSAPI");}
});// 示例方法：刷新数据
function refreshData() {console.log("开始刷新数据...");// 可在此处调用 dd.http.get 请求更新数据
}// 示例方法：提交表单
function submitForm() {console.log("开始提交表单...");// 可在此处调用 dd.http.post 提交表单数据
}// 示例方法：显示关于信息
function showAbout() {console.log("显示关于信息");alert("这是一个演示页面，用于展示钉钉右上角菜单的自定义功能。");
}
</script><style scoped>
.menu-container {padding: 20px;max-width: 600px;margin: auto;font-family: Arial, sans-serif;
}
</style>

四、关键代码解析

方法	描述
`dd.ui.setRight({ show, text, onSuccess })`	设置右上角按钮样式与点击行为
`dd.actionSheet({ title, items, onSuccess })`	弹出底部操作菜单
`dd.http.get(url)` / `dd.http.post(url, data)`	发起网络请求获取或提交数据

五、常见问题与调试建议

问题	解决方案
`dd is not defined`	确保在钉钉客户端内打开页面，且 SDK 已正确加载
按钮不显示	检查是否调用了 `setRight` 并设置了 `show: true`
菜单无法弹出	查看是否被其他 UI 层遮挡或未触发 `onSuccess`
域名未授权	确保访问地址已在钉钉后台配置为合法域名
权限不足	检查是否开启了“前端 JSAPI 权限”