Metabase Embedding SDK StaticDashboard 组件 Props 完全指南从属性详解到嵌入实战【免费下载链接】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 开源仓库 StaticDashboardProps 文档 为主体系统讲解 Embedding SDK 中StaticDashboard轻量级仪表盘组件的全部 19 个 Props 属性并结合仓库中的类型定义、真实示例代码与InteractiveDashboard的对照帮助你在 React 宿主应用中快速、安全、可定制地嵌入只读仪表盘并掌握参数过滤、事件回调与外观控制的完整用法。一、StaticDashboard 是什么轻量只读的嵌入式仪表盘在 Metabase Embedding SDKmetabase/embedding-sdk-react中仪表盘组件分为两个层次StaticDashboard轻量级仪表盘组件专注于「把仪表盘原样呈现出来」适合展示型场景。InteractiveDashboard带钻取drill-down、点击行为click behaviors以及查看/点进问题question能力的完整交互式仪表盘适合需要用户深入分析数据的场景。从 StaticDashboard 组件签名 可以看到其极简接口function StaticDashboard(props: StaticDashboardProps): Element;组件接收唯一的props参数并返回一个 ReactElement。而StaticDashboardProps的全部属性定义正是本文要逐项拆解的核心内容。一个最小的完整用法来自仓库 static-dashboard.tsx 示例import React from react; import { MetabaseProvider, StaticDashboard, defineMetabaseAuthConfig, } from metabase/embedding-sdk-react; const authConfig defineMetabaseAuthConfig({ metabaseInstanceUrl: https://your-metabase.example.com, }); export default function App() { const dashboardId 1; // This is the dashboard ID you want to embed return ( MetabaseProvider authConfig{authConfig} StaticDashboard dashboardId{dashboardId} withTitle{true} / /MetabaseProvider ); }StaticDashboard必须作为MetabaseProvider的子组件使用认证配置由外层 Provider 统一提供。二、StaticDashboardProps 全属性速查表以下属性表完整继承自 StaticDashboardProps.md所有属性均为可选?后缀可按需组合属性类型说明autoRefreshInterval?number仪表盘自动刷新的时间间隔单位秒。className?string追加到根元素上的自定义 CSS 类名。dashboardId?SdkDashboardId|null仪表盘 ID。可以是访问仪表盘链接时的数字 ID例如http://localhost:3000/dashboard/1-my-dashboard中的1也可以是直接调用 API 或通过 SDK Collection Browser 返回数据时仪表盘对象entity_id字段中的字符串 ID。dataPickerProps?PickSdkQuestionProps, entityTypes当在仪表盘上新建问题时透传给由InteractiveQuestion渲染的查询构建器的额外属性。hiddenParameters?string[]需要隐藏的参数列表。⚠️ 将initialParameters/parameters与hiddenParameters组合用于「前端过滤数据」存在安全风险仅用于「精简界面」则没有问题。initialParameters?ParameterValues查询参数的初始值按参数 slug 键控。仅在挂载时应用一次之后用户在组件内对控件的修改不会回传给宿主应用。每个参数设置为值单选为字符串、多选为字符串数组则应用该值设置为null则严格清除忽略参数默认值省略或设为undefined则回退到参数默认值无默认值则为null。onLoad?(dashboard: MetabaseDashboard \| null) void仪表盘加载完成时触发的回调。onLoadWithoutCards?(dashboard: MetabaseDashboard \| null) void仪表盘在没有卡片的情况下加载完成时触发的回调。onParametersChange?(payload: ParameterChangePayload) void参数变化时触发。payload 中的source字段用于区分加载时的初始状态initial-state、用户在界面中的手动修改manual-change、以及自动更新auto-change。onVisualizationChange?(visualization: object \| table \| bar \| line \| pie \| scalar \| row \| area \| combo \| pivot \| smartscalar \| gauge \| progress \| funnel \| map \| scatter \| boxplot \| waterfall \| sankey \| treemap \| list) void当从仪表盘卡片打开某个问题或用户修改了某个问题的可视化类型时触发。parameters?ParameterValues受控参数值按 slug 键控。每次渲染时该对象会整体替换仪表盘的参数值设置为值的参数使用该值设置为null的参数被清除即使它有默认值从对象中省略或设为undefined的参数使用其默认值无默认值则为null。建议与onParametersChange配合使用以保持与用户编辑同步。⚠️ 与hiddenParameters组合做前端数据过滤存在安全风险仅用于精简界面则没问题。plugins?MetabasePluginsConfig用于覆盖或新增钻取菜单的 mapper 函数配置。style?CSSProperties应用到根元素的自定义样式对象。token?string \| null用于访客嵌入guest embed的有效 JWT 令牌。withCardTitle?boolean仪表盘卡片是否显示标题。withDownloads?boolean是否隐藏下载按钮。withSubscriptions?boolean是否显示订阅subscriptions按钮。withTitle?boolean仪表盘是否显示标题。三、基础属性如何指定要嵌入的仪表盘3.1 dashboardId数字 ID 与 entity_id 字符串 IDdashboardId是StaticDashboard中语义上最核心的属性。其类型SdkDashboardId定义如下type SdkDashboardId number | string | SdkEntityId;其中SdkEntityId是一个带标签的字符串类型type SdkEntityId string {};文档明确给出了两种获取方式数字 ID直接取自仪表盘访问链接。例如http://localhost:3000/dashboard/1-my-dashboard中斜杠后的第一个数字1即为该仪表盘的数字 ID字符串 ID取自仪表盘对象中的entity_id字段可通过直接调用 Metabase API或使用 SDK 的 Collection Browser 组件返回数据时获得。从 MetabaseDashboard 类型 可以看到仪表盘实体的id与entity_id同时存在type MetabaseDashboard { collection?: MetabaseCollection | null; created_at: string; description: string | null; entity_id: SdkEntityId; id: SdkDashboardId; last-edit-info: { email: string; first_name: string; id: number; last_name: string; timestamp: string; }; name: string; updated_at: string; };使用entity_id的好处是当仪表盘被迁移、导入导出或跨环境同步时数字 ID 可能发生变化而entity_id保持稳定更利于在嵌入代码中做长期引用。3.2 token访客嵌入的 JWT 令牌token属性接受string | null用于访客嵌入guest embed场景下的 JWT 认证。当你的嵌入方案采用「为每个终端用户签发专属 JWT」的方式时可将其传入组件采用MetabaseProvider统一配置认证信息时通常无需显式传入。四、外观与行为控制title、downloads、subscriptions 与样式StaticDashboard提供了一系列布尔开关用于控制界面元素的显隐这是快速调整嵌入体验最常用的手段属性作用withTitle是否显示仪表盘的整体标题withCardTitle是否显示仪表盘内各卡片的标题withDownloads是否隐藏下载按钮注意语义为true时隐藏下载withSubscriptions是否显示订阅按钮仓库 interactive-dashboard.tsx 示例 展示了典型组合用法InteractiveDashboard dashboardId{dashboardId} initialParameters{initialParameters} withTitle{false} withDownloads{false} hiddenParameters{hiddenParameters} /此外还有两类通用样式属性className追加到根元素的自定义 CSS 类名适合配合全局样式表做统一定制style直接传入 React 的CSSProperties样式对象适合内联微调。两者都作用于组件根元素。需要注意的是StaticDashboard本身的尺寸控制更推荐通过包裹容器的布局实现如需精确控制高度可参考仓库中 custom-height.tsx 示例 的做法该示例基于EditableDashboard但style的使用方式一致EditableDashboard style{{ height: 800, minHeight: auto, }} dashboardId{dashboardId} /五、参数控制initialParameters、parameters 与 hiddenParameters仪表盘参数Dashboard Parameters是嵌入式分析的核心交互入口。StaticDashboardProps提供了三个相互配合的参数属性。5.1 ParameterValues 类型initialParameters与parameters都使用ParameterValues类型其定义如下type ParameterValues Record string, | string | number | boolean | (string | number | boolean | null)[] | null | undefined ;即一个以参数 slug 为键、值为标量或标量数组的对象。单个值对应单选参数字符串数组对应多选参数。5.2 initialParameters一次性初始值initialParameters在组件挂载时应用一次之后用户在组件内对参数控件的编辑不会回传给宿主应用。文档明确了三种取值语义设置为一个值单选为string多选为string[]应用该值设置为null严格清除该参数忽略其默认值省略或显式设为undefined回退到该参数的默认值若参数本身无默认值则为null。典型场景打开仪表盘时预置一个默认筛选条件如默认地区、默认时间范围同时允许用户后续自行调整。5.3 parameters受控参数与initialParameters不同parameters是受控属性在每次渲染时该对象会整体替换仪表盘的参数值。因此它必须配合onParametersChange使用才能与用户在界面上的编辑保持同步——即典型的「受控组件」模式宿主保存参数状态通过parameters下发用户在 SDK 界面修改后通过onParametersChange回调更新宿主状态形成闭环。5.4 hiddenParameters隐藏界面控件hiddenParameters接收一组参数名slug用于隐藏对应的参数控件。典型用途是把某个参数作为「隐含条件」固定下来或精简界面。⚠️安全警告文档原话强调将initialParameters/parameters与hiddenParameters组合起来在前端过滤数据是一种安全风险——因为隐藏的参数值仍可通过请求被篡改前端过滤永远不能替代服务端权限控制。仅将这种组合用于「精简用户界面」才是安全的。5.5 通过 onParametersChange 感知参数变化ParameterChangePayload定义了回调的载荷结构type ParameterChangePayload { defaultParameters: ParameterValues; lastUsedParameters: ParameterValues; parameters: ParameterValues; source: ParameterChangeSource; };其中ParameterChangeSource用于区分事件来源type ParameterChangeSource initial-state | manual-change | auto-change;initial-state加载时首次应用的快照每次仪表盘加载触发一次manual-change用户在界面中编辑参数auto-change自动更新场景例如将规范化后的值回传给父组件。通过source字段宿主应用可以精确区分「初始值、用户手动修改、自动更新」三类事件从而决定是否将参数同步到宿主状态避免不必要的重渲染或循环更新。5.6 autoRefreshInterval自动刷新autoRefreshInterval以秒为单位设置仪表盘的自动刷新间隔。仓库 dashboard-auto-refresh.tsx 示例 展示了最简单的用法InteractiveDashboard dashboardId{dashboardId} autoRefreshInterval{60} /即每 60 秒自动刷新一次。StaticDashboard同样支持该属性适合大屏监控、实时运营看板等数据会持续更新的场景。六、生命周期与事件回调6.1 onLoad 与 onLoadWithoutCardsonLoad仪表盘加载完成时触发回调参数为MetabaseDashboard对象或null。可用于埋点、记录加载耗时、联动外部状态等onLoadWithoutCards仪表盘在没有卡片即空仪表盘或卡片加载失败被过滤的情况下加载完成时触发。可用于识别「空仪表盘」这一特殊状态并给出提示。6.2 onVisualizationChange当从仪表盘卡片打开某个问题或用户修改某个问题的可视化类型时触发。回调参数为 21 种可视化类型的联合字符串object | table | bar | line | pie | scalar | row | area | combo | pivot | smartscalar | gauge | progress | funnel | map | scatter | boxplot | waterfall | sankey | treemap | list宿主应用可根据当前可视化类型动态调整周边 UI如切换说明文案、展示对应图例等。七、高级扩展dataPickerProps 与 pluginsdataPickerProps类型为PickSdkQuestionProps, entityTypes用于在仪表盘内新建问题走InteractiveQuestion渲染的查询构建器时透传数据选择器的额外配置例如限定可选的实体类型范围plugins类型为MetabasePluginsConfig用于扩展钻取菜单等行为type MetabasePluginsConfig { dashboard?: MetabaseDashboardPluginsConfig; mapQuestionClickActions?: MetabaseClickActionPluginsConfig; };其中dashboard配置仪表盘维度的自定义菜单项mapQuestionClickActions用于覆盖或新增地图类问题卡片的点击动作drill-down。具体实现方式可参考仓库 plugins.tsx 示例 与文档 plugins.md。八、结合 InteractiveDashboardProps 理解属性家族StaticDashboardProps与InteractiveDashboardProps共享绝大部分属性autoRefreshInterval、className、dataPickerProps、hiddenParameters、initialParameters、onLoad、onLoadWithoutCards、onParametersChange、onVisualizationChange、parameters、plugins、style、token、withCardTitle、withDownloads、withSubscriptions、withTitle主要差异在于InteractiveDashboardProps的dashboardId为必填string | number而StaticDashboardProps中为可选SdkDashboardId | nullInteractiveDashboardProps额外提供drillThroughQuestionHeight、drillThroughQuestionProps、renderDrillThroughQuestion、enableEntityNavigation等与「点击钻取到问题详情」相关的属性这是其交互性的来源。因此当你从StaticDashboard升级到InteractiveDashboard时现有的大多数属性参数控制、外观开关、事件回调都可以无缝迁移只需再补充钻取相关的配置。九、组合实战一个完整的静态仪表盘嵌入方案综合以上属性一个兼顾外观精简、参数预置、事件感知与自动刷新的完整示例整合自仓库多个 snippets 示例import React, { useCallback, useState } from react; import { MetabaseProvider, StaticDashboard, defineMetabaseAuthConfig, } from metabase/embedding-sdk-react; const authConfig defineMetabaseAuthConfig({ metabaseInstanceUrl: https://your-metabase.example.com, }); export default function App() { const dashboardId 1; // 或使用仪表盘对象中的 entity_id 字符串 // 挂载时应用一次按 slug 键控 const initialParameters { region: North }; // 隐藏界面上的参数控件仅用于精简界面勿用于前端数据过滤 const hiddenParameters [region]; // 感知参数变化来源 const handleParametersChange useCallback((payload) { console.log(source:, payload.source); console.log(current:, payload.parameters); }, []); const handleLoad useCallback((dashboard) { if (dashboard) { console.log(Dashboard loaded:, dashboard.name); } }, []); return ( MetabaseProvider authConfig{authConfig} StaticDashboard dashboardId{dashboardId} initialParameters{initialParameters} hiddenParameters{hiddenParameters} onParametersChange{handleParametersChange} onLoad{handleLoad} autoRefreshInterval{60} withTitle{true} withCardTitle{false} withDownloads{false} withSubscriptions{false} classNamemy-embedded-dashboard style{{ borderRadius: 8, overflow: hidden }} / /MetabaseProvider ); }该示例演示了指定仪表盘通过dashboardId数字或entity_id字符串预置参数initialParameters在挂载时应用配合hiddenParameters隐藏控件、精简界面事件感知onParametersChange区分initial-state/manual-change/auto-changeonLoad获取仪表盘元信息界面控制withTitle/withCardTitle/withDownloads/withSubscriptions精确控制元素显隐classNamestyle定制外观数据保鲜autoRefreshInterval{60}实现每分钟自动刷新。如需自定义加载与错误状态可参考仓库 customizing-loader-and-components.tsx 示例在MetabaseProvider上通过loaderComponent与errorComponent注入自定义的加载动画与错误提示 UIStaticDashboard会自动使用这些组件。十、安全与最佳实践小结前端过滤 ≠ 安全过滤切勿用initialParameters/parametershiddenParameters在客户端隐藏敏感数据数据访问控制必须依赖 Metabase 服务端的行级权限与用户认证优先使用entity_id在嵌入代码中长期引用仪表盘时使用entity_id字符串比数字 ID 更稳定受控参数需配对使用parameters时必须同时使用onParametersChange保持状态同步否则用户编辑会被下一次渲染覆盖按场景选择组件展示型场景用StaticDashboard需要钻取与交互分析时升级到InteractiveDashboard属性可平滑迁移访客嵌入使用 JWT需要为每个终端用户隔离数据时通过token或认证配置传入各自有效的 JWT。通过上述属性与示例你可以将 Metabase 仪表盘以只读、可定制、参数可控制的方式无缝嵌入到任意 React 应用中实现「数据展示在自家产品内」的完整闭环。【免费下载链接】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），仅供参考