Metabase 模块化嵌入完全指南metabase-questionWeb 组件属性全解析【免费下载链接】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/metabasemetabase-question是 Metabase 模块化嵌入Modular Embedding体系中的核心 Web 组件用于把单个 Question图表嵌入到你自己的应用中。本指南以仓库内 MetabaseQuestionAttributes.md 为骨架完整解析该组件的全部属性——包括选择嵌入目标、控制 SQL 参数、管理交互与界面元素——并给出可复制运行的 HTML 示例帮助你同时掌握只读图表嵌入、交互式图表嵌入以及查询构建器/SQL 编辑器嵌入三类实战场景。读完本文你将能读懂并编写任何一个metabase-question标签知道每个属性在何种认证模式与版本计划下可用并能结合sql-parameters-changeDOM 事件实现参数的双向同步。一、组件定位一个标签四种形态metabase-question是模块化嵌入Modular Embedding提供的四个 Web 组件之一。仓库中的 eajs/snippets/index.md 明确说明该目录是模块化嵌入组件所有属性的权威来源source of truth四个组件分别为metabase-browser见 MetabaseBrowserAttributes.mdmetabase-dashboard见 MetabaseDashboardAttributes.mdmetabase-metabot见 MetabaseMetabotAttributes.mdmetabase-question即本文主题一个metabase-question标签通过组合question-id与token两个入口属性可以承载四种完全不同的形态形态关键属性认证模式只读图表view-only charttokenGuest 嵌入交互式图表interactive chartquestion-idSSO 嵌入可视化查询构建器question-idnewSSO 嵌入SQL 编辑器question-idnew-nativeSSO 嵌入正如 query-builder.md 所述四种形态共用同一个metabase-question元素因此它们接受的属性完全一致——这正是本文档值得通读全表的原因。二、选择嵌入目标question-id与tokenmetabase-question组件的第一个核心决策是嵌入什么由两个互斥属性决定SSO 嵌入用question-idGuest 嵌入用token。question-idSSO 嵌入的入口类型string | number可用范围仅 SSO 嵌入该属性接受目标 Question 的 ID有三种取值方式普通顺序 IDsequential ID即该 Question URL 中的数字例如question-id1。这是最常用的方式。Entity ID在 Pro/Enterprise 计划上可以使用 序列化文档 中定义的 Entity ID。它与顺序 ID 的最大区别是在序列化迁移如从 staging 复制到 production后保持不变见 chart.md。特殊值new与new-nativequestion-idnew嵌入可视化查询构建器让用户从零构建新 Questionquestion-idnew-native嵌入SQL 编辑器让用户编写原生 SQL。重要前提两种查询编辑器都必须搭配 SSO 使用。原因在于——运行一条全新查询时Metabase 必须知道是谁在问才能据此判定数据权限Guest 嵌入没有登录账户因此无法运行新查询详见 query-builder.md。tokenGuest 嵌入的入口类型string可用范围仅 Guest 嵌入token是 Guest 嵌入的身份凭证由 Guest 嵌入流程自动设置即 Metabase 内嵌向导生成的代码会自动填充。实战中需特别注意 chart.md 强调的一点不要直接把向导生成的 JWT 硬编码进 HTML——该 token 是带过期时间的固定字符串过期后嵌入会失效。正确做法是在你的应用服务端为每次页面加载签发新 JWT 并渲染进token属性或省略该属性、改用guestEmbedProviderUri指向你应用内的端点来刷新/初始化 JWT见 guest-embedding.md。三、SQL 参数控制从初始化到受控同步metabase-question对原生 SQL Question 中的变量提供了两套参数机制外加一个隐藏控制理解它们的区别是正确使用参数嵌入的关键。initial-sql-parameters一次性初始值类型object默认值无可用范围Pro/Enterprise 与 Guest 嵌入适用范围仅原生 SQL Question为 SQL 参数提供默认值例如{ productId: 42 }。它是初始种子——用户随后可以在界面上修改这些值。sql-parameters受控参数受控组件模式类型object可用范围Pro/Enterprise 与 Guest 嵌入这是把参数从初始化升级为受控的关键属性。设置sql-parameters后它取代initial-sql-parameters成为初始种子supersedes它会与后续的参数变更保持同步stays in sync with subsequent mutations——用户在嵌入界面改动参数时该属性值会随之更新应配合sql-parameters-changeDOM 事件使用监听该事件即可追踪参数编辑实现应用状态 → 组件参数 → 应用状态的双向闭环。典型用法是以人为主、以应用为准的联动你的应用通过 JS 更新sql-parameters属性来驱动图表同时监听sql-parameters-change事件把用户在图表内的改动写回应用状态。与之对比Dashboard 组件也有对应机制parameters与parameters-change见 MetabaseDashboardAttributes.md模式完全一致。hidden-parameters隐藏参数类型string[]可用范围Pro/Enterprise传入需要从图表中隐藏的参数名列表例如[productId]。隐藏后参数不再显示在界面上但仍可被initial-sql-parameters/sql-parameters或 token 中的锁定值驱动适用于展示给用户的数据已经由服务端限定的场景。entity-types限定数据选择器的实体范围类型string[]可能值model、table可用范围Pro/Enterprise 与 Guest 嵌入当嵌入question-idnew查询构建器时用该属性限定用户的数据选择器data picker中可选的实体类型。例如entity-types[table]只允许从原始表起步entity-types[model, table]则同时允许模型与原始表见 query-builder.md。custom-context透传给 Guest Token 端点的上下文类型string可用范围Guest 嵌入可选的自定义上下文字符串会被透传到 guest token 端点passed through to the guest token endpoint。可用于在签发 token 时携带业务上下文信息如租户标识、页面来源供服务端在生成 JWT 时参考。四、交互与界面控制六组布尔开关这组属性负责控制嵌入图表能做什么、显示什么。需特别留意其中有五个drills、is-save-enabled、target-collection、with-alerts、hidden-parameters标注为 Pro/Enterprise 计划可用且主要服务于 SSO 嵌入另有三个with-title、with-downloads、custom-context标注为 Guest 嵌入可用。drills钻取Drill-through开关类型boolean默认值true可用范围Pro/Enterprise控制是否启用图表的钻取drill-through即点击数据点下钻查看详情。默认开启。若想把 SSO 嵌入的图表降级为只读体验最直接的方式就是drillsfalse配合is-save-enabledfalse详见 chart.md。对应的交互文档见仓库内 drill-through 相关章节。is-save-enabled保存按钮开关类型boolean默认值false可用范围Pro/Enterprise控制保存按钮是否启用。默认关闭打开后用户可以把修改过的Question 保存到 Metabase。与target-collection搭配使用见 chart.md 的保存示例。target-collection保存目标集合类型string | number可选值普通 ID、Entity ID、personal、root可用范围Pro/Enterprise指定新保存的 Question 落入哪个集合Collection。除数字/字符串 ID 与 Entity ID 外还支持两个语义化取值personal保存到用户个人空间与root根集合。建议始终设置该属性——正如 query-builder.md 所言否则用户的产出会散落在 Metabase 各处。with-alerts告警按钮开关类型boolean默认值false可用范围Pro/Enterprise控制是否显示创建告警alert按钮。默认隐藏。with-downloads下载按钮开关类型boolean默认值OSS/Starter 为truePro/Enterprise 为false可用范围Guest 嵌入控制是否显示 Question 结果的下载按钮。注意默认值随版本不同而不同且仅在 Guest 嵌入中可用。with-title标题显示开关类型boolean默认值true可用范围Guest 嵌入控制嵌入中是否显示 Question 的标题。默认显示设为false可隐藏以获得更干净的嵌入界面。五、完整属性参考表下表完整收录 MetabaseQuestionAttributes.md 的全部 14 个属性便于快速查阅属性类型描述默认值可用范围custom-contextstring透传给 guest token 端点的自定义上下文字符串—Guest 嵌入drillsboolean是否启用图表钻取truePro/Enterpriseentity-typesstring[]数据选择器中显示的实体类型如[model, table]—Pro/Enterprise 与 Guest 嵌入hidden-parametersstring[]要从图表中隐藏的参数名列表—Pro/Enterpriseinitial-sql-parametersobjectSQL 参数默认值如{ productId: 42 }仅原生 SQL Question—Pro/Enterprise 与 Guest 嵌入is-save-enabledboolean保存按钮是否启用falsePro/Enterprisequestion-idstring \| number要嵌入的 Question ID可用普通 ID 或 Entity IDnew为查询构建器、new-native为 SQL 编辑器仅 SSO 嵌入—SSO 嵌入sql-parametersobject受控 SQL 参数值如{ productId: 42 }设置后取代initial-sql-parameters为初始种子并持续同步配合sql-parameters-changeDOM 事件—Pro/Enterprise 与 Guest 嵌入target-collectionstring \| number保存 Question 的目标集合取值普通 ID、Entity ID、personal、root—Pro/EnterprisetokenstringGuest 嵌入的 token由 guest 嵌入流程自动设置—Guest 嵌入with-alertsboolean是否显示告警按钮falsePro/Enterprisewith-downloadsboolean是否显示 Question 结果下载按钮OSS/Starter 为truePro/Enterprise 为falseGuest 嵌入with-titleboolean是否显示 Question 标题trueGuest 嵌入提示question-id、target-collection均可使用 Entity ID在需要把内容从 staging 序列化迁移到 production 的场景下Entity ID 保持稳定是比顺序 ID 更可靠的引用方式详见 序列化文档。六、属性值传递的框架注意事项question-reference.md 针对不同前端框架给出了一条关键提示在部分框架中对象/数组类型的属性值需要先字符串化再传给组件。此外若属性值外层用双引号包裹则内部必须使用单引号metabase-question question-id1 initial-sql-parameters{ productId: 42 } hidden-parameters[productId] /metabase-question布尔与数字属性同样按 HTML 属性语法传递drillsfalse、with-titletrue、target-collection5。七、实战组合示例场景一Guest 只读图表带锁定参数沿用 chart.md 的经典例子——在每位客户的账户页嵌入该客户的订单图表。前端只声明展示类属性参数值由服务端签发 token 时锁定script defer srchttps://your-metabase.example.com/app/embed.js/script script function defineMetabaseConfig(config) { window.metabaseConfig config; } /script script defineMetabaseConfig({ instanceUrl: https://your-metabase.example.com, isGuest: true, }); /script metabase-question tokenPASS_SIGNED_TOKEN_FROM_SERVER with-titletrue with-downloadstrue /metabase-question服务端在 JWT payload 的params中锁定参数使客户 13 的页面只返回客户 13 的订单const jwt require(jsonwebtoken); // 密钥来自 Metabase 后台 /admin/embedding/guest - Embedding secret key const METABASE_SECRET_KEY YOUR_SECRET_KEY; const payload { resource: { question: 40956 }, params: { customer_id: [13], // 根据当前渲染的账户页动态设置 }, exp: Math.round(Date.now() / 1000) 10 * 60, // 10 分钟过期 }; const token jwt.sign(payload, METABASE_SECRET_KEY);场景二SSO 交互式图表drills默认开启直接引用 Question ID 即得到可钻取的交互式图表metabase-question question-id1/metabase-question如需让图表只读显式关闭钻取与保存metabase-question question-id1 drillsfalse is-save-enabledfalse /metabase-question场景三允许保存且落到指定集合metabase-question question-id1 is-save-enabledtrue target-collection5 /metabase-questiontarget-collection也可取personal或root。场景四嵌入可视化查询构建器 / SQL 编辑器!-- 可视化查询构建器 -- metabase-question question-idnew/metabase-question !-- 限定数据选择器只显示原始表 -- metabase-question question-idnew entity-types[table]/metabase-question !-- SQL 编辑器 -- metabase-question question-idnew-native/metabase-question注意两种编辑器都必须运行在 SSO 嵌入之下见 query-builder.md且用户能查询的数据受其 Metabase 账户的数据权限约束可参考 数据权限文档。场景五SQL 参数受控同步对含变量的原生 SQL Question把参数提升为受控状态并通过 DOM 事件追踪编辑metabase-question question-id42 sql-parameters{ productId: 42 } /metabase-questiondocument .querySelector(metabase-question) .addEventListener(sql-parameters-change, (event) { // event.detail 为最新参数对象写回应用状态 console.log(event.detail); });八、使用边界与最佳实践总结认证模式决定入口SSO 嵌入使用question-idGuest 嵌入使用token两者不可混用。两种认证的详细对比见 introduction.md。计划决定属性可用性drills、hidden-parameters、is-save-enabled、target-collection、with-alerts仅在 Pro/Enterprise 可用custom-context、with-downloads、with-title属于 Guest 嵌入entity-types、initial-sql-parameters、sql-parameters则在 Pro/Enterprise 与 Guest 嵌入中均可用。集成前务必对照你的部署版本OSS/Starter/Pro/Enterprise核对。不要让 JWT 过期Guest 嵌入的token应由服务端按页面加载动态签发或用guestEmbedProviderUri托管刷新见 guest-embedding.md。参数三态SQL 参数有initial-sql-parameters初始化种子与sql-parameters受控并双向同步两套机制需要追踪用户编辑时务必使用后者并监听sql-parameters-change。外观统一组件的品牌色、字体等外观可通过页面级metabaseConfig.theme配置完整主题对象见 appearance.md参数主题的通用约定见 parameters.md。若你的嵌入场景是 Dashboard 而非单个 Question可对照 MetabaseDashboardAttributes.md 与 dashboard-reference.md 使用dashboard-id体系两套组件的属性设计保持一致迁移成本很低。【免费下载链接】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），仅供参考