Metabase 集合浏览器嵌入完全参考metabase-browserWeb Component 属性与 React SDKCollectionBrowserProps 指南【免费下载链接】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 的集合浏览器Collection Browser组件让外部应用可以直接嵌入一个可浏览、可搜索的集合目录用户点击即可打开其中的仪表盘dashboard与问题question。本文以 Metabase 官方参考文档 browser-reference.md 为骨架完整展开metabase-browserWeb Component 的 9 个属性与 React SDKCollectionBrowser的 8 个 Props并结合 嵌入集合浏览器主文档、组件属性片段、SDK Props 片段 及 SDK 类型定义给出每个参数的取值、默认值与实战用法。读完本文你将能熟练配置两种嵌入方式并理解read-only、initial-collection、onClick等关键参数背后的权限与保存行为。两种嵌入方式与适用场景Metabase 集合浏览器提供两种嵌入形态二者的能力边界差异很大选择前需要先明确需求维度Web Componentmetabase-browserReact SDKCollectionBrowser形态一个完整自洽的浏览器一个列表 面包屑点击行为在嵌入内打开仪表盘/问题自带面包屑返回只触发onClick回调由你的应用决定下一步新建按钮内置New question/New dashboard按钮无需要自己实现保存能力可配合read-onlyfalse开启编辑保存不负责保存由宿主应用自行搭建流程前置条件Pro/Enterprise SSO 认证嵌入Pro/Enterprise 模块化嵌入 SDKModular embedding SDK两条路线的共同前提是查看集合浏览器的用户必须拥有 Metabase 账号因为 Metabase 依据集合权限计算每个人能看到的内容。因此集合浏览器只适用于通过 SSO 登录用户的嵌入场景无法用于访客嵌入guest embed。Web Componentmetabase-browser属性参考metabase-browser是浏览器端的自定义元素属性即其配置接口。完整属性定义见 MetabaseBrowserAttributes.md汇总如下属性类型说明collection-entity-typesstring[]浏览器中展示的实体类型可选值collection、dashboard、question、model。可选collection-page-sizenumber集合浏览器每页展示的条目数量。可选collection-visible-columnsstring[]集合列表中展示的列可选值type、name、description、lastEditedBy、lastEditedAt、archive。可选data-picker-entity-typesstring[]新建问题时的数据选择器data picker中展示的实体类型可选值model、table。可选enable-entity-navigationboolean是否启用内部实体导航跳转到其他仪表盘/问题的链接。可选默认falseinitial-collectionstring \| number起始集合常规 ID、entity ID、root顶层 Our Analytics、personal查看者个人集合、tenant查看者的租户集合、all展示查看者可访问的全部内容。非租户成员使用tenant会报错read-onlyboolean内容管理器是否处于只读模式。true时可交互筛选、汇总、下钻但不能保存false时可创建与编辑。可选默认truewith-new-dashboardboolean是否显示New dashboard按钮仅当read-onlyfalse时生效。可选默认truewith-new-questionboolean是否显示New question按钮。可选默认true属性均为可选但实际使用中最少要指定initial-collection否则组件没有明确起点。最小可用示例metabase-browser initial-collection123/metabase-browser属性传值与字符串化规则Web Component 的属性值本质是字符串数组、数字等类型需要按框架约定序列化。官方建议如果属性值外层使用双引号内部改用单引号例如metabase-browser initial-collection123 collection-entity-types[collection, dashboard] >metabase-browser initial-collection123 read-onlyfalse/metabase-browser保存目标遵循两条规则新建的问题或仪表盘会保存到用户当前浏览的集合。保存对话框会预选该集合用户也可选择其他有写入权限的集合取决于集合权限。每个人的个人集合始终可写因此即使未授予任何策展访问权限个人集合也会作为选项出现。对从浏览器打开的仪表盘/问题所做的修改会覆盖原件无论原件存放在哪里若用户改为另存为新问题则新问题保存到当前浏览的集合。两种情况都没有集合选择器用户无法将内容另存到别处。租户tenant场景下保存选择器中会出现两个可写选项租户集合Metabase 标注为Our data和用户个人集合。租户集合与个人集合都会自动授予不可关闭的策展权限因此租户集合浏览器始终提供可保存的位置而租户用户无权访问Our analytics该选项不会出现。需要注意metabase-browser没有类似metabase-question上target-collection那样可把保存目标固定到某个集合的属性这一点在图表嵌入保存说明中有对照说明。新建按钮with-new-question与with-new-dashboard浏览器可在列表上方显示New question与New dashboard两个按钮两者行为有细微差别with-new-question默认true且忽略read-only——即使是只读浏览器也会显示该按钮。用户点击可打开查询构建器自由探索但无法保存构建结果也无法覆盖既有问题。with-new-dashboard默认true但仅在read-onlyfalse时显示。任一按钮仅对拥有当前集合策展访问权限的用户显示。因此默认的metabase-browser只会给用户New question按钮加上read-onlyfalse后两个按钮都会出现。如需关闭某个按钮将其设为falsemetabase-browser initial-collection123 read-onlyfalse with-new-dashboardfalse /metabase-browser上例中用户只能看到New question看不到New dashboard。用data-picker-entity-types限制新建数据来源New question按钮打开查询构建器时默认展示用户有权访问的全部表、模型和已保存问题。data-picker-entity-types用于收窄数据选择器中的实体类型例如只允许基于模型models构建让用户建立在经过治理的数据之上而非原始表metabase-browser initial-collection123 read-onlyfalse >metabase-browser initial-collection123 enable-entity-navigationtrue /metabase-browser即便开启跳转用户仍只能打开其集合权限允许的内容。React SDKCollectionBrowserProps 参考React SDK 的CollectionBrowser组件模块化嵌入 SDKPro/Enterprise 功能负责列出集合内容并上报点击事件。与 Web Component 不同它不打开任何内容、不提供新建按钮——点击行为由你决定新建/保存流程也需在宿主应用中自行实现。它自带面包屑因此用户可以在子集合间自由进出。组件函数签名见 CollectionBrowser.mdfunction CollectionBrowser(props: CollectionBrowserProps): Element。完整 Props 定义见 CollectionBrowserProps.md汇总如下Prop类型说明className?string添加到根元素的自定义 class 名collectionId?SdkBrowserCollectionId要展示的集合数字 ID、实体 ID 字符串、personal、tenant、root、all。默认personalEmptyContentComponent?ComponentType \| null集合为空时展示的组件onClick?(item: MetabaseCollectionItem) void点击某个条目时触发的回调pageSize?number每页展示条目数默认25showDashboardQuestions?boolean是否在集合已保存问题旁展示属于仪表盘的问题默认false保持列表聚焦集合内容style?CSSProperties添加到根元素的自定义样式对象visibleColumns?CollectionBrowserListColumns[]集合条目表展示的列不传则全部展示visibleEntityTypes?(collection \| dashboard \| question \| model)[]可见的实体类型不传则全部展示完整示例来自官方 SDK 示例片段 collection-browser.tsximport React from react; import { CollectionBrowser, MetabaseProvider, defineMetabaseAuthConfig, } from metabase/embedding-sdk-react; const authConfig defineMetabaseAuthConfig({ metabaseInstanceUrl: https://your-metabase.example.com, }); export default function App() { const collectionId 123; // This is the collection ID you want to browse return ( MetabaseProvider authConfig{authConfig} CollectionBrowser collectionId{collectionId} pageSize{10} visibleEntityTypes{[dashboard, question, collection]} / /MetabaseProvider ); }组件必须包裹在配置了认证信息的MetabaseProvider内认证配置方式参见认证文档与 SDK 快速开始。collectionId与 Web Component 的initial-collection对应关系collectionId是 React 侧的起点配置取值与 Web Component 的initial-collection一一对应数字集合 ID、实体 ID 字符串如nT4gT_MOnU1uJ1zLsGaTV、personal、tenant、rootOur analytics、all根集合 租户集合 个人集合的列表。唯一区别是collectionId默认为personal——如果不想让用户从自己的个人集合开始必须显式传值。visibleColumns与列类型visibleColumns接受CollectionBrowserListColumns联合类型可取值与 Web Component 的collection-visible-columns一致type CollectionBrowserListColumns | type | name | description | lastEditedBy | lastEditedAt | archive;不传该 prop 时展示全部列传入部分值时仅渲染指定列常用于精简列表宽度。onClick与MetabaseCollectionItem点击载荷onClick是 React SDK 方式下交互的核心你可以用它渲染某个 Metabase 组件、在应用内路由跳转或打开一个模态框。回调参数item的类型为MetabaseCollectionItem其关键字段包括id集合条目 IDSdkCollectionId。entity_id?跨环境不变的实体 ID。model条目模型类型字符串其中card表示问题questiondataset表示模型model——判断点击对象时以此字段为准。name、description名称与描述。last-edit-info?最近编辑者信息email、first_name、last_name、id、timestamp。type?集合类型可取值包括model、question、metric、trash、instance-analytics、remote-synced、library、shared-tenant-collection、tenant-specific-root-collection等。一个需要特别注意的交互怪癖用户点击集合collection时CollectionBrowser会既导航进入该集合又触发onClick。因此在处理函数中应跳过collection类型否则会触发双重跳转。官方示例模式如下onClick{(item) { if (item.model collection) { // CollectionBrowser 已经处理了导航这里直接返回 return; } // item.model card 是问题item.model dataset 是模型 // 在此渲染对应组件、路由跳转或打开模态框 }}完整点击处理示例参见 SDK 片段 collection-browser-click.tsx。空状态与列表聚焦EmptyContentComponent用于自定义集合为空时的展示传null可隐藏空状态区域。showDashboardQuestions控制是否把属于仪表盘的问题也列在集合中默认false保持列表聚焦于集合自身内容设为true则并排展示仪表盘下的问题方便用户在同一视图中发现更多内容。实战组合建议结合两种方式的能力差异给出常见需求的最小配置开箱即用的完整浏览器带打开、面包屑、新建按钮Web Component initial-collectionread-onlyfalse。严格只读的目录Web Component 默认配置即可但注意with-new-question默认仍会显示它忽略read-only如需完全隐藏请显式设置with-new-questionfalse。只展示模型、不让用户触碰原始表data-picker-entity-types[model]。宿主应用深度定制点击行为React SDKCollectionBrowseronClick自行路由并记得在处理器中跳过model collection。进一步阅读嵌入集合浏览器本文参数的完整使用场景与配置流程Dashboard 组件参考与 Question 组件参考同一参考体系下的其他组件模块化嵌入组件总览SDK 组件全景集合权限理解可见性与保存目标的基础序列化与实体 ID跨环境内容迁移时实体 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），仅供参考