企业官网建设流程全解析

Metabase Embedded Analytics SDK：StaticDashboard 轻量仪表盘组件 API 实战解析

【免费下载链接】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

StaticDashboard是 Metabase 嵌入式分析 SDK（@metabase/embedding-sdk-react）中用于嵌入只读（view-only）仪表盘的 React 组件。本文以其 API 文档为骨架，结合当前仓库源码，完整讲解其函数签名、全部 Props 参数、底层实现原理与最小可运行示例，帮助你在自己的应用中快速接入一个“轻量、无编辑干扰”的嵌入式仪表盘。

组件定位：轻量只读仪表盘

在 SDK API 索引 中，仪表盘家族包含三个组件，职责划分清晰：

官方 Dashboard component reference 明确指出：StaticDashboard嵌入的是仅查看（view-only）仪表盘——一个"轻量组件，只展示结果，不让人与数据交互"。它适合把某个仪表盘当作"只读报表"嵌进你的 SaaS 应用、客户门户或内部工具页。

函数签名与返回值

按 StaticDashboard API 片段，组件签名如下：

function StaticDashboard(props: StaticDashboardProps): Element;

• 参数：单个props对象，类型为StaticDashboardProps（详见下一节）。
• 返回值：React 的Element（即React.ReactElement）。

在 源码实现 中，StaticDashboardProps是通过Omit从SdkDashboardProps派生出来的：

export type StaticDashboardProps = Omit< SdkDashboardProps, | "dashboardId" | "token" | "drillThroughQuestionProps" | "drillThroughQuestionHeight" | "renderDrillThroughQuestion" | "enableEntityNavigation" > & SdkDashboardEntityPublicProps;

也就是说，静态模式屏蔽了下钻相关 Props 与实体导航，从而保证"只读"语义——用户点进卡片后不会进入可编辑的查询构建器（query builder）流程。

完整 Props 参数详解

依据 StaticDashboardProps 文档，StaticDashboard支持的全部属性如下（所有属性均为可选）：

参数语义的关键细节（来自源码）

• dashboardId与token二选一：运行时校验 Schema 规定，当传入token（Guest Embed 场景）时dashboardId变为可选；否则dashboardId必填。
• initialParameters的三种取值语义：设为值（单个选项用字符串、多选用字符串数组）则应用该值；设为null则强制清空（忽略参数默认值）；省略或设为undefined则回退到参数默认值（无默认值则为null）。
• parameters是受控模式：每次渲染整体替换参数值，配合onParametersChange可实现宿主与嵌入仪表盘的双向同步。源码通过useSdkControlledParameters和useWarnConflictingParameterProps处理受控逻辑，并在同时传入initialParameters与parameters时发出告警（见 SdkDashboard.tsx）。
• 安全提示：用hiddenParameters隐藏参数、再用initialParameters/parameters在前端过滤数据，属于安全风险（每个最终用户都应拥有独立的 Metabase 账号才能真正隔离数据）；仅用于"隐藏界面元素、精简 UI"则是允许的。参数过滤必须依赖服务端权限体系（如行级权限、用户隔离），切勿只靠前端隐藏。

最小可运行示例

仓库提供了开箱即用的示例 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> ); }

要点：

1. StaticDashboard必须包裹在MetabaseProvider内，由后者提供认证配置与主题上下文；
2. dashboardId指向你要嵌入的仪表盘 ID（数字 ID 或entity_id字符串均可）；
3. withTitle={true}显式开启仪表盘标题显示；
4. 如需访客嵌入（Guest Embed）场景，改为通过MetabaseProvider传入authType，并在StaticDashboard上直接传入 JWTtoken与对应的dashboardId/token组合。

底层实现：源码级解析

静态模式如何被强制

StaticDashboard的核心实现在 StaticDashboard.tsx，它复用了通用的SdkDashboard，但通过三项"硬约束"收紧交互能力：

