Metabase 嵌入式 React SDK 卡片菜单定制指南DashboardCardCustomMenuItem 类型全解析与实战【免费下载链接】metabaseThe easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:项目地址: https://gitcode.com/GitHub_Trending/me/metabase在 Metabase 模块化嵌入式 SDK 中每个交互式仪表盘InteractiveDashboard卡片右上角都有一个溢出菜单overflow menu默认提供下载结果编辑问题等操作。dashboardCardMenu插件允许你完全掌控这个菜单的内容与行为而DashboardCardCustomMenuItem就是该插件配置对象的核心类型定义。本文以 DashboardCardCustomMenuItem.md 为骨架结合仓库内 SDK 源码plugins.ts、DashCardMenuItems.tsx与官方实战文档dashboard.md、dashboard-reference.md系统讲解该类型的每个属性、底层实现原理并给出可复制运行的完整示例。读完本文你将能够在嵌入式仪表盘中开关默认菜单项、追加自定义操作、甚至用自定义组件整体替换菜单。一、类型定义速览DashboardCardCustomMenuItem是一个 TypeScript 对象类型定义如下原文照录type DashboardCardCustomMenuItem { customItems?: (DashCardMenuItem | CustomDashboardCardMenuItem)[]; withDownloads?: boolean; withEditLink?: boolean; };该类型同时出现在两处源码定义中且保持一致SDK 公共类型frontend/src/metabase/embedding-sdk/types/plugins.ts对外导出的 API 类型仪表盘内部实现frontend/src/metabase/dashboard/components/DashCard/DashCardMenu/dashcard-menu.ts内部渲染逻辑使用三个属性全部为可选?其含义如下表属性类型说明customItems?(DashCardMenuItem \| CustomDashboardCardMenuItem)[]自定义菜单项数组每项可以是普通菜单项对象也可以是接收{ question }并返回菜单项的函数withDownloads?boolean是否显示下载结果按钮withEditLink?boolean是否显示编辑问题链接二、三个属性的作用与默认值从DashboardCardCustomMenuItem的消费方 DashCardMenuItems.tsx 的源码可以看出当配置对象为undefined或属性缺省时实际采用的是以下默认值const { customItems [], // 默认无自定义项 withDownloads true, // 默认显示下载按钮 withEditLink true, // 默认显示编辑链接 } dashcardMenuItems ?? {};官方文档 dashboard-reference.md 中对三个键的描述如下键作用withDownloads控制下载结果按钮的显示与隐藏withEditLink控制编辑问题链接的显示与隐藏customItems自定义菜单项每项可以是菜单项对象也可以是接收{ question }并返回菜单项的函数2.1 withDownloads控制结果下载当withDownloads: true时只要当前卡片查询结果可下载内部通过canDownloadResults(result)判断见 dataset.ts菜单中就会出现下载结果Download results项点击后展开QuestionDownloadWidget供用户选择下载格式CSV / XLSX / JSON 等。置为false后该菜单项被移除。注意下载能力还受仪表盘上下文中的downloadsEnabled开关约束两者同时满足才会真正渲染下载相关 UI。2.2 withEditLink控制编辑入口当withEditLink: true且用户具备编辑权限canEdit且canEditQuestion(question)时菜单会根据卡片的实体类型渲染对应的编辑项问题question渲染编辑问题Edit question点击进入 notebook 编辑模式模型model渲染编辑模型Edit model指标metric渲染编辑指标Edit metric此外如果卡片处于可编辑可视化状态onEditVisualization存在会优先渲染编辑可视化Edit visualization项。相关分支逻辑全部位于 DashCardMenuItems.tsx 第 61~94 行。三、customItems追加自定义操作customItems是数组类型每个元素可以是以下两种之一3.1 静态菜单项 DashCardMenuItem直接传入一个完整的菜单项对象。DashCardMenuItem的类型定义为见 DashCardMenuItem.mdtype DashCardMenuItem { children?: ReactNode; // 子元素 closeMenuOnClick?: boolean; // 点击后是否关闭菜单可覆盖 Menu 组件的 closeOnItemClick color?: MantineColor; // theme.colors 的键或任意合法 CSS 颜色 disabled?: boolean; // 是否禁用 iconName: IconName; // 图标名必填 label: string; // 菜单项文本必填 leftSection?: ReactNode; // 文本左侧区域 onClick: () void; // 点击回调必填 rightSection?: ReactNode; // 文本右侧区域 };其中iconName是必填项其取值是IconName字符串字面量联合类型见 IconName.md仓库中收录了 300 个合法图标名常用示例download、pencil、chevronright、gear、external、share、trash、link等。3.2 动态菜单项 CustomDashboardCardMenuItemCustomDashboardCardMenuItem是一个函数类型见 CustomDashboardCardMenuItem.md接收一个{ question }对象并返回一个DashCardMenuItemtype CustomDashboardCardMenuItem ({ question, }: { question?: MetabaseQuestion; // 当前卡片对应的问题可能为 undefined }) DashCardMenuItem;其中question是MetabaseQuestion类型见 MetabaseQuestion.md包含id数字、name字符串、entityId、isSavedQuestion、description等字段可用于在菜单项文本或回调中引用当前问题的元数据。3.3 底层合并逻辑在 DashCardMenuItems.tsx 中customItems会与内置项编辑链接、下载按钮合并后统一渲染items.push( ...customItems.map((item) { const customItem typeof item function ? item({ question: transformSdkQuestion(question) }) // 函数项在此被调用 : item; return { ...customItem, key: MB_CUSTOM_${customItem.label}, }; }), );关键点若元素是函数则在渲染时调用传入经transformSdkQuestion转换后的MetabaseQuestion每个自定义项最终渲染为Menu.Item图标放在leftSection并设置fwbold加粗样式与无障碍标签菜单项的内部 key 由MB_CUSTOM_${label}生成同一 label 重复会冲突建议 label 唯一。四、如何使用 dashboardCardMenu 插件DashboardCardCustomMenuItem是dashboardCardMenu插件的两种配置形态之一。插件完整类型为见 MetabaseDashboardPluginsConfig.md 与 dashcard-menu.tstype DashboardCardMenu | DashboardCardMenuCustomElement // 函数形态整体替换菜单 | DashboardCardCustomMenuItem; // 对象形态在默认菜单基础上定制也就是说dashboardCardMenu要么传一个返回ReactNode的函数完全自定义菜单要么传本文主角DashboardCardCustomMenuItem对象在保留/裁剪默认项的基础上追加自定义项。插件通过pluginsprop 挂在仪表盘组件上dashboard键之下import { InteractiveDashboard } from metabase/embedding-sdk-react; InteractiveDashboard dashboardId{1} plugins{{ dashboard: { dashboardCardMenu: { withDownloads: true, // 默认值 withEditLink: true, // 默认值 customItems: [], // 默认值 }, }, }} /以上即官方文档给出的默认配置形态完整示例见 plugins.tsx。插件既可以在MetabaseProvider上全局设置也可以在每个仪表盘组件上局部设置组件自身的plugins优先于全局配置见 dashboard.md。注意dashboardCardMenu插件仅存在于 React SDK官方明确说明 Web Componentmetabase-dashboard没有对应等价物。4.1 关闭默认操作const plugins { dashboard: { dashboardCardMenu: { withDownloads: false, // 移除下载按钮 withEditLink: false, // 移除编辑链接 customItems: [], }, }, };当withDownloads、withEditLink均为false且customItems为空时DashCardMenu.tsx 中的isDashCardMenuEmpty判定为真整个菜单按钮将不渲染第 87~89 行直接返回null。4.2 追加自定义操作对象 函数两种形态const plugins: MetabasePluginsConfig { dashboard: { dashboardCardMenu: { customItems: [ // 形态一静态菜单项对象 { iconName: chevronright, label: Custom action, onClick: () { alert(Custom action clicked); }, }, // 形态二函数接收 { question }返回菜单项对象 ({ question }) { return { iconName: chevronright, label: Custom action, onClick: () { alert(Custom action clicked ${question?.name}); }, }; }, ], }, }, };函数形态让菜单项可以感知当前卡片对应的问题——例如把问题名拼进操作提示、按问题类型决定是否展示某项或携带问题 ID 跳转到宿主应用内部页面。4.3 整体替换菜单DashboardCardMenuCustomElement如果内置菜单完全不符合需求可以直接传一个返回 React 元素的函数const plugins: MetabasePluginsConfig { dashboard: { dashboardCardMenu: ({ question }) ( button onClick{() console.log(question.name)}Click me/button ), }, };该函数形态类型为DashboardCardMenuCustomElement见 DashboardCardMenuCustomElement.md其参数除了question在内部实现中还注入dashcard、result、downloadsEnabled等标记为internal的字段见 dashcard-menu.ts。在 DashCardMenu.tsx 中当typeof dashcardMenu function时直接调用该函数并将其返回值作为菜单整体渲染第 91~98 行。五、底层渲染链路与判空规则从源码看DashboardCardCustomMenuItem的完整消费链路为plugins.dashboard.dashboardCardMenu传入仪表盘组件经 Dashboard 上下文useDashboardContext传递到每个卡片的 DashCardMenu.tsx若为对象形态则交给DashCardMenuItems组装菜单项先按withEditLink决定是否加入编辑项再按withDownloads与canDownloadResults决定是否加入下载项最后展开customItems追加自定义项全部项渲染进 MantineMenu.Dropdown触发下载时切换为QuestionDownloadWidget视图。此外还有一处渲染前的过滤DashCardMenu.shouldRender会检查是否满足渲染条件非内部查询、且至少存在可编辑/可下载/有下层问题项之一不满足则整个菜单不渲染。定制时如果发现菜单消失了可优先排查这些前置条件。六、常见问题与注意事项菜单完全不显示检查dashboardCardMenu是否配置为{ withDownloads: false, withEditLink: false, customItems: [] }这种全空形态或卡片本身不可编辑、结果不可下载、查询属于内部查询Audit V1 等InternalQuery。自定义项图标不生效iconName必须为IconName联合类型中的合法值DashCardMenuItem中iconName与label、onClick均为必填。自定义项不出现确认插件挂在dashboard键下且customItems数组非空函数形态的项只有被调用时才生成菜单项。React SDK 专属dashboardCardMenu插件没有 Web Component 版本使用metabase-dashboard静态/交互式嵌入时无法通过该插件定制卡片菜单。七、相关资源索引类型参考DashboardCardCustomMenuItem.md、DashCardMenuItem.md、CustomDashboardCardMenuItem.md、DashboardCardMenu.md、DashboardCardMenuCustomElement.md插件配置类型MetabaseDashboardPluginsConfig.md实战文档仪表盘卡片菜单定制、dashboardCardMenu 插件参考、插件总览源码实现plugins.ts、DashCardMenuItems.tsx、DashCardMenu.tsx、dashcard-menu.ts可运行示例plugins.tsx【免费下载链接】metabaseThe easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:项目地址: https://gitcode.com/GitHub_Trending/me/metabase创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
