Metabase Embedding SDK 的 DashboardCardMenu 类型定制交互式看板卡片溢出菜单的完整指南【免费下载链接】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 开源项目 Embedding SDKReact 版中的DashboardCardMenu类型。它是dashboardCardMenu插件位于MetabasePluginsConfig.dashboard.dashboardCardMenu的核心类型定义用于控制交互式看板InteractiveDashboard上每张卡片右上角溢出菜单的内容——包括内置的下载结果、编辑问题链接以及你自定义的菜单项甚至可以整体替换为完全自定义的 React 组件。读完本文你将掌握该类型两种形态配置对象 / 自定义元素函数的完整用法、默认行为、底层实现原理与可运行的实战代码。DashboardCardMenu 是什么一个联合类型Union Type在 docs/embedding/sdk/api/snippets/DashboardCardMenu.md 中DashboardCardMenu的定义非常精简type DashboardCardMenu | DashboardCardMenuCustomElement | DashboardCardCustomMenuItem;它是由两个分支组成的联合类型意味着dashboardCardMenu插件接受两种截然不同的配置形态分支类型形态作用DashboardCardMenuCustomElement一个接收{ question }并返回ReactNode的函数整体替换卡片溢出菜单用你自己的 React 元素渲染DashboardCardCustomMenuItem一个配置对象含customItems、withDownloads、withEditLink增量定制默认菜单控制内置项显隐并追加自定义菜单项该类型的实际定义位于 frontend/src/metabase/embedding-sdk/types/plugins.ts而 SDK 内部渲染时所使用的更完整版本额外带有dashcard、result、downloadsEnabled等内部字段见 frontend/src/metabase/dashboard/components/DashCard/DashCardMenu/dashcard-menu.ts。内部版本标注为internal的字段在公开类型中被隐藏开发者只需要关心公开 API。重要限制dashboardCardMenu插件是React SDK 专属没有对应的 Web Component 等价物见 docs/embedding/dashboard.md。如果你使用metabase-dashboardWeb Component 嵌入看板将无法使用本插件。分支一DashboardCardCustomMenuItem——用配置对象增量定制菜单这是最常用、侵入性最小的形态。其定义见 DashboardCardCustomMenuItem.md为type DashboardCardCustomMenuItem { customItems?: (DashCardMenuItem | CustomDashboardCardMenuItem)[]; withDownloads?: boolean; withEditLink?: boolean; };三个配置键的含义与默认值根据 docs/embedding/dashboard-reference.md 的说明各键作用如下键作用默认值withDownloads显示或隐藏“下载结果”Download results按钮truewithEditLink显示或隐藏“编辑问题/模型/指标”链接truecustomItems追加的自定义菜单项数组每项可以是菜单项对象或接收{ question }返回菜单项对象的函数[]这些默认值在源码中有直接印证在 DashCardMenuItems.tsx 中组件通过解构赋默认值的方式实现了customItems []、withDownloads true、withEditLink true。内置菜单项的完整结构DashCardMenuItemcustomItems数组中的每个元素要么是DashCardMenuItem对象要么是能生成它的函数。DashCardMenuItem见 DashCardMenuItem.md完整定义如下type DashCardMenuItem { children?: ReactNode; closeMenuOnClick?: boolean; color?: MantineColor; disabled?: boolean; iconName: IconName; label: string; leftSection?: ReactNode; onClick: () void; rightSection?: ReactNode; };各属性说明属性类型是否必填说明iconNameIconName必填菜单项图标名称。IconName是一个超长的字符串字面量联合类型包含download、pencil、chevronright、external等数百个内置图标名labelstring必填菜单项显示文本onClick() void必填点击回调childrenReactNode可选菜单项子内容closeMenuOnClickboolean可选点击该项后是否关闭菜单可覆盖Menu组件的closeOnItemClickcolorMantineColor可选图标/文本颜色可为theme.colors的键或任意合法 CSS 颜色disabledboolean可选是否禁用该项leftSectionReactNode可选标签左侧区域图标通常在这里rightSectionReactNode可选标签右侧区域如快捷键提示、下拉箭头动态生成菜单项CustomDashboardCardMenuItemcustomItems数组中的元素也可以是函数其类型见 CustomDashboardCardMenuItem.mdtype CustomDashboardCardMenuItem ({ question, }: { question?: MetabaseQuestion; }) DashCardMenuItem;它接收{ question }即当前卡片对应的问题MetabaseQuestion类型可能为空所以是可选的返回一个DashCardMenuItem。这让你可以根据当前卡片的问题元数据动态决定菜单项的内容例如根据问题名称、ID 决定是否显示某项。MetabaseQuestion的属性见 MetabaseQuestion.md包括descriptionstring | null、entityIdstring、idnumber、isSavedQuestionboolean、namestring。分支二DashboardCardMenuCustomElement——用自定义 React 元素整体替换菜单当你需要完全掌控溢出菜单的 UI例如改成自定义样式的按钮组、弹层、甚至非菜单形态的交互组件时使用DashboardCardMenuCustomElement。其定义见 DashboardCardMenuCustomElement.mdtype DashboardCardMenuCustomElement ({ question, }: { question: MetabaseQuestion; }) ReactNode;入参{ question }其中question是必填的MetabaseQuestion返回值任意ReactNodeReact 元素、片段、字符串等。一旦你传入的是函数形态SDK 将跳过内置菜单的渲染逻辑直接把函数返回值渲染为卡片菜单区域。这在源码中体现得十分清晰在 DashCardMenu.tsx 中组件先判断typeof dashcardMenu function若是则直接调用它并返回结果完全不再走 MantineMenu的内置渲染分支。如何传入MetabasePluginsConfig 的配置链路DashboardCardMenu通过以下类型链路挂载到插件配置上见 MetabaseDashboardPluginsConfig.md 与 MetabasePluginsConfig.mdtype MetabasePluginsConfig { dashboard?: MetabaseDashboardPluginsConfig; mapQuestionClickActions?: MetabaseClickActionPluginsConfig; }; type MetabaseDashboardPluginsConfig { dashboardCardMenu?: DashboardCardMenu; };有两种传递方式见 docs/embedding/dashboard.md组件级通过看板组件如InteractiveDashboard的pluginsprop 传入仅对该组件生效全局级在MetabaseProvider的pluginsprop 上设置对所有看板组件生效。优先级规则组件自身的pluginsprop 优先于MetabaseProvider上的全局配置。从源码结构看dashboardCardMenu最终通过 Dashboard 的 Context 向下传递见 frontend/src/metabase/dashboard/context/context.tsx上下文字段为dashcardMenu?: DashboardCardMenu | null供卡片组件消费。实战示例完整可运行的配置代码仓库文档中提供了完整的可运行示例见 docs/embedding/sdk/snippets/dashboards/plugins.tsx以下是三种典型场景的完整代码。场景一带默认值的完整配置import { InteractiveDashboard, type MetabasePluginsConfig, } from metabase/embedding-sdk-react; const plugins: MetabasePluginsConfig { dashboard: { dashboardCardMenu: { withDownloads: true, // 显示下载按钮 withEditLink: true, // 显示编辑链接 customItems: [], // 暂不追加自定义项 }, }, }; InteractiveDashboard dashboardId{1} plugins{plugins} /;场景二关闭默认动作将withDownloads和withEditLink设为false即可移除下载按钮与编辑链接const plugins { dashboard: { dashboardCardMenu: { withDownloads: false, withEditLink: false, customItems: [], }, }, };注意一个细节当withDownloads、withEditLink均为false且customItems为空时溢出菜单会被判定为“空菜单”而完全不渲染连右上角的省略号按钮也会消失。这一行为在 DashCardMenu.tsx 的isDashCardMenuEmpty函数中实现并有对应的单元测试验证见 Dashcard.unit.spec.tsx测试断言空配置时省略号图标不出现在文档中。同理当dashcardMenu为null时菜单也不渲染X-ray 场景见同文件 L272-L275。场景三追加自定义菜单项对象 函数两种写法const plugins: MetabasePluginsConfig { dashboard: { dashboardCardMenu: { customItems: [ // 写法 1静态对象 { iconName: chevronright, label: Custom action, onClick: () { alert(Custom action clicked); }, }, // 写法 2接收 { question } 的函数可基于问题动态构建 ({ question }) { return { iconName: chevronright, label: Custom action, onClick: () { alert(Custom action clicked ${question?.name}); }, }; }, ], }, }, };从源码看两种写法在渲染时是统一处理的在 DashCardMenuItems.tsx 中SDK 先判断元素是否为函数若是则用item({ question: transformSdkQuestion(question) })动态求值再为每个自定义项生成MB_CUSTOM_${label}格式的 React key最后以Menu.Item渲染图标放入leftSection。同时注意自定义项追加在内置的“编辑”与“下载”项之后。场景四整体替换菜单为自定义组件const plugins: MetabasePluginsConfig { dashboard: { dashboardCardMenu: ({ question }) ( button onClick{() console.log(question.name)}Click me/button ), }, };此时 SDK 不再渲染内置溢出菜单而是直接渲染你返回的 React 元素见 DashCardMenu.tsx 的函数分支。底层实现内置菜单项是如何生成的理解DashboardCardMenu的两种形态之后再看底层实现会让你对边界行为有更准确的把握。内置菜单的构建逻辑集中在 DashCardMenuItems.tsx编辑类菜单项L61-L94仅当withEditLink为true且具备编辑权限canEdit时出现。根据问题类型生成不同条目普通问题questionEdit question图标pencil模型modelEdit model图标pencil进入查询模式指标metricEdit metric图标pencil存在可视化编辑器回调时显示Edit visualization图标lineandbar。下载菜单项L96-L105仅当withDownloads为true且canDownloadResults(result)为真时出现标签为Download results下载中显示Downloading…下载期间禁用并保持菜单不关闭closeMenuOnClick: false。菜单是否渲染由DashCardMenu.shouldRender静态方法把关DashCardMenu.tsx问题不存在、看板不存在、菜单为null、查询为内部查询Audit V1 场景时均不渲染并且只有当“可编辑问题 / 可下载结果 / 有底层问题子菜单”三者之一成立时才显示。这些细节解释了为什么withDownloads: false加上withEditLink: false并清空customItems后整张卡片的省略号按钮都会消失——因为此时没有任何可展示的动作。总结与进一步阅读DashboardCardMenu是 Metabase Embedding SDK 中“看板卡片溢出菜单”的唯一类型入口配置对象形态DashboardCardCustomMenuItem适合对内置菜单做增量定制用withDownloads/withEditLink开关默认动作用customItems追加自定义项对象或基于{ question }的动态函数自定义元素形态DashboardCardMenuCustomElement适合彻底替换菜单 UI直接返回任意ReactNode两者通过plugins.dashboard.dashboardCardMenu挂载组件级配置优先于MetabaseProvider全局配置且仅限 React SDK 使用。想继续深入了解可查阅以下仓库内资料插件使用文档docs/embedding/dashboard.md、docs/embedding/dashboard-reference.md可运行示例代码docs/embedding/sdk/snippets/dashboards/plugins.tsx类型定义源码frontend/src/metabase/embedding-sdk/types/plugins.ts菜单实现源码DashCardMenu.tsx、DashCardMenuItems.tsx单元测试Dashcard.unit.spec.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），仅供参考