Metabase 嵌入式分析 SDK 自定义 Dashboard 卡片菜单项CustomDashboardCardMenuItem 类型深入解析【免费下载链接】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 嵌入式分析 SDKEmbedding SDK中用于扩展InteractiveDashboard卡片菜单Dashboard Card Menu的CustomDashboardCardMenuItem类型。该类型允许开发者以函数形式动态生成菜单项并在运行时拿到当前卡片对应的MetabaseQuestion对象。读完本文你将掌握该类型的完整签名、参数与返回值语义、它与普通菜单项DashCardMenuItem的区别以及如何通过MetabasePluginsConfig插件配置将其接入实际嵌入场景。类型定义速览CustomDashboardCardMenuItem是一个返回型函数类型接收包含可选question参数的对象返回一个DashCardMenuItem。其定义位于 dashcard-menu.ts与 API 文档 CustomDashboardCardMenuItem.md 完全对应type CustomDashboardCardMenuItem ({ question, }: { question?: MetabaseQuestion; }) DashCardMenuItem;关键语义它本身不是菜单项而是菜单项工厂——每次渲染时被调用一次产出一个具体的DashCardMenuItemquestion是可选的?后缀但实际运行时 SDK 总会传入当前卡片对应的MetabaseQuestion见下文源码验证返回的DashCardMenuItem必须是完整、合法的菜单项对象label与onClick为必填。参数解析question?与MetabaseQuestion按 API 文档的参数表该函数类型只有一组参数参数类型说明{ question, }{ question?: MetabaseQuestion }解构自函数的入参对象{ question, }.question?MetabaseQuestion当前卡片所对应的问题可选MetabaseQuestion是该 SDK 对外暴露的、只读摘要版问题对象属性如下见 MetabaseQuestion.md属性类型含义descriptionstring \| null问题描述entityIdstring实体唯一标识idnumber问题 IDisSavedQuestionboolean是否为已保存问题namestring问题名称在自定义菜单回调里最常用的就是question.name用于展示与question.id用于跳转或埋点。返回值DashCardMenuItem属性全解函数必须返回一个DashCardMenuItem其完整属性如下属性类型必填说明labelstring✅菜单项显示文本iconNameIconName✅图标名称onClick() void✅点击处理函数children?ReactNode❌子节点内容closeMenuOnClick?boolean❌点击后是否关闭菜单覆盖Menu组件的closeOnItemClickcolor?MantineColor❌theme.colors的键或任意合法 CSS 颜色disabled?boolean❌禁用该菜单项leftSection?ReactNode❌标签左侧区域rightSection?ReactNode❌标签右侧区域label、iconName、onClick为必填项其余均可选。若需要在点击时保持菜单展开例如触发下载中状态可设置closeMenuOnClick: false。源码验证函数式菜单项如何被调用在 SDK 运行时自定义菜单项在 DashCardMenuItems.tsx 中被渲染if (customItems) { items.push( ...customItems.map((item) { const customItem typeof item function ? item({ question: transformSdkQuestion(question) }) : item; return { ...customItem, key: MB_CUSTOM_${customItem.label}, }; }), ); }从源码结构可以看到两个重要实现事实类型判别customItems数组里的元素既可以是普通对象DashCardMenuItem也可以是函数CustomDashboardCardMenuItem。SDK 通过typeof item function判断——是函数则调用它并传入{ question }否则原样使用question 的来源传入函数的是transformSdkQuestion(question)的结果即内部Question对象经过 SDK 转换后得到的MetabaseQuestion只读视图。因此回调中question.name、question.id等字段始终可用question?的可选标记仅为类型层面的保守声明。每个自定义项还会被注入唯一keyMB_CUSTOM_${label}并在 DashCardMenu.tsx 中随下载结果“编辑问题”等内置项一同渲染为 MantineMenu.Item左侧自动渲染iconName图标。接入方式通过插件配置启用CustomDashboardCardMenuItem不是单独使用的它作为DashboardCardCustomMenuItem.customItems数组的元素之一挂在InteractiveDashboard的plugins.dashboard.dashboardCardMenu上。类型装配关系定义在 dashcard-menu.ts 与 plugins.tstype DashboardCardCustomMenuItem { withDownloads?: boolean; withEditLink?: boolean; customItems?: (DashCardMenuItem | CustomDashboardCardMenuItem)[]; }; type DashboardCardMenu | DashboardCardMenuCustomElement // 整个菜单替换为自定义元素 | DashboardCardCustomMenuItem; // 保留默认菜单并在其中追加/配置自定义项相关配置字段字段类型说明withDownloadsboolean是否保留下载结果内置菜单项默认truewithEditLinkboolean是否保留编辑内置菜单项默认truecustomItems(DashCardMenuItem \| CustomDashboardCardMenuItem)[]追加的自定义菜单项支持静态对象或函数两种形态完整实战示例以下示例来自官方文档代码片段 plugins.tsx演示如何同时使用静态对象与函数式菜单项import { InteractiveDashboard, type MetabasePluginsConfig, } from metabase/embedding-sdk-react; const plugins: MetabasePluginsConfig { dashboard: { dashboardCardMenu: { customItems: [ // 静态菜单项无需感知具体问题 { iconName: chevronright, label: Custom action, onClick: () { alert(Custom action clicked); }, }, // 函数式菜单项动态读取当前卡片对应的问题 ({ question }) { return { iconName: chevronright, label: Custom action, onClick: () { alert(Custom action clicked ${question?.name}); }, }; }, ], }, }, }; export const MyDashboard () ( InteractiveDashboard dashboardId{1} plugins{plugins} / );典型应用场景包括按问题类型动态生成菜单根据question.isSavedQuestion决定展示查看详情还是保存为收藏携带问题元数据跳转在onClick中使用question.id触发自有业务逻辑如打开外部报表系统与默认菜单共存保持withDownloads/withEditLink为true只在末尾追加自定义动作。若需完全替换菜单可改用DashboardCardMenuCustomElement即dashboardCardMenu直接传函数返回自定义ReactNode参见 plugins.tsx 中的dashboardCardMenu: ({ question }) button...形态。小结CustomDashboardCardMenuItem是 Metabase 嵌入式分析 SDK 扩展 Dashboard 卡片菜单的动态工厂类型它把当前卡片的MetabaseQuestion注入到菜单生成回调中让开发者可以在不触碰内置菜单的前提下按需产出上下文相关的自定义操作项。使用时牢记三点返回对象必须包含label、iconName、onClickquestion在运行时总是可用customItems中静态对象与函数可以混用。【免费下载链接】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），仅供参考