基于 Metabase Embedded Analytics SDK 的 CreateDashboardModal 组件API 签名、Props 详解与仪表盘创建实战【免费下载链接】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 Embedded Analytics SDKmetabase/embedding-sdk-react允许开发者在自己的 React 应用中直接嵌入仪表盘、问答等分析能力。其中CreateDashboardModal是一个开箱即用的新建仪表盘弹窗组件你只需传入一个onCreate回调即可让用户在嵌入页面中创建仪表盘并拿到创建结果继续做二次编排例如紧接着用EditableDashboard打开新仪表盘进行编辑。本文以仓库中 CreateDashboardModal API 参考文档 为骨架结合 SDK 源码、示例代码与单元测试完整讲解其函数签名、全部 Props、默认行为与典型实战流程。函数签名与核心定位CreateDashboardModal的 TypeScript 签名非常简单function CreateDashboardModal(props: CreateDashboardModalProps): Element;功能创建一个新的仪表盘dashboard。返回值一个 ReactElement即渲染出的模态框Modal界面。参数仅接受一个props对象类型为CreateDashboardModalProps。它由 SDK 的公共导出入口统一暴露位于 sdk-bundle-exports.ts与CollectionBrowser、CreateQuestion、InteractiveQuestion等组件并列属于 SDK 面向应用开发者的公开组件 API。Props 参数详解CreateDashboardModal的全部配置都集中在CreateDashboardModalProps中。下表是官方文档定义详见 CreateDashboardModalProps属性类型说明initialCollectionId?SdkCollectionId初始所在的集合collection即打开弹窗时默认选中的保存位置。可使用root、personal等预定义系统值。isOpen?boolean弹窗是否打开。onClose?() void关闭弹窗的处理函数。onCreate(dashboard: MetabaseDashboard) void仪表盘创建成功后的回调入参为新建的仪表盘实体。targetCollection?SdkCollectionId仪表盘最终保存到的集合。传入后将隐藏保存弹窗中的集合选择器直接保存到该集合。其中SdkCollectionId的定义为见 SdkCollectionId.mdtype SdkCollectionId number | personal | root | tenant | SdkEntityId;即既可以传集合的数字 ID也可以传personal当前用户个人集合、root根集合、tenant租户集合这类语义化字符串或SdkEntityId形式的实体 ID 字符串。各属性的默认值源码确认在 SDK 的实现 CreateDashboardModal.tsx 中两个可选属性有明确的默认值const CreateDashboardModalInner ({ initialCollectionId personal, targetCollection, isOpen true, onCreate, onClose, }: CreateDashboardModalProps) { ... }initialCollectionId默认为personal不传时弹窗会默认选中当前用户的个人集合作为初始位置。isOpen默认为true组件挂载即打开弹窗。onClose与targetCollection无默认值按需传入。属性在源码中的解析逻辑initialCollectionId与targetCollection传入后会通过getCollectionIdValueFromReference/getCollectionIdSlugFromReference来自embedding-sdk-bundle/store/collections解析为具体的集合 ID 与 slug再调用useGetCollectionQuery拉取集合元数据用于弹窗内集合选择器的展示。源码注释还特别指出当集合 slug 为空时会使用skipToken跳过请求以避免发出/api/collection/undefined导致 404。组件在返回 UI 前有两个等待条件if (isLocaleLoading || isCollectionQueryLoading) { return null; }即本地化资源locale未加载完成或集合元数据未拉取完成时组件渲染为空加载完成后才显示弹窗——这保证了弹窗内集合名称、语言文案的准确性。底层实现SDK 包装层与公共核心弹窗CreateDashboardModal并不是从零实现的它采用SDK 包装层 产品公共组件的架构SDK 层CreateDashboardModal.tsx负责处理SdkCollectionId解析、集合查询、本地化等待、埋点上报useTrackSdkComponentMount(CreateDashboardModal, ...)并通过withPublicComponentWrapper包裹supportsGuestEmbed: false即不支持 guest 匿名嵌入模式需要真实用户会话。公共核心层metabase/common/CreateDashboard/CreateDashboardModal.tsx渲染Modal标题 New dashboard、sizelg、data-testidnew-dashboard-modal内部承载CreateDashboardForm表单仪表盘名称、描述、目标集合。值得注意的是核心层的行为当没有传入onCreate时handleCreate会默认执行onClose并跳转到新仪表盘的编辑模式Urls.dashboard(dashboard, { editMode: true })。而 SDK 层始终会传入onCreate因此跳转逻辑由调用方决定。另外SDK 层通过 CreateDashboardModal.schema.ts 定义了一套 Yup 运行时校验 schemaonCreate为必填initialCollectionId、targetCollection、isOpen、onClose均为可选并禁止未知属性.noUnknown()——这为 SDK 的运行时类型安全提供了保障。实战完整的新建仪表盘工作流仓库官方示例 create-dashboard.tsx 展示了一个推荐的完整工作流创建成功后立即用EditableDashboard打开新仪表盘进行编辑。import { useState } from react; import { CreateDashboardModal, EditableDashboard, type MetabaseDashboard, } from metabase/embedding-sdk-react; const ExampleComponent () { const handleClose () {}; const [dashboard, setDashboard] useStateMetabaseDashboard | null(null); if (dashboard) { return EditableDashboard dashboardId{dashboard.id} /; } return CreateDashboardModal onClose{handleClose} onCreate{setDashboard} /; };要点解析用useState保存创建结果onCreate{setDashboard}直接把新仪表盘实体写入 state。一旦dashboard非空切换渲染EditableDashboard dashboardId{dashboard.id} /实现创建即编辑的无缝衔接。不传isOpen时组件默认打开isOpen true。控制打开与关闭当需要由外部按钮控制弹窗开关时使用isOpen与onCloseconst [open, setOpen] useState(false); return ( button onClick{() setOpen(true)}New dashboard/button CreateDashboardModal isOpen{open} onCreate{(d) { console.log(created dashboard:, d.id); setOpen(false); }} onClose{() setOpen(false)} / / );指定保存集合仅设置初始位置initialCollectionIdroot让弹窗打开时默认选中根集合用户仍可在集合选择器中改选其他位置。锁定保存位置targetCollection{123}会隐藏集合选择器新建的仪表盘直接保存到该集合。单元测试验证同时传入initialCollectionId与targetCollection时targetCollection优先见测试用例 should hide the collection picker when passing targetCollection。特殊值root会被解析为根集合创建请求中collection_id为null测试用例 should resolve special collection name like root。返回数据MetabaseDashboard 实体onCreate回调拿到的MetabaseDashboard是仪表盘实体的 SDK 视图见 MetabaseDashboard.mdtype MetabaseDashboard { collection?: MetabaseCollection | null; created_at: string; description: string | null; entity_id: SdkEntityId; id: SdkDashboardId; last-edit-info: { email: string; first_name: string; id: number; last_name: string; timestamp: string; }; name: string; updated_at: string; };其中最常用的是id可用于EditableDashboard、StaticDashboard的dashboardId与name。备选方案useCreateDashboardApi Hook如果不想使用弹窗 UI而希望完全自定义交互SDK 提供了等价的命令式 HookuseCreateDashboardApi见 useCreateDashboardApi.mdfunction useCreateDashboardApi(): { createDashboard: (params: CreateDashboardValues) PromiseMetabaseDashboard; } | null;注意其返回值为null直到 SDK 完全加载初始化完成。CreateDashboardValues包含三个字段见 CreateDashboardValues.md属性类型说明namestring仪表盘标题必填descriptionstring \| null仪表盘描述collectionIdSdkCollectionId创建所在集合同样支持root、personal等系统值官方示例中命令式创建的方式为const hookResult useCreateDashboardApi(); const handleDashboardCreate async () { // hookResult 为 null 时表示 SDK 尚未初始化完成 if (!hookResult) { return; } const dashboard await hookResult.createDashboard({ name: New dashboard, description: null, collectionId: 1, }); // 对创建的空仪表盘做后续处理例如交给 EditableDashboard 渲染 };选择建议交互流程简单、希望零成本复用 UI 时用CreateDashboardModal需要完全自定义触发方式、或在非弹窗场景如工具栏按钮、批量创建时用useCreateDashboardApi。行为验证单元测试视角仓库为CreateDashboardModal编写了完整的单元测试 CreateDashboardModal.unit.spec.tsx覆盖了以下关键行为可作为使用时的行为契约locale 加载中显示空态isLocaleLoading为 true 时渲染为 null不出现 New dashboard 标题。正常渲染加载完成后出现 New dashboard 标题、Description 输入框与 Which collection should this go in? 集合选择提示。创建请求填写名称并点击 Create 后向POST /api/dashboard发起请求请求体包含{ name, collection_id }随后onCreate以服务端返回的仪表盘实体调用一次。isOpen控制isOpen{false}时不渲染弹窗重新渲染为 true 后出现。initialCollectionId默认值不传时集合选择器显示当前用户的个人集合Personal collection。initialCollectionId自定义传入集合 ID 后集合选择器显示对应集合名称。targetCollection行为传入后集合选择器被隐藏collection-picker-button不存在且targetCollection优先于initialCollectionId传入root时请求体collection_id为null。这些测试同时印证了文档中默认个人集合targetCollection 隐藏集合选择器支持 root/personal 系统值等描述均可在真实实现中找到对应逻辑。小结CreateDashboardModal是 Embedded Analytics SDK 中低成本启用创建能力的关键组件一个组件即可获得完整的集合选择、命名与创建流程。使用时牢记三条原则onCreate为必填并接收MetabaseDashboardtargetCollection会隐藏集合选择器并优先于initialCollectionId不传initialCollectionId时默认落在用户个人集合。配合EditableDashboard即可快速构建创建 → 编辑 → 嵌入展示的完整闭环。若需更细粒度的控制useCreateDashboardApi提供了等价的编程式 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/metabase创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考