Metabase Embedding SDK 的 CollectionBrowser 组件：集合浏览器的 API 详解与实战指南

Metabase Embedding SDK 的 CollectionBrowser 组件集合浏览器的 API 详解与实战指南【免费下载链接】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/metabaseCollectionBrowser 是 Metabase Embedding SDKmetabase/embedding-sdk-react提供的开箱即用组件用于在宿主应用中嵌入一个可交互的集合Collection浏览器展示集合及其中的仪表盘、问题、模型等内容。本文以 SDK 的 API 文档为主体结合当前仓库的前端源码与单元测试完整讲解CollectionBrowser的函数签名、全部 props 参数、集合 ID 定位方式、列裁剪与实体过滤并给出可直接运行的嵌入示例与底层实现原理帮助你快速把 Metabase 的内容浏览与导航能力集成到自己的 React 应用中。一、组件概览函数签名与返回值在 API 文档 中CollectionBrowser被定义为如下函数签名function CollectionBrowser(props: CollectionBrowserProps): Element;它是一个标准 React 函数组件参数接收一个props对象类型为CollectionBrowserProps所有属性均可选。返回值一个 ReactElement对应官方文档中引用的 DefinitelyTyped 的 React 类型定义。该组件的作用是“允许你浏览集合及其中的条目”A component that allows you to browse collections and their items例如集合、仪表盘、保存的问题card、模型dataset等。在 SDK 的公共导出清单 中CollectionBrowser是sdkBundleExports导出的首批组件之一与InteractiveDashboard、InteractiveQuestion、StaticQuestion等并列说明它是 SDK 的核心 UI 组件之一。二、props 参数全解CollectionBrowser的全部配置都通过CollectionBrowserProps传入。下表完整列出所有属性继承自 API 文档的属性表并补充了源码中的默认值与取值说明属性类型说明className?string添加到根元素的自定义 CSS 类名。collectionId?SdkBrowserCollectionId要展示的集合。可以是数字集合 ID、实体 ID 字符串、personal、tenant、root、all。默认值为personal。EmptyContentComponent?ComponentType|null当集合中没有条目时展示的组件。默认null此时渲染 SDK 内置的空状态EmptyState。onClick?(item: [MetabaseCollectionItem](https://link.gitcode.com/i/e5c666b820da847a76ee28672c1bff7f)) void点击某个条目时调用的回调函数。pageSize?number每页展示的条目数量。默认值为 25对应源码常量COLLECTION_PAGE_SIZE。showDashboardQuestions?boolean是否在集合保存的问题之外同时展示隶属于某个仪表盘的问题。设为true时展示默认false保持列表聚焦于集合内容。style?CSSProperties添加到根元素的自定义样式对象。visibleColumns?CollectionBrowserListColumns[]集合条目表格中展示的列。不传时展示全部列。visibleEntityTypes?(collection|dashboard|question|model)[]可见的实体类型。不传时展示全部实体。这些默认值在源码中有明确印证。看 CollectionBrowser.tsx 中的组件解构export const CollectionBrowserInner ({ collectionId, onClick, pageSize COLLECTION_PAGE_SIZE, // 默认 25 visibleEntityTypes [...USER_FACING_ENTITY_NAMES], // 默认四种实体全开 showDashboardQuestions false, EmptyContentComponent null, visibleColumns COLLECTION_BROWSER_LIST_COLUMNS, // 默认列集合 className, style, }: CollectionBrowserProps) { ... };其中COLLECTION_PAGE_SIZE来自metabase/collections/components/CollectionContent而USER_FACING_ENTITY_NAMES定义为[collection, dashboard, question, model]CollectionBrowser.tsx。此外Props 校验由 CollectionBrowser.schema.ts 中的 Yup schema 完成它只允许上述属性.noUnknown()任何未知属性都会被拒绝这保证了宿主应用传参时的类型与运行时双重校验一致性。三、collectionId五种定位集合的方式collectionId的类型是SdkBrowserCollectionIdtype SdkBrowserCollectionId SdkCollectionId | all;而SdkCollectionId定义为type SdkCollectionId number | personal | root | tenant | SdkEntityId;其中SdkEntityId是一个字符串标记类型type SdkEntityId string {};见 SdkEntityId.md。综合源码注释types/collection.tscollectionId支持以下取值取值含义数字集合 ID。可以从 Metabase 实例中集合页面的 URL 里找到例如http://localhost:3000/collection/1-my-collection中的 ID 就是1。实体 ID 字符串例如nT4gT_MOnU1uJ1zLsGaTV即集合的entity_id对内容迁移/多环境同步场景更稳定。personal当前用户的个人收藏Personal Collection。这是默认值。tenant当前用户的租户集合Tenant Collection面向多租户tenants能力。root根集合即 Metabase 的 Our analytics。allSdkBrowserCollectionId独有的虚拟只读顶层视图展示当前用户有权访问的一切内容其中包含根集合、租户集合与当前用户的个人收藏。注意源码注释明确指出核心应用中的CollectionId还包含root | users与trash但 SDK 公共 API刻意不包含这两种types/collection.ts这是 SDK 对外接口与内部实现的边界。collectionId不传时的默认行为在 CollectionBrowser.tsx 中实现const CollectionBrowserWrapper ({ collectionId personal, // 默认进入个人收藏 ...restProps }: CollectionBrowserProps) { ... if (!collectionId) { return CollectionNotFoundError id{collectionId} /; } return CollectionBrowserInner collectionId{collectionId} {...restProps} /; };四、可见实体类型与实体名映射visibleEntityTypes控制列表中出现的实体类型可选项为collection、dashboard、question、model。注意这里使用的是面向用户的命名与 Metabase 内部的model字段值并不完全一致。源码中的ENTITY_NAME_MAPCollectionBrowser.tsx完成了映射const ENTITY_NAME_MAP: PartialRecordUserFacingEntityName, CollectionItemModel { collection: collection, dashboard: dashboard, question: card, // 问题在内部叫 card model: dataset, // 模型在内部叫 dataset };也就是说用户在界面上看到的 question 在 Metabase API 中的model是card而 model 对应dataset。这个细节在编写onClick回调时尤其重要见下文第六节同时也被 SDK 的单元测试专门覆盖onClick收到的是包含内部model值的完整条目对象见 CollectionBrowser.unit.spec.tsx。五、可见列CollectionBrowserListColumnsvisibleColumns决定条目表格展示哪些列其类型CollectionBrowserListColumns定义如下type CollectionBrowserListColumns | type // 类型图标列 | name // 名称 | description// 描述 | lastEditedBy// 最后编辑人 | lastEditedAt// 最后编辑时间 | archive; // 归档操作不传visibleColumns时源码默认展示以下列CollectionBrowser.tsxconst COLLECTION_BROWSER_LIST_COLUMNS: CollectionBrowserListColumns[] [ type, name, lastEditedBy, lastEditedAt, archive, ];也就是说默认并不包含description列需要在visibleColumns中显式加入。这一点在单元测试中有明确断言“默认不应包含 Description 列”“显式传入[type, name, description]时才展示描述列”见 CollectionBrowser.unit.spec.tsx。另一个值得注意的细节在collectionIdall的虚拟根视图中合成出来的行根集合、租户集合、个人收藏不携带编辑信息、也不能被归档因此lastEditedBy、lastEditedAt、archive三列会被自动过滤掉只保留type与name源码见 CollectionBrowser.tsx测试见 CollectionBrowser.unit.spec.tsx。六、onClick 回调与 MetabaseCollectionItemonClick在用户点击条目时触发参数是MetabaseCollectionItem对应源码类型 types/collection.tstype MetabaseCollectionItem { collection_namespace?: string | null; description: string | null; entity_id?: SdkEntityId; id: SdkCollectionId; is_remote_synced?: boolean; last-edit-info?: { email: string; first_name: string | null; id: SdkUserId; last_name: string | null; timestamp: string; }; model: string; // 内部 model 名collection / dashboard / card / dataset ... name: string; namespace?: string | null; type?: instance-analytics | trash | remote-synced | library | ... | null; };官方示例 collection-browser-click.tsx 演示了如何利用model字段区分条目类型并切换到对应组件import React, { useState } from react; import { CollectionBrowser, InteractiveDashboard, InteractiveQuestion, type MetabaseCollectionItem, } from metabase/embedding-sdk-react; export default function BrowseAndOpen() { const [dashboardId, setDashboardId] useStatenumber | null(null); const [questionId, setQuestionId] useStatenumber | null(null); const handleClick (item: MetabaseCollectionItem) { // Metabase 的内部命名与用户看到的不同 // question 在内部是 cardmodel 在内部是 dataset。 if (item.model dashboard) { setDashboardId(item.id as number); } else if (item.model card || item.model dataset) { setQuestionId(item.id as number); } }; if (dashboardId) { return InteractiveDashboard dashboardId{dashboardId} /; } if (questionId) { return InteractiveQuestion questionId{questionId} /; } return CollectionBrowser collectionIdpersonal onClick{handleClick} /; }这段代码展示了一个典型场景浏览 → 点击 → 在宿主应用中打开对应的InteractiveDashboard或InteractiveQuestion把“集合浏览”与“内容展示”串成完整的数据应用体验。注意id的类型是SdkCollectionId即可能是数字、特殊字符串或实体 ID 字符串当确定条目是 dashboard/card 时示例通过as number断言后传给组件。测试用例还验证了 “Our analytics” 占位符会被映射回真实的根集合 IDroot确保onClick与后续 API 请求拿到的都是真实 ID见 CollectionBrowser.unit.spec.tsx。七、完整可运行示例官方提供的最小可运行示例 collection-browser.tsx 如下import 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; // 这是你想浏览的集合 ID return ( MetabaseProvider authConfig{authConfig} CollectionBrowser collectionId{collectionId} pageSize{10} visibleEntityTypes{[dashboard, question, collection]} / /MetabaseProvider ); }要点拆解必须包裹在MetabaseProvider中CollectionBrowser依赖MetabaseProvider提供的认证配置defineMetabaseAuthConfig与全局状态。更完整的认证配置说明可参考 SDK 配置文档 与 MetabaseProviderProps。collectionId{123}直接传入数字 ID对应 Metabase 中某个具体集合。pageSize{10}每页展示 10 条覆盖默认的 25 条。visibleEntityTypes{[dashboard, question, collection]}只展示仪表盘、问题与子集合隐藏模型model。该示例演示了最基础的嵌入方式实际部署时还需要先完成 Embedding SDK 的认证接入JWT / API Key / SAML可参考 SDK 快速开始。八、源码级实现原理从实现上看CollectionBrowser内部由若干层协作完成全部位于 CollectionBrowser.tsx公共包装层Public Component Wrapper导出的CollectionBrowser通过Object.assign(withPublicComponentWrapper(...), { schema })包装CollectionBrowser.tsx提供加载态、错误态等统一外壳。特别注意该组件supportsGuestEmbed: false即不支持 Guest 嵌入模式使用时需要带身份的用户上下文。本地化加载CollectionBrowserWrapper会等待 locale 加载完成useLocale().isLocaleLoading为真时渲染SdkLoader避免列表文案闪烁CollectionBrowser.tsx。集合数据解析useCollectionData(collectionId)负责把personal、tenant、root、all等特殊值解析为真实的内部集合 ID并处理 403 等加载错误CollectionBrowser.tsx。“all” 虚拟根模式collectionId all时组件不进入任何真实集合而是调用useAllCollectionsItems拉取根集合、租户集合与个人收藏的列表用ItemsTable渲染该列表独立分页usePaginationPaginationControls并且面包屑会呈现一个虚拟的 “All collections” 静态入口CollectionBrowser.tsx。常规集合列表非 “all” 模式下渲染CollectionItemsTable将pageSize、models由visibleEntityTypes映射而来、showDashboardQuestions、visibleColumns逐一下发CollectionBrowser.tsx。面包屑导航默认开启内部CollectionBreadcrumbs点击子集合时通过setInternalCollectionId深入导航并把面包屑路径与reportLocation上报同步CollectionBrowser.tsx。空状态与错误状态403 时渲染 “You dont have access to this collection” 空状态all根加载失败时渲染SdkError“Failed to load collections”CollectionBrowser.tsx。单元测试 CollectionBrowser.unit.spec.tsx 对以上行为做了系统验证可作为理解组件行为的权威参考默认渲染 Type / Name / Last edited by / Last edited at 四列表头L129-L139无个人收藏的用户如 API Key 场景打开personal时应渲染空状态而不是请求/api/collection/undefinedL141-L166showDashboardQuestions会以show_dashboard_questions查询参数形式传给后端L206-L216collectionIdtenant会解析到当前用户的tenant_collection_idL218-L246all模式下根集合可读则展示 “Our analytics” 行根集合 403 时展示根下集合列表L256-L285虚拟根列表支持分页且返回时页码会重置L463-L505。九、使用注意事项与最佳实践综合 API 文档、官方示例与源码测试实际接入时建议关注以下几点必须登录态CollectionBrowser不支持 Guest 嵌入supportsGuestEmbed: false请确保MetabaseProvider使用带身份JWT / API Key / SAML的认证配置。内部 model 名与用户名词的差异判断条目类型请以item.model的值为准collection/dashboard/card/dataset而不是界面语言question / model。默认列不含 description需要描述列时显式传入visibleColumns{[type, name, description, ...]}。无个人收藏的用户API Key 用户通常没有个人收藏默认collectionIdpersonal会得到空状态而非报错这是预期行为也可以显式改用root或具体集合 ID。all是只读虚拟视图其中不展示编辑信息列适合作为“全库概览”入口。配合其他 SDK 组件使用onClick拿到条目后可切换到InteractiveDashboard、InteractiveQuestion或StaticQuestion完成浏览→打开的闭环需要更多嵌入 UI 能力可查阅 SDK 文档目录 及 组件总览。十、小结CollectionBrowser是 Metabase Embedding SDK 中把“集合内容浏览”能力开放给宿主应用的关键组件。通过collectionId的五种定位方式、visibleEntityTypes与visibleColumns的裁剪、pageSize分页控制以及onClick回调与MetabaseCollectionItem的条目信息你可以低成本地在自己的 React 应用中搭建一个与 Metabase 原生体验一致的集合导航界面再联动InteractiveDashboard、InteractiveQuestion等组件组成完整的数据应用。其实现CollectionBrowser.tsx与测试CollectionBrowser.unit.spec.tsx展示了 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），仅供参考