Metabase EJS 嵌入模板详解modular embedding 四个 Web Component 的完整属性参考【免费下载链接】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 仓库中docs/embedding/eajs/snippets/index.md为核心完整解读 EJSEmbedding Application JavaScript模态嵌入模板体系它定义了metabase-browser、metabase-dashboard、metabase-metabot、metabase-question四个 web component 可接受的全部属性。读完本文你可以直接编写 EJS 模板按 SSO 嵌入或 Guest 嵌入两种方式生成嵌入片段并精确控制仪表盘、问题、集合浏览器和 AI 聊天界面在宿主页面上的行为与外观。一、EJS 模态嵌入模板的定位与文档组织EJS 是 Metabase 用于生成嵌入代码片段的轻量模板层宿应用通过 EJS 模板把属性写入metabase-*web component 标签再配合 iframe SDK 加载对应的 Metabase 组件。仓库文档明确该目录是所有 modular embedding 组件所接受属性的唯一事实来源source of truth。docs/embedding/eajs/snippets/index.md作为索引页把四个属性接口文档组织成一张表接口对应 web component说明MetabaseBrowserAttributesmetabase-browser集合浏览器collection browser属性MetabaseDashboardAttributesmetabase-dashboard仪表盘嵌入属性MetabaseMetabotAttributesmetabase-metabotAI 聊天界面Metabot属性MetabaseQuestionAttributesmetabase-question问题图表嵌入属性四个子文档的编写格式高度统一均由两段组成Remarks 段标注可用版本档位例如 Browser 和 Metabot 都标注Pro/Enterprise且限定于authenticated (SSO) modular embeds已认证 SSO 嵌入Properties 段属性表每个属性给出属性名HTML attribute、TypeTypeScript 类型、Description描述中用---分隔出 Optional/Default/Possible values/Available in 等元信息。这种接口名 web component 属性集的命名约定让 EJS 模板作者可以直接按 TypeScript 接口名查阅可用属性避免猜测属性名。从源码结构看这些属性最终会映射到 iframe SDK 的类型定义例如 modular-embedding.ts 定义了metabase-question、metabase-dashboard等组件的 TS 类型而 embed.ts 等文件承载了 SDK 对组件标签的加载逻辑。文档层docs/embedding/eajs/snippets/与源码层frontend/src/metabase/embedding/embedding-iframe-sdk/一一对应保证了文档中的属性名可以实际在模板中生效。二、metabase-browser集合浏览器属性Browser 组件用于在宿应用内嵌一个内容管理器让用户浏览集合、打开仪表盘或问题。它仅对已认证SSO的模态嵌入可用且文档 Remarks 标注为Pro/Enterprise功能。完整属性表来源MetabaseBrowserAttributes.md属性类型说明collection-entity-typesstring[]集合浏览器中显示哪些实体类型可选值model、collection、dashboard、question。Optionalcollection-page-sizenumber每页显示多少项。Optionalcollection-visible-columnsstring[]集合浏览器中显示哪些列type、name、description、lastEditedBy、lastEditedAt、archive。Optionaldata-picker-entity-typesstring[]问题的数据选择器data picker中显示哪些实体类型model、table。Optionalenable-entity-navigationboolean是否启用内部实体导航链接到仪表盘/问题。OptionalDefault:falseinitial-collectionstring|number起始集合。取值常规 ID、实体 ID、root顶层 Our Analytics 集合、personal查看者个人集合、tenant查看者租户集合非租户成员会得到错误、all查看者可访问的全部内容个人集合 共享集合read-onlyboolean内容管理器是否只读。true时可交互筛选、汇总、钻取但不可保存false时可创建和编辑。OptionalDefault:truewith-new-dashboardboolean是否显示New dashboard按钮仅在read-only为false时生效。OptionalDefault:truewith-new-questionboolean是否显示New question按钮。OptionalDefault:true使用要点默认只读read-only默认true因此在 EJS 模板中若希望用户能保存内容必须显式设置read-onlyfalse此时with-new-dashboard/with-new-question按钮默认出现initial-collection的字符串语义是该组件最有特色的设计——不需要计算集合数字 ID用root、personal、tenant、all即可锚定不同导航起点导航联动enable-entity-navigation默认关闭即浏览器中的条目默认不会跳转开启后才允许点击进入仪表盘/问题适合做内容门户式嵌入。三、metabase-dashboard仪表盘嵌入属性Dashboard 组件用于嵌入单个 Metabase 仪表盘。文档说明其两种身份模式SSO 嵌入提供dashboard-idGuest 嵌入提供token再叠加可选的展示配置。完整属性表来源MetabaseDashboardAttributes.md属性类型说明可用性auto-refresh-intervalnumber自动刷新间隔秒如60表示每 60 秒刷新Pro/Enterprise 与 Guest embedcustom-contextstring透传给 guest token 端点的自定义上下文字符串Guest embeddashboard-idstring|number要嵌入的仪表盘 ID可为常规 ID 或实体 IDentity ID。仅 SSO 嵌入可用Guest 嵌入用tokenSSOdrillsboolean是否启用仪表盘上的钻取drill-through。Default:truePro/Enterpriseenable-entity-navigationboolean是否启用内部实体导航链接到仪表盘/问题要求drills为true。Default:falsePro/Enterprisehidden-parametersstring[]要从仪表盘隐藏的过滤器名称列表如[productId]Pro/Enterpriseinitial-parametersobject仪表盘过滤器的默认值如{ productId: 42 }Pro/Enterprise 与 Guest embedparametersobject受控的仪表盘过滤器值如{ productId: 42 }。设置该属性会取代initial-parameters作为种子值并随后续变更保持同步配合parameters-changeDOM 事件可追踪编辑Pro/Enterprise 与 Guest embedtokenstringGuest 嵌入的 token由 guest embed 流程自动设置Guest embedwith-downloadsboolean是否显示下载仪表盘为 PDF和下载问题结果按钮。Default: OSS/Starter 为truePro/Enterprise 为falseGuest embedwith-subscriptionsboolean是否允许用户设置仪表盘订阅来自嵌入仪表盘的订阅不含 Metabase 内部链接Pro/Enterprisewith-titleboolean是否在嵌入中显示仪表盘标题。Default:trueGuest embed该组件最值得展开的是参数控制的三档递进设计initial-parameters一次性种子值用户改动后组件不再回写parameters受控controlled值设置后取代initial-parameters作为种子并随后续变更保持同步——即双向绑定parameters-changeDOM 事件宿应用监听它来捕获用户对过滤器的编辑从而更新parameters属性完成受控闭环。这意味着 EJS 模板可以生成过滤器值由宿应用状态驱动的仪表盘嵌入而不是把初始值写死在 HTML 里。四、metabase-question问题嵌入属性Question 组件嵌入单个问题图表。同样支持 SSOquestion-id与 Guesttoken两种模式并额外提供两个特殊的 ID 字面量用于嵌入创作界面question-idnew嵌入查询构建器query builder探索界面question-idnew-native嵌入 SQL 编辑器界面。完整属性表来源MetabaseQuestionAttributes.md属性类型说明可用性custom-contextstring透传给 guest token 端点的自定义上下文字符串Guest embeddrillsboolean是否启用问题上的钻取。Default:truePro/Enterpriseentity-typesstring[]问题数据选择器中显示的实体类型如[model, table]可选值model、tablePro/Enterprise 与 Guest embedhidden-parametersstring[]要隐藏的参数名称列表Pro/Enterpriseinitial-sql-parametersobjectSQL 参数默认值仅适用于原生 SQL 问题如{ productId: 42 }Pro/Enterprise 与 Guest embedis-save-enabledboolean是否启用保存按钮。Default:falsePro/Enterprisequestion-idstring|number要嵌入的问题 ID可为常规 ID 或实体 IDnew嵌入查询构建器new-native嵌入 SQL 编辑器。仅 SSO 嵌入可用Guest 嵌入用tokenSSOsql-parametersobject受控的 SQL 参数值如{ productId: 42 }。设置后取代initial-sql-parameters作为种子并随变更同步配合sql-parameters-changeDOM 事件追踪编辑Pro/Enterprise 与 Guest embedtarget-collectionstring|number保存问题到的目标集合。取值常规 ID、实体 ID、personal、rootPro/EnterprisetokenstringGuest 嵌入的 token由 guest embed 流程自动设置Guest embedwith-alertsboolean是否显示告警alerts按钮。Default:falsePro/Enterprisewith-downloadsboolean是否显示问题结果下载按钮。Default: OSS/Starter 为truePro/Enterprise 为falseGuest embedwith-titleboolean是否显示问题标题。Default:trueGuest embed与 Dashboard 组件对照可以发现一致的参数控制范式initial-sql-parameters种子→sql-parameters受控→sql-parameters-change事件回调且都标注 Pro/Enterprise 与 Guest embed 双可用。差异在于 Question 组件把创作能力也纳入了嵌入范围——通过question-idnew/new-native可以在宿应用里提供完整的建问界面并配合is-save-enabledtarget-collection决定保存行为与落点集合。五、metabase-metabotAI 聊天嵌入属性Metabot 组件嵌入 AI 聊天界面仅对已认证SSO的模态嵌入可用文档 Remarks 标注为Pro/Enterprise。完整属性表来源MetabaseMetabotAttributes.md属性类型说明is-save-enabledboolean保存按钮是否启用。OptionalDefault:falselayoutstring可视化图表相对于聊天界面的定位方式。auto在移动端用stacked、大屏用sidebar。OptionalDefault:auto可选值auto、sidebar、stackedtarget-collectionstring|number保存问题到的目标集合。Optional该组件属性最精简设计意图是把 AI 嵌入做成开箱即用layout一个属性即覆盖了响应式布局需求auto模式自动在堆叠/侧栏间切换is-save-enabled默认关闭以保证嵌入内生成的内容不会未经宿应用授权就写入 Metabasetarget-collection则在开启保存时指定落点。六、属性设计规律小结SSO 与 Guest 的分界把四个组件的属性横向比较EJS 模板作者可以归纳出三条可复用的规律身份属性二选一*-iddashboard-id/question-id用于 SSO 嵌入token用于 Guest 嵌入两者不混用token由 guest embed 流程自动设置模板作者通常只需消费。展示开关按档位标注可用性with-downloads、with-title标注 Guest embeddrills、hidden-parameters、with-subscriptions、with-alerts标注 Pro/Enterpriseinitial-parameters/parameters、initial-sql-parameters/sql-parameters则两端皆可。编写模板时应先确认宿应用所处的嵌入类型与许可档位再挑选属性。受控参数三件套initial-*种子→ 受控属性parameters/sql-parameters→*-change事件parameters-change/sql-parameters-change构成嵌入过滤器值的双向绑定闭环这是 EJS 模板实现宿应用状态驱动嵌入 UI的核心机制。以上四个组件及其全部属性均以docs/embedding/eajs/snippets/下的五个文档为唯一事实来源属性语义如与源码行为存在演进差异时建议以该目录文档与 modular-embedding.ts 等 SDK 类型定义交叉核对。【免费下载链接】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），仅供参考