企业官网建设流程全解析

Metabase 模块化嵌入参数传递实战：initialParameters、sqlParameters 与控制/非控制模式详解

【免费下载链接】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 官方文档 Modular embedding parameters，完整讲解如何通过 React SDK 的 props 与 Web Components 的属性/属性 API，向嵌入的 Dashboard 和 SQL 问题传递参数值，涵盖非控制（uncontrolled）与控制（controlled）两种同步模式、参数值解析规则（置值/清空/回退默认）、变更事件载荷结构，以及如何隐藏过滤器。读完后，你可以让宿主应用与嵌入内容之间的筛选器状态实现真正的双向同步。

1. 定位：这些 props 能做什么，不能做什么

模块化嵌入（React SDK 与 Web Components）中的参数 props/attributes 用来设置参数值的初始状态，并保持宿主应用与用户在嵌入内容中修改的值同步。需要特别注意它们的权限边界：

• 通过这些 props 设置的值，嵌入内容的查看者仍然可以自行修改——它们不是"锁死"的值；
• 如果你需要一个由你的应用控制、用户既看不到也改不了的值，应改用 guest embed 的 locked parameter，或 SSO embed 的 data permissions。

这一安全边界在文档末尾再次强调：用initial-parameters设值后再隐藏筛选器组件，不构成安全的数据过滤手段，因为值是在浏览器端设置的。

2. React SDK：向 Dashboard 传递参数

文档给出了两种互斥的模式，只能二选一，不要混用（文档原话：pick one）：

2.1initialParameters（非控制模式）

加载时一次性设置筛选器值，之后用户在 Dashboard 里改动筛选器时，你的应用不会感知。适用于不需要追踪变更的场景：

import { InteractiveDashboard } from "@metabase/embedding-sdk-react"; const dashboardId = 1; const Example = () => ( <InteractiveDashboard dashboardId={dashboardId} initialParameters={{ state: "NY" }} /> );

该示例出自 initial-parameters.tsx。键是 dashboard 参数的 slug，语义规则见 第 5 节。

2.2parameters+onParametersChange（控制模式）

由你的应用推送值，并通过回调观察每一次"已生效"的变更。它的工作方式类似于受控的<input value onChange>：你的应用持有 source of truth，Dashboard 在 prop 变化时重新渲染，已生效值变化时你收到回调：

