Metabase Embedding SDK StaticDashboard 组件 Props 完全指南：从属性详解到嵌入实战

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 SDK（@metabase/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，所有属性均为可选（?后缀），可按需组合：

三、基础属性：如何指定要嵌入的仪表盘

3.1 dashboardId：数字 ID 与 entity_id 字符串 ID

dashboardId是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提供了一系列布尔开关用于控制界面元素的显隐，这是快速调整嵌入体验最常用的手段：

仓库 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 与 onLoadWithoutCards

• onLoad：仪表盘加载完成时触发，回调参数为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 与 plugins

• dataPickerProps：类型为Pick<SdkQuestionProps, "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 | null）；
• InteractiveDashboardProps额外提供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} className="my-embedded-dashboard" style={{ borderRadius: 8, overflow: "hidden" }} /> </MetabaseProvider> ); }

该示例演示了：

1. 指定仪表盘：通过dashboardId（数字或entity_id字符串）；
2. 预置参数：initialParameters在挂载时应用，配合hiddenParameters隐藏控件、精简界面；
3. 事件感知：onParametersChange区分initial-state/manual-change/auto-change，onLoad获取仪表盘元信息；
4. 界面控制：withTitle/withCardTitle/withDownloads/withSubscriptions精确控制元素显隐，className+style定制外观；
5. 数据保鲜：autoRefreshInterval={60}实现每分钟自动刷新。

如需自定义加载与错误状态，可参考仓库 customizing-loader-and-components.tsx 示例：在MetabaseProvider上通过loaderComponent与errorComponent注入自定义的加载动画与错误提示 UI，StaticDashboard会自动使用这些组件。

十、安全与最佳实践小结

1. 前端过滤 ≠ 安全过滤：切勿用initialParameters/parameters+hiddenParameters在客户端隐藏敏感数据，数据访问控制必须依赖 Metabase 服务端的行级权限与用户认证；
2. 优先使用entity_id：在嵌入代码中长期引用仪表盘时，使用entity_id字符串比数字 ID 更稳定；
3. 受控参数需配对：使用parameters时必须同时使用onParametersChange保持状态同步，否则用户编辑会被下一次渲染覆盖；
4. 按场景选择组件：展示型场景用StaticDashboard，需要钻取与交互分析时升级到InteractiveDashboard（属性可平滑迁移）；
5. 访客嵌入使用 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