尧图网页设计 
Metabase Full App Embedding UI Components用 URL 参数定制嵌入式界面【免费下载链接】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本文讲解如何通过在全应用嵌入full app embedding的 URL 末尾追加查询参数精细控制 Metabase 嵌入界面的各个 UI 组件顶栏top nav、侧边导航side nav、面包屑、Logo、页面头部、操作按钮、搜索框、New 按钮、数据选择器data picker、实体类型entity types以及界面语言locale。文章不仅完整给出每个参数的默认值、取值与组合规则还结合前端源码Redux 切片、参数解析管线、导航栏可见性选择器说明这些参数在运行时如何被解析、归一化并最终影响组件渲染帮助你在自有产品中把 Metabase 嵌入到“只留你需要的界面”的程度。一、整体思路把 UI 开关拼进嵌入 URL在全应用嵌入场景下你通常通过一个 iframe 指向 Metabase 的某个页面例如经过 SSO 登录后的/auth/sso或/collection/...等路由。Metabase 允许你在嵌入 URL 的查询字符串中附加一组“交互式嵌入选项”用来开关界面元素your_embedding_url?top_navfalseside_navfalse如果目标是修改配色或字体应改用外观定制中的主题配置而不是 URL 参数如果需要更细粒度的组件级控制例如单独嵌入一个查询构建器或问题卡片官方文档建议评估模块化嵌入Modular embedding。用 URL Constructor 拼装参数推荐写法在 Node.js 服务侧跳转 SSO 时使用URL对象而不是手工字符串拼接可以避免转义问题。官方文档给出的示例如下const mods logofalsetop_navtruesearchtruenew_buttontrue; app.get(/sso/metabase, restrict, (req, res) { const ssoUrl new URL(/auth/sso, METABASE_SITE_URL); ssoUrl.searchParams.set(jwt, signUserToken(req.session.user)); ssoUrl.searchParams.set(return_to, ${req.query.return_to ?? /}?${mods}); res.redirect(ssoUrl); });注意这里的技巧UI 参数不能直接挂在 SSO URL 上而是要拼进return_to的查询串里这样 SSO 完成后重定向回目标页面时参数才会被保留下来。实践提示当嵌入页面使用点击行为click behavior时要让查询参数在跳转后仍然保留需要在管理设置中将 Site URL 配置为你的 Metabase 服务器地址。二、参数速览表参数默认值作用top_navtrue显示顶部导航栏整体开关为false时其子元素search、new_button、breadcrumbs自动隐藏side_navdefault仅/collection与主页显示其余路由默认收起允许用户展开/收起侧边导航searchfalse隐藏顶栏中的搜索框new_buttonfalse隐藏顶栏中的 New按钮创建查询/仪表盘breadcrumbstrue显示顶栏中的集合面包屑logotrue打开/收起侧边栏的 Logo或通用侧栏图标headertrue问题/仪表盘页面的标题区域additional_infotrue标题下方的“X 天前由某人编辑”等附加信息与面包屑action_buttonstrue问题页面的 Filter、Summarize、查询构建器等操作按钮locale跟随用户设置界面语言如localeesentity_typestable,model数据选择器、侧边栏、New 菜单中可见的实体类型data_pickerflat简单下拉问题中数据源选择器可选staged完整多级选择器上表默认值可以直接在前端源码中得到印证embed.ts 中定义了默认选项常量第 24-36 行export const DEFAULT_INTERACTIVE_EMBEDDING_OPTIONS: InteractiveEmbeddingOptionsState { font: undefined, top_nav: true, side_nav: default, search: false, new_button: false, breadcrumbs: true, logo: true, header: true, additional_info: true, action_buttons: true, };其中side_nav的类型是boolean | default见 store/embed.ts 中的InteractiveEmbeddingOptions接口第 6-19 行不传该参数时即default语义——侧边导航只在集合浏览器与主页路由出现其余路由自动收起显式传side_navtrue后用户才可以在任意页面手动展开它。完整的选项键集合由同一文件中的ALLOWED_INTERACTIVE_EMBEDDING_OPTIONS第 39-45 行给出默认常量全部键加上额外并入的entity_types和data_picker两个键。解析 URL 时会先经过excludeNonInteractiveEmbeddingOptions即URL 中出现的其它无关参数如jwt、return_to会被剔除只有这份白名单内的键才会进入嵌入选项状态。三、顶栏及其子组件top_nav默认显示。隐藏整条顶部导航栏top_navfalsetop_nav控制的是整条顶栏的可见性设为false时其子元素search、new_button、breadcrumbs会自动全部隐藏设为true时可以单独控制这三个子元素。search默认隐藏。在顶栏显示搜索框top_navtruesearchtruenew_button默认隐藏。显示用于创建查询或仪表盘的 New按钮top_navtruenew_buttontruebreadcrumbs默认显示在顶栏中。集合面包屑collection breadcrumbs展示条目所在集合的路径该参数不影响用户拥有查询构建器权限时看到的 Data 面包屑。隐藏方式breadcrumbsfalse四、侧边导航与 Logoside_nav默认行为侧边导航在/collection路由和主页上显示其余路由隐藏。允许用户在嵌入中展开/收起侧边栏top_navtrueside_navtrue导航栏“随路由收起”的行为可以从源码得到印证redux/app.ts 中的isNavbarOpenForPathname第 67-74 行定义了使导航栏收起的路由正则const PATH_WITH_COLLAPSED_NAVBAR /\/(model\b|question\b|dashboard|metabot|document|explore).*/; export function isNavbarOpenForPathname(pathname: string, prevState: boolean) { return ( !isSmallScreen() !PATH_WITH_COLLAPSED_NAVBAR.test(pathname) prevState ); }也就是说进入/model、/question、/dashboard等具体内容页时导航栏会自动收起——这正是side_nav默认值在文档中描述为“仅/collection和主页显示”的底层机制。logoLogo 用于打开/收起侧边导航默认true。其行为与side_nav组合后按如下四种情况生效logoside_nav结果truetrue侧边栏中显示你配置的 Logotruefalse没有侧边栏也没有 Logo 功能falsetrue显示通用的侧栏图标默认灰色悬停时为主题品牌色falsefalse无侧边栏、无 Logo面包屑靠左对齐这四种组合在 AppBar.unit.spec.tsx 的单元测试中被逐一覆盖例如“logo 隐藏但 side_nav 开启时始终显示侧栏切换图标”“两者都关闭时不显示 Logo 也不显示切换按钮”等断言与上表一一对应。另外还有一个容易忽略的兜底逻辑selectors/app.ts 中当top_navfalse但side_navtrue时侧边栏会被强制展开——否则一旦顶栏隐藏用户将没有任何入口可以打开侧边栏。五、问题/仪表盘页的头部区域header默认显示在问题页与仪表盘页。同时隐藏标题、附加信息和操作按钮headerfalseheaderfalse是“一键收起标题区”的开关它隐含影响其下的additional_info与action_buttons。additional_info默认显示。隐藏灰色文字“Edited X days ago by FirstName LastName”以及包含集合、数据库、表名的面包屑headerfalseadditional_infofalseaction_buttons默认显示在问题页面前提是header已启用。隐藏Filter、Summarize、查询构建器按钮等操作按钮headerfalseaction_buttonsfalse六、数据选择器与实体类型data_pickerdata_picker控制问题编辑器中“选择数据源”的菜单形态。默认行为是显示表和模型models排除指标metrics和问题questions;使用简单下拉菜单当条目数达到 100 个及以上时Metabase 会自动升级为完整的数据选择器full data picker。显式使用完整数据选择器data_pickerstaged源码中该选项的合法值只有两个staged与flat定义在 store/embedding-data-picker.tsexport type EmbeddingDataPicker staged | flat;且默认状态为dataPicker: flat见 embedding-data-picker.ts 中的DEFAULT_EMBEDDING_DATA_PICKER_STATE。参数解析管线中的normalizeDataPickerembed.ts 第 161-176 行会过滤掉任何不在白名单中的值——即传了非法的data_picker值时选项被整体忽略而不是报错。entity_types控制数据选择器、侧边栏和 New 按钮菜单中可见的实体类型。例如只显示表entity_typestable此时侧边栏将不再显示模型。可用实体类型共三种tablemodelquestion仅在data_pickerstaged时生效多种类型用逗号分隔entity_typestable,modeldata_pickerstagedentity_typestable,model,question即上文完整数据选择器截图所对应的配置。question只在多级选择器中生效的原因在 store/embedding-data-picker.ts 的类型注释中写得很明确简单选择器追求“轻嵌入”体验question是为习惯在交互式嵌入中直接复用已保存问题的用户后来追加的能力因此成为特例。逗号分隔参数的解析细节entity_typestable,model这种“一个参数携带多个值”的写法并不是直接透传的。embed.ts 中的normalizeEntityTypesCommaSeparatedSearchParameter第 98-118 行会先把entity_typesvalue1,value2改写成entity_typesvalue1entity_typesvalue2这种符合URLSearchParams多值格式的形式然后再交给parseSearchOptions。整个解析流程是一个组合管线第 91-96 行URL.search → normalizeEntityTypesCommaSeparatedSearchParameter // 逗号拆分 → parseSearchOptions // 解析为键值对象 → excludeNonInteractiveEmbeddingOptions // 白名单过滤 → normalizeProperties (normalizeEntityTypes normalizeDataPicker) // 归一化normalizeEntityTypesembedding-data-picker.ts 第 60-78 行保证entity_types永远不会变成空数组合法值过滤后若为空则回退到默认值[model, table]DEFAULT_EMBEDDING_ENTITY_TYPES否则按白名单[model, table, question]过滤。七、界面语言locale通过参数直接改变嵌入界面的语言例如设为西班牙语localees完整的语言支持与后端多语言机制见本地化文档仓库中的语言包文件位于 locales 目录。八、参数组合实战把上述参数组合起来可以覆盖常见的嵌入形态# 只读浏览形态无顶栏、无侧栏、无头部信息 top_navfalseside_navfalseheaderfalse # “内容优先”形态保留顶栏但不显示 Logo开启搜索与 New 按钮 logofalsetop_navtruesearchtruenew_buttontrue # 面向只关心表数据、且条目很多的场景完整数据选择器 限定实体类型 data_pickerstagedentity_typestable九、小结与源码索引URL 参数只是“开关”它们不改变权限与数据可见性只影响界面呈现所有参数都经过白名单过滤与值归一化非法值被静默忽略而非抛出错误因此可以放心把多个参数拼在return_to里top_nav、header这类父级开关会连带控制子元素entity_types与data_picker共同决定数据选择形态其中question仅在staged下生效。关键源码位置便于继续深入关注点文件默认选项常量、白名单、URL 解析管线frontend/src/metabase/redux/embed/embed.ts选项类型定义含side_nav: boolean \| defaultfrontend/src/metabase/redux/store/embed.ts实体类型与数据选择器的默认值、归一化frontend/src/metabase/redux/embedding-data-picker.ts选择器类型staged \| flat与question特例注释frontend/src/metabase/redux/store/embedding-data-picker.ts路由驱动的导航栏收起正则frontend/src/metabase/redux/app.ts顶栏隐藏时强制展开侧栏的兜底逻辑frontend/src/metabase/selectors/app.tslogo×side_nav组合行为的单元测试frontend/src/metabase/app/nav/AppBar.unit.spec.tsx顶栏/侧栏可见性测试top_navfalseside_navtrue等组合frontend/src/metabase/app/nav/Navbar.unit.spec.tsx【免费下载链接】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），仅供参考 Metabase Full App Embedding UI Components：用 URL 参数定制嵌入式界面
Metabase Full App Embedding UI Components用 URL 参数定制嵌入式界面【免费下载链接】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本文讲解如何通过在全应用嵌入full app embedding的 URL 末尾追加查询参数精细控制 Metabase 嵌入界面的各个 UI 组件顶栏top nav、侧边导航side nav、面包屑、Logo、页面头部、操作按钮、搜索框、New 按钮、数据选择器data picker、实体类型entity types以及界面语言locale。文章不仅完整给出每个参数的默认值、取值与组合规则还结合前端源码Redux 切片、参数解析管线、导航栏可见性选择器说明这些参数在运行时如何被解析、归一化并最终影响组件渲染帮助你在自有产品中把 Metabase 嵌入到“只留你需要的界面”的程度。一、整体思路把 UI 开关拼进嵌入 URL在全应用嵌入场景下你通常通过一个 iframe 指向 Metabase 的某个页面例如经过 SSO 登录后的/auth/sso或/collection/...等路由。Metabase 允许你在嵌入 URL 的查询字符串中附加一组“交互式嵌入选项”用来开关界面元素your_embedding_url?top_navfalseside_navfalse如果目标是修改配色或字体应改用外观定制中的主题配置而不是 URL 参数如果需要更细粒度的组件级控制例如单独嵌入一个查询构建器或问题卡片官方文档建议评估模块化嵌入Modular embedding。用 URL Constructor 拼装参数推荐写法在 Node.js 服务侧跳转 SSO 时使用URL对象而不是手工字符串拼接可以避免转义问题。官方文档给出的示例如下const mods logofalsetop_navtruesearchtruenew_buttontrue; app.get(/sso/metabase, restrict, (req, res) { const ssoUrl new URL(/auth/sso, METABASE_SITE_URL); ssoUrl.searchParams.set(jwt, signUserToken(req.session.user)); ssoUrl.searchParams.set(return_to, ${req.query.return_to ?? /}?${mods}); res.redirect(ssoUrl); });注意这里的技巧UI 参数不能直接挂在 SSO URL 上而是要拼进return_to的查询串里这样 SSO 完成后重定向回目标页面时参数才会被保留下来。实践提示当嵌入页面使用点击行为click behavior时要让查询参数在跳转后仍然保留需要在管理设置中将 Site URL 配置为你的 Metabase 服务器地址。二、参数速览表参数默认值作用top_navtrue显示顶部导航栏整体开关为false时其子元素search、new_button、breadcrumbs自动隐藏side_navdefault仅/collection与主页显示其余路由默认收起允许用户展开/收起侧边导航searchfalse隐藏顶栏中的搜索框new_buttonfalse隐藏顶栏中的 New按钮创建查询/仪表盘breadcrumbstrue显示顶栏中的集合面包屑logotrue打开/收起侧边栏的 Logo或通用侧栏图标headertrue问题/仪表盘页面的标题区域additional_infotrue标题下方的“X 天前由某人编辑”等附加信息与面包屑action_buttonstrue问题页面的 Filter、Summarize、查询构建器等操作按钮locale跟随用户设置界面语言如localeesentity_typestable,model数据选择器、侧边栏、New 菜单中可见的实体类型data_pickerflat简单下拉问题中数据源选择器可选staged完整多级选择器上表默认值可以直接在前端源码中得到印证embed.ts 中定义了默认选项常量第 24-36 行export const DEFAULT_INTERACTIVE_EMBEDDING_OPTIONS: InteractiveEmbeddingOptionsState { font: undefined, top_nav: true, side_nav: default, search: false, new_button: false, breadcrumbs: true, logo: true, header: true, additional_info: true, action_buttons: true, };其中side_nav的类型是boolean | default见 store/embed.ts 中的InteractiveEmbeddingOptions接口第 6-19 行不传该参数时即default语义——侧边导航只在集合浏览器与主页路由出现其余路由自动收起显式传side_navtrue后用户才可以在任意页面手动展开它。完整的选项键集合由同一文件中的ALLOWED_INTERACTIVE_EMBEDDING_OPTIONS第 39-45 行给出默认常量全部键加上额外并入的entity_types和data_picker两个键。解析 URL 时会先经过excludeNonInteractiveEmbeddingOptions即URL 中出现的其它无关参数如jwt、return_to会被剔除只有这份白名单内的键才会进入嵌入选项状态。三、顶栏及其子组件top_nav默认显示。隐藏整条顶部导航栏top_navfalsetop_nav控制的是整条顶栏的可见性设为false时其子元素search、new_button、breadcrumbs会自动全部隐藏设为true时可以单独控制这三个子元素。search默认隐藏。在顶栏显示搜索框top_navtruesearchtruenew_button默认隐藏。显示用于创建查询或仪表盘的 New按钮top_navtruenew_buttontruebreadcrumbs默认显示在顶栏中。集合面包屑collection breadcrumbs展示条目所在集合的路径该参数不影响用户拥有查询构建器权限时看到的 Data 面包屑。隐藏方式breadcrumbsfalse四、侧边导航与 Logoside_nav默认行为侧边导航在/collection路由和主页上显示其余路由隐藏。允许用户在嵌入中展开/收起侧边栏top_navtrueside_navtrue导航栏“随路由收起”的行为可以从源码得到印证redux/app.ts 中的isNavbarOpenForPathname第 67-74 行定义了使导航栏收起的路由正则const PATH_WITH_COLLAPSED_NAVBAR /\/(model\b|question\b|dashboard|metabot|document|explore).*/; export function isNavbarOpenForPathname(pathname: string, prevState: boolean) { return ( !isSmallScreen() !PATH_WITH_COLLAPSED_NAVBAR.test(pathname) prevState ); }也就是说进入/model、/question、/dashboard等具体内容页时导航栏会自动收起——这正是side_nav默认值在文档中描述为“仅/collection和主页显示”的底层机制。logoLogo 用于打开/收起侧边导航默认true。其行为与side_nav组合后按如下四种情况生效logoside_nav结果truetrue侧边栏中显示你配置的 Logotruefalse没有侧边栏也没有 Logo 功能falsetrue显示通用的侧栏图标默认灰色悬停时为主题品牌色falsefalse无侧边栏、无 Logo面包屑靠左对齐这四种组合在 AppBar.unit.spec.tsx 的单元测试中被逐一覆盖例如“logo 隐藏但 side_nav 开启时始终显示侧栏切换图标”“两者都关闭时不显示 Logo 也不显示切换按钮”等断言与上表一一对应。另外还有一个容易忽略的兜底逻辑selectors/app.ts 中当top_navfalse但side_navtrue时侧边栏会被强制展开——否则一旦顶栏隐藏用户将没有任何入口可以打开侧边栏。五、问题/仪表盘页的头部区域header默认显示在问题页与仪表盘页。同时隐藏标题、附加信息和操作按钮headerfalseheaderfalse是“一键收起标题区”的开关它隐含影响其下的additional_info与action_buttons。additional_info默认显示。隐藏灰色文字“Edited X days ago by FirstName LastName”以及包含集合、数据库、表名的面包屑headerfalseadditional_infofalseaction_buttons默认显示在问题页面前提是header已启用。隐藏Filter、Summarize、查询构建器按钮等操作按钮headerfalseaction_buttonsfalse六、数据选择器与实体类型data_pickerdata_picker控制问题编辑器中“选择数据源”的菜单形态。默认行为是显示表和模型models排除指标metrics和问题questions;使用简单下拉菜单当条目数达到 100 个及以上时Metabase 会自动升级为完整的数据选择器full data picker。显式使用完整数据选择器data_pickerstaged源码中该选项的合法值只有两个staged与flat定义在 store/embedding-data-picker.tsexport type EmbeddingDataPicker staged | flat;且默认状态为dataPicker: flat见 embedding-data-picker.ts 中的DEFAULT_EMBEDDING_DATA_PICKER_STATE。参数解析管线中的normalizeDataPickerembed.ts 第 161-176 行会过滤掉任何不在白名单中的值——即传了非法的data_picker值时选项被整体忽略而不是报错。entity_types控制数据选择器、侧边栏和 New 按钮菜单中可见的实体类型。例如只显示表entity_typestable此时侧边栏将不再显示模型。可用实体类型共三种tablemodelquestion仅在data_pickerstaged时生效多种类型用逗号分隔entity_typestable,modeldata_pickerstagedentity_typestable,model,question即上文完整数据选择器截图所对应的配置。question只在多级选择器中生效的原因在 store/embedding-data-picker.ts 的类型注释中写得很明确简单选择器追求“轻嵌入”体验question是为习惯在交互式嵌入中直接复用已保存问题的用户后来追加的能力因此成为特例。逗号分隔参数的解析细节entity_typestable,model这种“一个参数携带多个值”的写法并不是直接透传的。embed.ts 中的normalizeEntityTypesCommaSeparatedSearchParameter第 98-118 行会先把entity_typesvalue1,value2改写成entity_typesvalue1entity_typesvalue2这种符合URLSearchParams多值格式的形式然后再交给parseSearchOptions。整个解析流程是一个组合管线第 91-96 行URL.search → normalizeEntityTypesCommaSeparatedSearchParameter // 逗号拆分 → parseSearchOptions // 解析为键值对象 → excludeNonInteractiveEmbeddingOptions // 白名单过滤 → normalizeProperties (normalizeEntityTypes normalizeDataPicker) // 归一化normalizeEntityTypesembedding-data-picker.ts 第 60-78 行保证entity_types永远不会变成空数组合法值过滤后若为空则回退到默认值[model, table]DEFAULT_EMBEDDING_ENTITY_TYPES否则按白名单[model, table, question]过滤。七、界面语言locale通过参数直接改变嵌入界面的语言例如设为西班牙语localees完整的语言支持与后端多语言机制见本地化文档仓库中的语言包文件位于 locales 目录。八、参数组合实战把上述参数组合起来可以覆盖常见的嵌入形态# 只读浏览形态无顶栏、无侧栏、无头部信息 top_navfalseside_navfalseheaderfalse # “内容优先”形态保留顶栏但不显示 Logo开启搜索与 New 按钮 logofalsetop_navtruesearchtruenew_buttontrue # 面向只关心表数据、且条目很多的场景完整数据选择器 限定实体类型 data_pickerstagedentity_typestable九、小结与源码索引URL 参数只是“开关”它们不改变权限与数据可见性只影响界面呈现所有参数都经过白名单过滤与值归一化非法值被静默忽略而非抛出错误因此可以放心把多个参数拼在return_to里top_nav、header这类父级开关会连带控制子元素entity_types与data_picker共同决定数据选择形态其中question仅在staged下生效。关键源码位置便于继续深入关注点文件默认选项常量、白名单、URL 解析管线frontend/src/metabase/redux/embed/embed.ts选项类型定义含side_nav: boolean \| defaultfrontend/src/metabase/redux/store/embed.ts实体类型与数据选择器的默认值、归一化frontend/src/metabase/redux/embedding-data-picker.ts选择器类型staged \| flat与question特例注释frontend/src/metabase/redux/store/embedding-data-picker.ts路由驱动的导航栏收起正则frontend/src/metabase/redux/app.ts顶栏隐藏时强制展开侧栏的兜底逻辑frontend/src/metabase/selectors/app.tslogo×side_nav组合行为的单元测试frontend/src/metabase/app/nav/AppBar.unit.spec.tsx顶栏/侧栏可见性测试top_navfalseside_navtrue等组合frontend/src/metabase/app/nav/Navbar.unit.spec.tsx【免费下载链接】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），仅供参考