企业官网建设流程全解析

Metabase 模块化嵌入完全指南：<metabase-question>Web 组件属性全解析

【免费下载链接】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-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.md）
• <metabase-dashboard>（见 MetabaseDashboardAttributes.md）
• <metabase-metabot>（见 MetabaseMetabotAttributes.md）
• <metabase-question>（即本文主题）

一个<metabase-question>标签通过组合question-id与token两个入口属性，可以承载四种完全不同的形态：

正如 query-builder.md 所述，四种形态共用同一个<metabase-question>元素，因此它们接受的属性完全一致——这正是本文档值得通读全表的原因。

二、选择嵌入目标：question-id与token

<metabase-question>组件的第一个核心决策是"嵌入什么"，由两个互斥属性决定：SSO 嵌入用question-id，Guest 嵌入用token。

question-id：SSO 嵌入的入口

• 类型：string | number
• 可用范围：仅 SSO 嵌入

该属性接受目标 Question 的 ID，有三种取值方式：

1. 普通顺序 ID（sequential ID）：即该 Question URL 中的数字，例如question-id="1"。这是最常用的方式。
2. Entity ID：在 Pro/Enterprise 计划上，可以使用 序列化文档 中定义的 Entity ID。它与顺序 ID 的最大区别是在序列化迁移（如从 staging 复制到 production）后保持不变，见 chart.md。
3. 特殊值"new"与"new-native"：
   • question-id="new"：嵌入可视化查询构建器，让用户从零构建新 Question；
   • question-id="new-native"：嵌入SQL 编辑器，让用户编写原生 SQL。

重要前提：两种查询编辑器都必须搭配 SSO 使用。原因在于——运行一条全新查询时，Metabase 必须知道"是谁在问"，才能据此判定数据权限；Guest 嵌入没有登录账户，因此无法运行新查询，详见 query-builder.md。

token：Guest 嵌入的入口

• 类型：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后：

1. 它取代initial-sql-parameters成为初始种子（supersedes）；
2. 它会与后续的参数变更保持同步（stays in sync with subsequent mutations）——用户在嵌入界面改动参数时，该属性值会随之更新；
3. 应配合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-id="new"查询构建器时，用该属性限定用户的数据选择器（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 嵌入的图表降级为只读体验，最直接的方式就是drills="false"（配合is-save-enabled="false"），详见 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 为true，Pro/Enterprise 为false
• 可用范围：Guest 嵌入

控制是否显示 Question 结果的下载按钮。注意默认值随版本不同而不同，且仅在 Guest 嵌入中可用。

with-title：标题显示开关

• 类型：boolean
• 默认值：true
• 可用范围：Guest 嵌入

控制嵌入中是否显示 Question 的标题。默认显示，设为false可隐藏以获得更干净的嵌入界面。

五、完整属性参考表

下表完整收录 MetabaseQuestionAttributes.md 的全部 14 个属性，便于快速查阅：

提示：question-id、target-collection均可使用 Entity ID；在需要把内容从 staging 序列化迁移到 production 的场景下，Entity ID 保持稳定，是比顺序 ID 更可靠的引用方式，详见 序列化文档。

六、属性值传递的框架注意事项

question-reference.md 针对不同前端框架给出了一条关键提示：在部分框架中，对象/数组类型的属性值需要先字符串化再传给组件。此外，若属性值外层用双引号包裹，则内部必须使用单引号：

<metabase-question question-id="1" initial-sql-parameters="{ 'productId': '42' }" hidden-parameters="['productId']" ></metabase-question>

布尔与数字属性同样按 HTML 属性语法传递：drills="false"、with-title="true"、target-collection="5"。

七、实战组合示例

场景一：Guest 只读图表（带锁定参数）

沿用 chart.md 的经典例子——在每位客户的账户页嵌入该客户的订单图表。前端只声明展示类属性，参数值由服务端签发 token 时锁定：

<script defer src="https://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 token="PASS_SIGNED_TOKEN_FROM_SERVER" with-title="true" with-downloads="true" ></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-id="1"></metabase-question>

如需让图表只读，显式关闭钻取与保存：

<metabase-question question-id="1" drills="false" is-save-enabled="false" ></metabase-question>

场景三：允许保存，且落到指定集合

<metabase-question question-id="1" is-save-enabled="true" target-collection="5" ></metabase-question>

target-collection也可取"personal"或"root"。

场景四：嵌入可视化查询构建器 / SQL 编辑器

<!-- 可视化查询构建器 --> <metabase-question question-id="new"></metabase-question> <!-- 限定数据选择器只显示原始表 --> <metabase-question question-id="new" entity-types="['table']"></metabase-question> <!-- SQL 编辑器 --> <metabase-question question-id="new-native"></metabase-question>

注意：两种编辑器都必须运行在 SSO 嵌入之下（见 query-builder.md），且用户能查询的数据受其 Metabase 账户的数据权限约束，可参考 数据权限文档。

场景五：SQL 参数受控同步

对含变量的原生 SQL Question，把参数提升为受控状态，并通过 DOM 事件追踪编辑：

<metabase-question question-id="42" sql-parameters="{ 'productId': '42' }" ></metabase-question>

document .querySelector("metabase-question") .addEventListener("sql-parameters-change", (event) => { // event.detail 为最新参数对象，写回应用状态 console.log(event.detail); });

八、使用边界与最佳实践总结

• 认证模式决定入口：SSO 嵌入使用question-id；Guest 嵌入使用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