<SdkDashboard {...(normalizedProps as SdkDashboardProps)} clickActionMode={staticClickActionMode} // 静态点击模式 dashboardActions={[ DASHBOARD_ACTION.DASHBOARD_SUBSCRIPTIONS, // 仅保留订阅 DASHBOARD_ACTION.DOWNLOAD_PDF, // 仅保留导出 PDF DASHBOARD_ACTION.REFRESH_INDICATOR, // 仅保留刷新指示 ]} navigateToNewCardFromDashboard={null} // 禁用到新卡片的导航 dashcardMenu={({ dashcard, result }) => withDownloads && isQuestionDashCard(dashcard) && !!result?.data && !result?.error && ( <PublicOrEmbeddedDashCardMenu result={result} dashcard={dashcard} /> ) } />

其中staticClickActionMode来自getEmbeddingMode({ queryMode: EmbeddingSdkStaticMode })——从源码结构看，SDK 通过"嵌入模式（embedding mode）"这一抽象来区分静态、交互等不同交互层级，静态模式即对应EmbeddingSdkStaticMode。同时navigateToNewCardFromDashboard={null}直接禁用了从仪表盘卡片跳转到新卡片的导航能力，这是"只读"语义在实现层面的落地。

下载菜单的条件渲染

从上面代码可见，卡片菜单（dashcardMenu）仅在同时满足withDownloads、卡片是问题卡片（isQuestionDashCard）、有数据且无错误时才渲染PublicOrEmbeddedDashCardMenu，否则不显示下载入口。这也解释了 Props 表中withDownloads的默认行为。

与 SdkDashboard 的关系

StaticDashboard是SdkDashboard（源码）的"裁剪版"。SdkDashboard内部还处理了：

• Guest Embed 令牌管理：通过useExtractResourceIdFromJwtToken从 JWT 中提取resourceId（即被嵌入的仪表盘 ID），并用mountId隔离同一MetabaseProvider下多个 Guest 组件的令牌；
• 加载/错误状态：语言包加载中显示SdkLoader；令牌错误、静态嵌入实体加载错误、404/400（仪表盘不存在）分别渲染SdkError或DashboardNotFoundError；
• 自动刷新：AutoRefreshController把autoRefreshInterval（秒）同步到仪表盘上下文的刷新周期，组件卸载时自动复位；
• 样式包装：MaybeStyledWrapper仅在非内部导航栈场景下包一层SdkDashboardStyledWrapper，避免二次包裹丢失高度/粘性/滚动行为。

运行时 Props 校验

StaticDashboard通过Object.assign(withPublicComponentWrapper(StaticDashboardInner, { supportsGuestEmbed: true }), { schema: staticDashboardSchema })导出。其schema由 StaticDashboard.schema.ts 定义，使用 Yup 对象校验所有 Props 并启用.noUnknown()——传入未知属性会被拒绝，这是 SDK 保证组件 API 稳定的一种手段，也解释了为什么 Props 集合必须与文档严格一致。

与 Web Component 的对照

如果你不使用 React，也可以使用等价的<metabase-dashboard>Web Component。两者共享大部分外观与行为参数（如with-*开关、参数隐藏列表），区别在于 Web Component 用 HTML 属性表达、值需字符串化（涉及布尔值时需true/false字符串），而 React SDK 直接传 Props，详见 Dashboard component reference 与 Embed a dashboard。

常见使用场景与建议

• 客户门户 / 只读报表页：把StaticDashboard嵌进产品内部页面，用户只读数据、不能误改布局，天然避免脏数据与误操作；
• 移动端或低带宽场景：相比InteractiveDashboard，静态模式禁用了下钻与查询构建器，从源码看渲染路径更短（navigateToNewCardFromDashboard={null}直接剪掉卡片导航分支），适合追求"轻量"的嵌入场景；
• 参数化筛选：仪表盘本身带筛选器时，用hiddenParameters精简界面、用initialParameters/parameters从宿主传入业务上下文（如当前登录用户对应的筛选值），但务必牢记：真正的数据权限必须由服务端保证；
• 交互升级路径：当只读仪表盘需要下钻、点击行为时，把StaticDashboard换成InteractiveDashboard即可，两者 Props 高度重合，迁移成本低。

参考链接

• API 片段：StaticDashboard、StaticDashboardProps
• 完整组件参考：Dashboard component reference
• 嵌入教程：Embed a dashboard
• 可运行示例：static-dashboard.tsx
• 源码实现：StaticDashboard.tsx、SdkDashboard.tsx、StaticDashboard.schema.ts

【免费下载链接】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