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

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 one2.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.2parametersonParametersChange控制模式由你的应用推送值并通过回调观察每一次已生效的变更。它的工作方式类似于受控的input value onChange你的应用持有 source of truthDashboard 在 prop 变化时重新渲染已生效值变化时你收到回调import { InteractiveDashboard, type ParameterChangePayload, type ParameterValues, } from metabase/embedding-sdk-react; import { useState } from react; const dashboardId 1; const ExampleControlled () { const [parameters, setParameters] useStateParameterValues({ 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.2sqlParametersonSqlParametersChange控制模式与控制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] useStateSqlParameterValues({ 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-id1 initial-parameters{state: NY} /metabase-dashboard metabase-question question-id42 initial-sql-parameters{product_id: 50} /metabase-question关键行为组件只在加载时读取一次这些 attribute之后对 attribute 的修改会被忽略用户对 widget 的编辑不会回传到页面如需监听变更见 4.4attribute 承载的是JSON键是参数 slugdashboard或 SQL 变量名question。关于 ID 的一个实用提示上面的示例用的是顺序 ID——即资源 URL 里的那串数字。在 Pro 和 Enterprise 套餐下可以改用 entity ID在把内容从一个 Metabase 序列化到另一个实例如 staging 到 production时保持不变。从源码结构看这些 attribute 名确实被 SDK 注册为受支持属性在 embed.ts 的属性列表中可以看到initial-parametersL797与initial-sql-parametersL825。4.2 运行时推值parameters/sqlParametersJS 属性需要控制模式时设置的是元素上的JS property 而不是 attribute组件会重新渲染以应用新值metabase-dashboard idmy-dashboard dashboard-id1/metabase-dashboard script const el document.getElementById(my-dashboard); el.parameters { state: NY }; /scriptmetabase-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 idmy-dashboard dashboard-id1/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); }); /scriptevent.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/parametersdashboard与initialSqlParameters/sqlParametersSQL 问题——以及对应的 Web Component 属性initial-parameters、parameters等。针对每一个参数 slug意图写法效果设置值单选项筛选器传string多选项筛选器传string数组应用该值清空值设为null参数被清空且不使用其默认值回退默认值省略该键或显式设为undefined回退到参数的默认值若没有默认值则为null参数值的类型定义可从 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投递给onParametersChangeSDK与parameters-change事件的event.detailWeb Components。类型定义见 ParameterChangePayloadtype ParameterChangePayload { defaultParameters: ParameterValues; lastUsedParameters: ParameterValues; parameters: ParameterValues; source: ParameterChangeSource; };属性类型defaultParametersParameterValueslastUsedParametersParameterValuesparametersParameterValuessourceParameterChangeSourcesource说明回调为何触发initial-state—— 首次应用的快照每次 dashboard 加载触发一次manual-change—— 用户在 UI 中编辑了参数auto-change—— 自动更新场景例如把规范化后的值回传给你的应用。6.2 SQL question parameter change payload投递给onSqlParametersChangeSDK与sql-parameters-change事件的event.detailWeb Components。类型定义见 SqlParameterChangePayloadtype SqlParameterChangePayload { defaultParameters: ParameterValues; parameters: ParameterValues; source: SqlParameterChangeSource; };属性类型defaultParametersParameterValuesparametersParameterValuessourceSqlParameterChangeSource注意与 Dashboard 载荷的差异没有lastUsedParameters字段。source的取值语义相同initial-state每次问题加载触发一次、manual-change用户编辑、auto-change自动更新/值回传。7. 隐藏 Dashboard 过滤器hiddenParameters要隐藏 dashboard UI 中的某个过滤器Web Componenthidden-parameters属性详见 dashboard referenceReact SDKhiddenParametersprop。文档给出的适用场景与注意事项隐藏过滤器在SSO 嵌入中比较有用——SSO 嵌入下 dashboard 上的所有过滤器默认都会显示在guest embed中未设为 Editable 或 Locked 的过滤器本来就不可见通常没有可隐藏的对象隐藏只是让 UI 更清爽并不限制用户能查询什么。用initial-parameters设值后隐藏控件不是安全的过滤方式要控制用户既看不到也改不了的值请用 guest embed 的 locked parameter 或 SSO embed 的 data permissions。8. 速查表场景React SDKWeb ComponentDashboard 初始值一次性initialParametersinitial-parametersattributeDashboard 控制模式parametersonParametersChangeel.parameters ...JS propertySQL 问题初始值一次性initialSqlParametersinitial-sql-parametersattributeSQL 问题控制模式sqlParametersonSqlParametersChangeel.sqlParameters ...JS property监听已生效变更对应onChange回调parameters-change/sql-parameters-change事件切回非控制模式移除受控 propsproperty 设为undefined清空单个参数值设为null值设为null清空全部参数赋{}赋{}隐藏过滤器hiddenParametershidden-parameters最后再强调两条使用纪律initialParameters与parameters只能选一个控制模式只用parametersSQL 参数 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考