import { InteractiveDashboard, type ParameterChangePayload, type ParameterValues, } from "@metabase/embedding-sdk-react"; import { useState } from "react"; const dashboardId = 1; const ExampleControlled = () => { const [parameters, setParameters] = useState<ParameterValues>({ state: "NY", }); const handleParametersChange = (payload: ParameterChangePayload) => { // Sync your local state on every applied change. `payload.source` is one of: // "initial-state" — post-load snapshot, fired once per dashboard load // "manual-change" — user edited a parameter widget // "auto-change" — your push was normalized; re-sync from `payload.parameters` setParameters(payload.parameters); }; return ( <InteractiveDashboard dashboardId={dashboardId} parameters={parameters} onParametersChange={handleParametersChange} /> ); };

该示例出自 controlled-parameters.tsx。其中onParametersChange接收的载荷结构见 第 6.1 节。

同一 snippet 文件还给出了两种清空写法，供参考：

// 将某个参数设为 null 即清空它（忽略该参数的默认值） // 未提供的 slug 回退到 parameter.default ?? null <InteractiveDashboard dashboardId={dashboardId} parameters={{ state: null, city: "Austin" }} /> // 传入空对象清空所有参数 <InteractiveDashboard dashboardId={dashboardId} parameters={{}} />

3. React SDK：向 SQL 问题传递参数

参数值以{parameter_name: parameter_value}的格式传给 SQL 问题。文档明确：这些 props 只对 SQL 问题（native question）生效，对 query-builder 问题无效。

SQL 问题中的参数概念详见 SQL parameters。

3.1initialSqlParameters（非控制模式）

加载时一次性设置参数值，之后用户改动参数时应用无感知：

import { StaticQuestion } from "@metabase/embedding-sdk-react"; const questionId = 1; const Example = () => ( <StaticQuestion questionId={questionId} initialSqlParameters={{ product_id: 50 }} /> );

示例出自 initial-sql-parameters.tsx。注意值不必是字符串，示例中product_id: 50直接是数字，这与 第 5 节中的ParameterValues类型定义一致。

3.2sqlParameters+onSqlParametersChange（控制模式）

与控制<input>相同的模式：应用推送值，问题在 prop 变化时重新渲染，已生效值变化时回调触发：

import { InteractiveQuestion, type SqlParameterChangePayload, type SqlParameterValues, } from "@metabase/embedding-sdk-react"; import { useState } from "react"; const questionId = 1; const ExampleControlled = () => { const [sqlParameters, setSqlParameters] = useState<SqlParameterValues>({ state: "NY", }); const handleSqlParametersChange = (payload: SqlParameterChangePayload) => { setSqlParameters(payload.parameters); }; return ( <InteractiveQuestion questionId={questionId} sqlParameters={sqlParameters} onSqlParametersChange={handleSqlParametersChange} /> ); };

该示例出自 controlled-sql-parameters.tsx。回调载荷结构见 第 6.2 节。

4. Web Components：从页面驱动参数

使用原生<metabase-dashboard>/<metabase-question>自定义元素时，有四种能力：通过 attribute 播种初始值、通过 JS property 运行时推值、清空参数、监听已生效变更。

4.1 用initial-parameters/initial-sql-parameters属性播种一次

<metabase-dashboard dashboard-id="1" initial-parameters='{"state": "NY"}' ></metabase-dashboard> <metabase-question question-id="42" initial-sql-parameters='{"product_id": 50}' ></metabase-question>

关键行为：

• 组件只在加载时读取一次这些 attribute，之后对 attribute 的修改会被忽略；
• 用户对 widget 的编辑不会回传到页面（如需监听变更，见 4.4）；
• attribute 承载的是JSON：键是参数 slug（dashboard）或 SQL 变量名（question）。

关于 ID 的一个实用提示：上面的示例用的是顺序 ID——即资源 URL 里的那串数字。在 Pro 和 Enterprise 套餐下，可以改用 entity ID，在把内容从一个 Metabase 序列化到另一个实例（如 staging 到 production）时保持不变。

从源码结构看，这些 attribute 名确实被 SDK 注册为受支持属性：在 embed.ts 的属性列表中可以看到"initial-parameters"（L797）与"initial-sql-parameters"（L825）。

4.2 运行时推值：parameters/sqlParametersJS 属性

需要控制模式时，设置的是元素上的JS property 而不是 attribute，组件会重新渲染以应用新值：

<metabase-dashboard id="my-dashboard" dashboard-id="1"></metabase-dashboard> <script> const el = document.getElementById("my-dashboard"); el.parameters = { state: "NY" }; </script>

<metabase-question>上同样的模式使用sqlParameters属性。

切回非控制模式：把 property 设为undefined，组件将保留最后应用的一组值。

4.3 清空参数

• 清空单个参数：将其值设为null，这是"严格清空"，会忽略该参数的默认值：

const el = document.getElementById("my-dashboard"); // `null` strictly clears the parameter (ignores its default). el.parameters = { ...el.parameters, state: null };

• 清空所有参数：赋值为空对象{}：

const el = document.getElementById("my-dashboard"); el.parameters = {};

4.4 监听已生效变更：parameters-change/sql-parameters-change事件

<metabase-dashboard id="my-dashboard" dashboard-id="1"></metabase-dashboard> <script> const el = document.getElementById("my-dashboard"); el.addEventListener("parameters-change", (event) => { const { source, parameters, defaultParameters, lastUsedParameters } = event.detail; console.log(source, parameters); }); </script>

event.detail携带 Dashboard 参数变更载荷。对 SQL 问题，在<metabase-question>上监听sql-parameters-change，其event.detail携带 SQL 问题参数变更载荷。

这个事件在 SDK 层的分发实现可以在 embed.ts 中确认：iframe 内嵌内容通过postMessage发出metabase.embed.parametersChange/metabase.embed.sqlParametersChange消息后，宿主侧以CustomEvent的形式派发：

if (message.type === "metabase.embed.parametersChange") { this.dispatchEvent( new CustomEvent("parameters-change", { detail: message.data }), ); } if (message.type === "metabase.embed.sqlParametersChange") { this.dispatchEvent( new CustomEvent("sql-parameters-change", { detail: message.data }), ); }

也就是说event.detail正是 iframe 内发送的message.data，与 React SDK 回调收到的 payload 是同一份结构。

5. 参数值解析规则

以下规则对四种 props全部适用——initialParameters/parameters（dashboard）与initialSqlParameters/sqlParameters（SQL 问题）——以及对应的 Web Component 属性（initial-parameters、parameters等）。针对每一个参数 slug：

参数值的类型定义可从 SDK API 参考 ParameterValues 中确认：

type ParameterValues = Record< string, | string | number | boolean | (string | number | boolean | null)[] | null | undefined >;

即值可以是字符串、数字、布尔、可含null的数组，或null/undefined——这也解释了为什么 SQL 参数示例中product_id: 50能直接传数字。

6. 变更事件载荷

6.1 Dashboard parameter change payload

投递给onParametersChange（SDK）与parameters-change事件的event.detail（Web Components）。类型定义见 ParameterChangePayload：

type ParameterChangePayload = { defaultParameters: ParameterValues; lastUsedParameters: ParameterValues; parameters: ParameterValues; source: ParameterChangeSource; };

source说明回调为何触发：

• initial-state—— 首次应用的快照，每次 dashboard 加载触发一次；
• manual-change—— 用户在 UI 中编辑了参数；
• auto-change—— 自动更新场景，例如把规范化后的值回传给你的应用。

6.2 SQL question parameter change payload

投递给onSqlParametersChange（SDK）与sql-parameters-change事件的event.detail（Web Components）。类型定义见 SqlParameterChangePayload：

type SqlParameterChangePayload = { defaultParameters: ParameterValues; parameters: ParameterValues; source: SqlParameterChangeSource; };

注意与 Dashboard 载荷的差异：没有lastUsedParameters字段。source的取值语义相同：initial-state（每次问题加载触发一次）、manual-change（用户编辑）、auto-change（自动更新/值回传）。

7. 隐藏 Dashboard 过滤器：hiddenParameters

要隐藏 dashboard UI 中的某个过滤器：

• Web Component：hidden-parameters属性（详见 dashboard reference）；
• React SDK：hiddenParametersprop。

文档给出的适用场景与注意事项：

• 隐藏过滤器在SSO 嵌入中比较有用——SSO 嵌入下 dashboard 上的所有过滤器默认都会显示；
• 在guest embed中，未设为 Editable 或 Locked 的过滤器本来就不可见，通常没有可隐藏的对象；
• 隐藏只是让 UI 更清爽，并不限制用户能查询什么。用initial-parameters设值后隐藏控件不是安全的过滤方式；要控制"用户既看不到也改不了"的值，请用 guest embed 的 locked parameter 或 SSO embed 的 data permissions。

8. 速查表

最后再强调两条使用纪律：initialParameters与parameters只能选一个，控制模式只用parameters；SQL 参数 props 仅适用于 SQL 问题，query-builder 问题不受支持。完整可运行的代码示例以 参数 snippets 目录 下的源文件为准。

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