Metabase 模块化嵌入 SDK 插件配置MetabasePluginsConfig完整指南类型定义、作用域与实践示例【免费下载链接】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 开源仓库中 MetabasePluginsConfig 类型参考文档 为核心系统讲解模块化嵌入 SDKModular embedding SDK的插件配置体系如何通过dashboard与mapQuestionClickActions两个插槽定制嵌入式仪表盘与图表的交互行为如何区分全局插件与组件级插件的使用边界以及handleLink、getNoDataIllustration等全局扩展插件。读完本文你将能够熟练使用MetabaseProvider的pluginsConfig属性与各组件InteractiveQuestion、InteractiveDashboard的plugins属性为嵌入应用注入自定义点击菜单、自定义仪表盘卡片菜单、自定义空态插画与链接拦截逻辑。一、插件机制与作用域全局还是组件级Metabase 模块化嵌入 SDK即metabase/embedding-sdk-react提供了一套 React 组件MetabaseProvider、InteractiveQuestion、InteractiveDashboard等让开发者把 Metabase 的分析能力嵌入自己的应用。插件plugins是这套 SDK 的扩展点用于改写组件的默认行为例如用户点击图表数据点时弹出什么菜单仪表盘卡片右上角菜单里有哪些操作项点击嵌入内容中的链接时如何处理查询无结果或搜索无对象时展示什么插画。根据官方指南 plugins.md 的说明插件有两种挂载方式全局插件挂在MetabaseProvider的pluginsConfig属性上作用于其下所有嵌入组件组件级插件通过组件的plugins属性传入只作用于该组件实例如某个InteractiveQuestion或InteractiveDashboard。全局插件的最小示例来自 global-plugins.tsximport type { PropsWithChildren } from react; import { type MetabaseAuthConfig, MetabaseProvider, type MetabaseTheme, } from metabase/embedding-sdk-react; const authConfig {} as MetabaseAuthConfig; const theme {} as MetabaseTheme; const Example ({ children }: PropsWithChildren) ( MetabaseProvider authConfig{authConfig} theme{theme} pluginsConfig{{ mapQuestionClickActions: () [], // Add your custom actions here }} {children} /MetabaseProvider );组件级插件的最小示例来自 component-plugins.tsximport { InteractiveQuestion } from metabase/embedding-sdk-react; const Example () ( InteractiveQuestion questionId{1} plugins{{ mapQuestionClickActions: () [], }} / );注意作用域差异mapQuestionClickActions既可以全局使用也可以组件级使用而handleLink、getNoDataIllustration、getNoObjectIllustration只能在 Provider 层级全局使用详见后文。二、MetabasePluginsConfig 类型定义与属性MetabasePluginsConfig.md 给出了该类型的完整定义type MetabasePluginsConfig { dashboard?: MetabaseDashboardPluginsConfig; mapQuestionClickActions?: MetabaseClickActionPluginsConfig; };属性一览属性类型说明dashboard?MetabaseDashboardPluginsConfig仪表盘相关插件的配置集合目前包含仪表盘卡片菜单dashboardCardMenu定制mapQuestionClickActions?MetabaseClickActionPluginsConfig拦截并改写点击图表/仪表盘卡片数据点后弹出的操作菜单的回调类型在代码库中的真实定义该类型并非文档虚构其真实定义位于源码 frontend/src/metabase/embedding-sdk/types/plugins.tsexport type MetabasePluginsConfig { mapQuestionClickActions?: MetabaseClickActionPluginsConfig; dashboard?: MetabaseDashboardPluginsConfig; };可以看到SDK 源码与文档中的类型完全一致MetabasePluginsConfig是贯穿 Provider 与各组件插槽的统一类型。此外MetabaseGlobalPluginsConfig.md 表明Provider 级全局配置类型是在MetabasePluginsConfig基础上扩展而来的type MetabaseGlobalPluginsConfig MetabasePluginsConfig { getNoDataIllustration?: () string | null | undefined; getNoObjectIllustration?: () string | null | undefined; handleLink?: (url: string) { handled: boolean; }; };即MetabasePluginsConfig是组件插件配置与全局插件配置共同的基底MetabaseProvider的pluginsConfig属性类型见 MetabaseProviderProps.md接受扩展后的MetabaseGlobalPluginsConfig。三、dashboard 插槽定制仪表盘卡片菜单dashboard插槽的类型为MetabaseDashboardPluginsConfig见 MetabaseDashboardPluginsConfig.mdtype MetabaseDashboardPluginsConfig { dashboardCardMenu?: DashboardCardMenu; };属性类型说明dashboardCardMenu?DashboardCardMenu仪表盘卡片dashboard card右上角菜单的定制配置3.1 DashboardCardMenu 的两种形态DashboardCardMenu.md 定义了dashboardCardMenu的联合类型type DashboardCardMenu | DashboardCardMenuCustomElement | DashboardCardCustomMenuItem;即它可以是菜单项配置对象也可以是返回自定义 React 元素的函数。形态一菜单项配置对象DashboardCardCustomMenuItem.mdtype DashboardCardCustomMenuItem { customItems?: (DashCardMenuItem | CustomDashboardCardMenuItem)[]; withDownloads?: boolean; withEditLink?: boolean; };属性类型说明customItems?(DashCardMenuItem|CustomDashboardCardMenuItem)[]追加的自定义菜单项列表withDownloads?boolean是否保留默认的下载操作withEditLink?boolean是否保留默认的编辑链接其中单个菜单项DashCardMenuItem见 DashCardMenuItem.md的结构如下type DashCardMenuItem { children?: ReactNode; closeMenuOnClick?: boolean; color?: MantineColor; disabled?: boolean; iconName: IconName; label: string; leftSection?: ReactNode; onClick: () void; rightSection?: ReactNode; };字段要点iconName图标名必填与label菜单文本必填是核心onClick为点击回调color可以是theme.colors的键或任意合法 CSS 颜色closeMenuOnClick可覆盖 Menu 组件的closeOnItemClick行为disabled用于置灰禁用。CustomDashboardCardMenuItem则是一个工厂函数形态它接收{ question }其中question可选类型为 MetabaseQuestion包含id、name、entityId、description、isSavedQuestion等字段返回一个DashCardMenuItem从而可以根据当前卡片的问题动态生成菜单项type CustomDashboardCardMenuItem ({ question, }: { question?: MetabaseQuestion; }) DashCardMenuItem;形态二自定义菜单元素DashboardCardMenuCustomElement.mdtype DashboardCardMenuCustomElement ({ question, }: { question: MetabaseQuestion; }) ReactNode;传入一个接收{ question }并返回ReactNode的函数即可用你自己的组件整体替换默认菜单。3.2 完整示例从开关默认项到自定义菜单官方示例 dashboards/plugins.tsx 覆盖了全部用法。保留默认下载与编辑入口仅追加空的自定义列表InteractiveDashboard dashboardId{1} plugins{{ dashboard: { dashboardCardMenu: { withDownloads: true, withEditLink: true, customItems: [], }, }, }} /关闭默认操作去掉下载与编辑入口const plugins { dashboard: { dashboardCardMenu: { withDownloads: false, withEditLink: false, customItems: [], }, }, };追加自定义菜单项静态对象与基于 question 的动态工厂均可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}); }, }; }, ], }, }, };用自定义 React 元素整体替换菜单const plugins: MetabasePluginsConfig { dashboard: { dashboardCardMenu: ({ question }) ( button onClick{() console.log(question.name)}Click me/button ), }, };关于仪表盘卡片菜单的更多上下文可参考 dashboard.md 中的 Customize the menu on dashboard cards 一节。四、mapQuestionClickActions 插槽改写图表点击行为mapQuestionClickActions让你完全控制用户点击图表/仪表盘卡片数据点后发生了什么。官方文档 chart.md 对应小节 明确指出它有三种能力——保留默认菜单、追加自定义操作、或直接执行一个即时操作而不弹出菜单。4.1 回调签名类型定义见 MetabaseClickActionPluginsConfig.mdtype MetabaseClickActionPluginsConfig ( clickActions: MetabaseClickAction[], clickedDataPoint: MetabaseDataPointObject, ) | MetabaseClickAction[] | { onClick: () void; };参数类型说明clickActionsMetabaseClickAction[]Metabase 默认渲染的点击操作列表可在此基础上增删clickedDataPointMetabaseDataPointObject被点击数据点的上下文信息返回值三种形态返回MetabaseClickAction[]替换菜单中的操作列表可包含默认操作也可完全自定义返回{ onClick: () void }不弹出菜单直接执行即时操作从源码与示例看返回原clickActions等价于保持默认行为。其中MetabaseClickAction见 MetabaseClickAction.md是一个以name为必填键的开放对象type MetabaseClickAction { name: string; } Recordstring, any;这意味着你可以自由附加buttonType、title、section、type、icon、onClick、view等字段来定制菜单项的外观与行为。MetabaseDataPointObject见 MetabaseDataPointObject.md则提供了丰富的数据点上下文column列名name与显示名display_name、data整行数据、value单元格值、event原生鼠标事件、question所属问题、以及包含原始列/值信息的raw结构。4.2 实战示例按列定制点击行为来自 interactive-question-click-actions.tsx 的完整示例演示了三种分支MetabaseProvider authConfig{authConfig} pluginsConfig{{ mapQuestionClickActions: (clickActions, clicked) { if (clicked?.column?.display_name Last Name) { // 在菜单中追加一个自定义操作 return [ ...clickActions, { buttonType: horizontal, name: custom, title: This is the Last Name column, onClick: () alert(You clicked the Last Name column!), }, ]; } if (clicked?.column?.display_name Plan) { // 不弹菜单直接执行即时操作 return { onClick: () alert(You clicked the Plan column!), }; } // 其他列保持 Metabase 默认点击菜单 return clickActions; }, }} InteractiveQuestion questionId{1} / /MetabaseProvider4.3 进阶自定义操作的外观如果你希望自定义操作以完全自定义的 UI 呈现可以在操作对象中使用view字段渲染任意 React 元素。来自 interactive-question-plugins.tsx 的示例展示了两种自定义外观// 提供带自定义 onClick 的普通自定义操作 const createCustomAction (clicked) ({ buttonType: horizontal, name: client-custom-action, section: custom, type: custom, icon: chevronright, title: Hello from the click app!!!, onClick: ({ closePopover }) { alert(Clicked ${clicked.column?.name}: ${clicked.value}); closePopover(); }, }); // 或用 view 渲染自定义元素 const createCustomActionWithView (clicked) ({ name: client-custom-action-2, section: custom, type: custom, view: ({ closePopover }) ( button classNametw-text-base tw-text-yellow-900 tw-bg-slate-400 tw-rounded-lg onClick{() { alert(Clicked ${clicked.column?.name}: ${clicked.value}); closePopover(); }} Custom element /button ), }); const plugins { /** * 可以拿到 Metabase 默认渲染的 clickActions * 因此你可以决定是追加、删除还是整体替换。 */ mapQuestionClickActions: (clickActions, clicked) { return [ ...clickActions, createCustomAction(clicked), createCustomActionWithView(clicked), ]; }, };提示mapQuestionClickActions同样适用于仪表盘卡片——参见 dashboard.md 中的相关说明。从 SDK 源码 links.ts 的注释可以看出点击行为click behaviors与mapQuestionClickActions是天然协作的关系。五、全局扩展插件链接拦截与空态插画以下三个插件仅存在于MetabaseGlobalPluginsConfig即 Provider 的pluginsConfig不能作为组件级plugins使用。5.1 handleLink拦截链接点击默认情况下嵌入问题与仪表盘中的链接会在新标签页打开。使用handleLink可以拦截点击将链接交给自己的路由或弹窗处理。完整示例见 handlelink.tsxconst plugins { handleLink: (urlString: string) { const url new URL(urlString, window.location.origin); const isInternal url.origin window.location.origin; if (isInternal) { // 内部导航交给自己的路由处理 console.log(Navigate to:, url.pathname url.search url.hash); return { handled: true }; // 阻止默认导航 } return { handled: false }; // 交给 SDK 默认行为新标签页打开 }, }; return ( MetabaseProvider authConfig{authConfig} pluginsConfig{plugins} InteractiveDashboard dashboardId{1} / /MetabaseProvider );返回{ handled: true }阻止默认导航返回{ handled: false }则保持默认新标签页打开。根据 plugins.md 的说明该插件只能在 Provider 级全局使用且模块化嵌入modular embedding页面级配置中同样可用。若要让表格列里的内容变成可点击链接可将列的格式设置为显示为链接Display as link。5.2 getNoDataIllustration 与 getNoObjectIllustration替换空态插画默认情况下Metabase 在查询无结果时展示一张帆船sailboat插画。这两个插件可替换为自己品牌的图片返回值为 base64 编码的图片字符串。完整示例见 custom-images.tsxconst img_base64 ...; // base64-encoded image const plugins { getNoDataIllustration: () img_base64, getNoObjectIllustration: () img_base64, }; return ( MetabaseProvider authConfig{authConfig} pluginsConfig{plugins} InteractiveDashboard dashboardId{1} / /MetabaseProvider );两个插件的区别详见 loading-and-errors.mdgetNoDataIllustration查询返回 0 行数据时的空态插画getNoObjectIllustration搜索无结果时的空态插画如搜索页、实体选择器无匹配项。两者都只能在 Provider 级全局设置。注意它们与loaderComponent/errorComponent不同——后两者是组件自身的 props而这两个是插件必须放进pluginsConfig。六、源码速查类型定义的一手位置如果你需要在项目中确认类型细节或升级 SDK 后核对行为以下仓库路径是最直接的依据frontend/src/metabase/embedding-sdk/types/plugins.tsMetabasePluginsConfig、MetabaseDashboardPluginsConfig、MetabaseClickActionPluginsConfig、MetabaseDataPointObject、DashCardMenuItem、DashboardCardMenuCustomElement、CustomDashboardCardMenuItem、DashboardCardCustomMenuItem等类型的权威定义docs/embedding/sdk/plugins.md插件机制总览作用域、各插件说明、进一步阅读docs/embedding/sdk/api/snippets/本文涉及的MetabasePluginsConfig、MetabaseDashboardPluginsConfig、MetabaseClickActionPluginsConfig、MetabaseGlobalPluginsConfig、DashboardCardMenu、DashCardMenuItem、MetabaseDataPointObject等 API 参考片段docs/embedding/sdk/snippets/plugins/ 与 docs/embedding/sdk/snippets/questions/、docs/embedding/sdk/snippets/dashboards/可运行的完整示例代码docs/embedding/chart.md图表点击行为定制mapQuestionClickActions的用户文档docs/embedding/dashboard.md仪表盘卡片菜单定制dashboardCardMenu的用户文档docs/embedding/sdk/loading-and-errors.md空态插画替换getNoDataIllustration/getNoObjectIllustration的用户文档。七、小结与决策速查需求插件挂载位置返回/配置形态改写图表/卡片点击菜单mapQuestionClickActionsProvider 全局 或 组件级返回操作数组 /{ onClick }定制仪表盘卡片菜单dashboard.dashboardCardMenu组件级InteractiveDashboard.plugins菜单项配置对象 或 返回 ReactNode 的函数拦截嵌入内容中的链接handleLink仅 Provider 全局{ handled: boolean }替换无数据/无对象插画getNoDataIllustration/getNoObjectIllustration仅 Provider 全局返回 base64 图片字符串的函数在实际项目中建议按全局能力放MetabaseProvider.pluginsConfig单组件行为放组件plugins的原则组织代码所有类型均可从metabase/embedding-sdk-react导入如type MetabasePluginsConfig配合 TypeScript 可获得完整的属性提示与类型校验。掌握MetabasePluginsConfig这一入口类型即可系统性地扩展嵌入体验而无需改动 Metabase 服务端或仓库内部实现。【免费下载链接】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），仅供参考