企业官网建设流程全解析

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/metabase

Metabase 的集合浏览器（Collection Browser）组件让外部应用可以直接嵌入一个可浏览、可搜索的集合目录，用户点击即可打开其中的仪表盘（dashboard）与问题（question）。本文以 Metabase 官方参考文档 browser-reference.md 为骨架，完整展开<metabase-browser>Web Component 的 9 个属性与 React SDKCollectionBrowser的 8 个 Props，并结合 嵌入集合浏览器主文档、组件属性片段、SDK Props 片段 及 SDK 类型定义，给出每个参数的取值、默认值与实战用法。读完本文，你将能熟练配置两种嵌入方式，并理解read-only、initial-collection、onClick等关键参数背后的权限与保存行为。

两种嵌入方式与适用场景

Metabase 集合浏览器提供两种嵌入形态，二者的能力边界差异很大，选择前需要先明确需求：

两条路线的共同前提是：查看集合浏览器的用户必须拥有 Metabase 账号，因为 Metabase 依据集合权限计算每个人能看到的内容。因此集合浏览器只适用于通过 SSO 登录用户的嵌入场景，无法用于访客嵌入（guest embed）。

Web Componentmetabase-browser属性参考

<metabase-browser>是浏览器端的自定义元素，属性即其配置接口。完整属性定义见 MetabaseBrowserAttributes.md，汇总如下：

属性均为可选，但实际使用中最少要指定initial-collection，否则组件没有明确起点。最小可用示例：

<metabase-browser initial-collection="123"></metabase-browser>

属性传值与字符串化规则

Web Component 的属性值本质是字符串，数组、数字等类型需要按框架约定序列化。官方建议：如果属性值外层使用双引号，内部改用单引号，例如：

<metabase-browser initial-collection="123" collection-entity-types="['collection', 'dashboard']" ><metabase-browser initial-collection="123" read-only="false"></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-only="false"时显示。
• 任一按钮仅对拥有当前集合策展访问权限的用户显示。

因此默认的<metabase-browser>只会给用户New question按钮；加上read-only="false"后两个按钮都会出现。如需关闭某个按钮，将其设为false：

<metabase-browser initial-collection="123" read-only="false" with-new-dashboard="false" ></metabase-browser>

上例中用户只能看到New question，看不到New dashboard。

用data-picker-entity-types限制新建数据来源

New question按钮打开查询构建器时，默认展示用户有权访问的全部表、模型和已保存问题。data-picker-entity-types用于收窄数据选择器中的实体类型，例如只允许基于模型（models）构建，让用户建立在经过治理的数据之上而非原始表：

<metabase-browser initial-collection="123" read-only="false" ><metabase-browser initial-collection="123" enable-entity-navigation="true" ></metabase-browser>

即便开启跳转，用户仍只能打开其集合权限允许的内容。

React SDKCollectionBrowserProps 参考

React SDK 的CollectionBrowser组件（模块化嵌入 SDK，Pro/Enterprise 功能）负责列出集合内容并上报点击事件。与 Web Component 不同，它不打开任何内容、不提供新建按钮——点击行为由你决定，新建/保存流程也需在宿主应用中自行实现。它自带面包屑，因此用户可以在子集合间自由进出。组件函数签名见 CollectionBrowser.md：function CollectionBrowser(props: CollectionBrowserProps): Element。

完整 Props 定义见 CollectionBrowserProps.md，汇总如下：

完整示例

来自官方 SDK 示例片段 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; // 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"、"root"（Our 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：集合条目 ID（SdkCollectionId）。
• entity_id?：跨环境不变的实体 ID。
• model：条目模型类型（字符串），其中card表示问题（question），dataset表示模型（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-collection+read-only="false"。
• 严格只读的目录：Web Component 默认配置即可，但注意with-new-question默认仍会显示（它忽略read-only），如需完全隐藏请显式设置with-new-question="false"。
• 只展示模型、不让用户触碰原始表：data-picker-entity-types="['model']"。
• 宿主应用深度定制点击行为：React SDKCollectionBrowser+onClick自行路由，并记得在处理器中跳过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