Metabase Embedding SDK 编程式创建仪表盘：CreateDashboardValues 类型全解析

Metabase Embedding SDK 编程式创建仪表盘CreateDashboardValues 类型全解析【免费下载链接】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/metabaseCreateDashboardValues是 Metabase Embedding SDK 中描述创建新仪表盘所需参数的核心类型它同时服务于useCreateDashboardApiHook 与底层POST /api/dashboard接口。本文将以该类型为骨架逐一拆解name、description、collectionId三个字段的含义、取值规则与底层解析逻辑并给出可直接落地的 TypeScript 实战示例帮助你在嵌入应用中用几行代码动态生成仪表盘。CreateDashboardValues编程式建盘的参数契约在 Embedding SDK 中当你需要在宿主应用中以代码方式新建一个仪表盘例如根据用户操作动态生成报表容器时传入的参数对象就是CreateDashboardValues。它的完整定义如下export type CreateDashboardValues Omit CreateDashboardProperties, collection_id { /** * Collection in which to create a new dashboard. * You can use predefined system values like root or personal. */ collectionId: SdkCollectionId; };该定义位于 frontend/src/embedding-sdk-bundle/types/dashboard.ts其核心手法是从核心应用的表单属性CreateDashboardProperties中剔除内部字段collection_id再替换为面向 SDK 使用者的collectionId类型为SdkCollectionId。这意味着你在 SDK 侧永远不需要关心后端真实的数值型集合 ID只需给出语义化的引用即可。CreateDashboardProperties本身定义于 frontend/src/metabase/common/CreateDashboard/CreateDashboardForm.tsx是 Metabase 核心产品新建仪表盘表单同款的数据结构保证了嵌入式场景与原生界面的行为一致。属性一览CreateDashboardValues共包含三个属性其中name与collectionId必填description可空属性类型说明collectionIdSdkCollectionId新仪表盘将被创建到哪个集合Collection中。可使用预定义的系统值如root或personal。descriptionstring \| null仪表盘描述。namestring仪表盘标题。name仪表盘标题name是必填字段对应创建后仪表盘显示的名称。在表单校验层CreateDashboardForm.tsx 中的 Yup schema它被定义为name: Yup.string() .required(Errors.required) .max(DASHBOARD_NAME_MAX_LENGTH, Errors.maxLength) .default(),即必填、不允许为空字符串且最大长度受DASHBOARD_NAME_MAX_LENGTH约束。该常量定义于 frontend/src/metabase/common/utils/dashboard.tsexport const DASHBOARD_NAME_MAX_LENGTH 254; export const DASHBOARD_DESCRIPTION_MAX_LENGTH 1500;因此标题最长 254 个字符描述最长 1500 个字符。超出长度时SDK 侧的表单组件与后端校验都会拒绝创建。description仪表盘描述description类型为string | null即允许显式传入null表示无描述。在 Yup schema 中description: Yup.string() .nullable() .max(DASHBOARD_DESCRIPTION_MAX_LENGTH, Errors.maxLength) .default(null),如果不传SDK 会以null作为默认值提交。后端接口同样将description定义为可选{:optional true} [:maybe :string]并在存储时原样保留。collectionId决定仪表盘的归属集合collectionId是三个属性中最具 SDK 特色、也最值得展开讲解的一个。它不要求你提供后端数据库里的原始数值 ID而是接受一组集合引用包括预定义系统值personal当前用户个人集合、root根集合、tenant租户集合普通数值 ID某个具体集合的数据库 ID字符串实体 ID集合的entity_idSdkEntityId类型。其类型定义同时出现在 SdkCollectionId.md 与 frontend/src/embedding-sdk-bundle/types/collection.tsexport type SdkCollectionId | number | personal | root | tenant | SdkEntityId;其中SdkEntityId是一个品牌化字符串类型type SdkEntityId string {}用于在类型层面与普通字符串区分详见 SdkEntityId.md。需要说明的是该类型刻意不包含核心应用CollectionId中的users、trash等值——SDK 的公开 API 不支持这些内部集合源码注释对此有明确说明。集合引用的底层解析规则当你把collectionId传给 SDK 后真正发生转换的地方是 frontend/src/embedding-sdk-bundle/store/collections.ts 中的getCollectionIdValueFromReference一个基于 Redux 状态的createSelector。它依据传入的引用类型进行分支匹配传入值解析结果说明personal当前用户的个人集合 ID从getUserPersonalCollectionId派生tenant当前用户的租户集合 IDtenant_collection_id若用户不属于任何租户会抛出You must be a tenant member to access the tenant collection.错误rootnull关键细节根集合在后端 API 中就是用null表示的数值 / 字符串原样透传数值作为真实集合 ID字符串按实体 ID 处理其他抛错抛出Invalid collection id, expected number \| string \| root \| personal \| tenant这段逻辑collections.ts同时揭示了两个易踩的坑root会被转换为null提交。这是因为后端POST /api/dashboard端点用collection_id null表示根集合而非字面量字符串roottenant依赖当前用户的租户成员身份非租户成员直接抛出异常调用前应做好容错如try/catch或先判断当前用户。实战通过 useCreateDashboardApi 创建仪表盘CreateDashboardValues最典型的使用场景是配合useCreateDashboardApiHook。其签名定义于 useCreateDashboardApi.mdfunction useCreateDashboardApi(): { createDashboard: ( params: CreateDashboardValues, ) PromiseMetabaseDashboard; } | null;注意返回值为null或对象在 SDK 完全加载并初始化完成之前该 Hook 返回null因此调用前必须先判空。一个完整的实战示例import { useCreateDashboardApi } from metabase/embedding-sdk-react; function CreateDashboardButton() { const { createDashboard } useCreateDashboardApi() ?? {}; const handleCreate async () { if (!createDashboard) { // SDK 尚未就绪此时 createDashboard 不可用 return; } try { const dashboard await createDashboard({ name: Q3 销售周报, // 必填仪表盘标题≤ 254 字符 description: 由嵌入应用动态生成, // 可选可传 null collectionId: personal, // 可选但强烈建议显式指定 // 不传时 SDK 默认使用 personal }); console.log(创建成功仪表盘 ID:, dashboard.id); console.log(实体 ID:, dashboard.entity_id); } catch (error) { // 处理权限不足、名称超长、租户集合不可达等异常 } }; return button onClick{handleCreate}新建仪表盘/button; }一个值得注意的默认值细节SDK 的createDashboard实现frontend/src/embedding-sdk-bundle/lib/create-dashboard.ts在解构参数时为collectionId提供了默认值personalexport const createDashboard (reduxStore: SdkStore) async ({ collectionId personal, ...rest }: CreateDashboardValues) { const realCollectionId getCollectionIdValueFromReference( reduxStore.getState(), collectionId, ); const action createDashboardMutation.initiate({ ...rest, collection_id: realCollectionId, }); return reduxStore.dispatch(action).unwrap(); };即即使你在类型层面按必填声明了collectionId运行时也可以省略它仪表盘会被创建到当前用户的个人集合中。解析后的真实集合 ID 被映射为collection_id字段连同其余参数一起交给 RTK Query 的createDashboardmutation定义于 frontend/src/metabase/api/dashboard.ts最终发出POST /api/dashboard请求。创建成功后的返回值MetabaseDashboardcreateDashboard返回PromiseMetabaseDashboard即创建成功的完整仪表盘实体其结构见 MetabaseDashboard.md对应源码定义在 dashboard.tsexport type MetabaseDashboard { id: SdkDashboardId; entity_id: SdkEntityId; created_at: string; updated_at: string; collection?: MetabaseCollection | null; name: string; description: string | null; last-edit-info: { id: number; email: string; first_name: string; last_name: string; timestamp: string; }; };其中id是SdkDashboardId数值 ID、字符串 ID 或实体 ID 的联合类型。拿到返回值后你可以直接将其id传入InteractiveDashboard/StaticDashboard等组件立即渲染刚创建的仪表盘形成创建即展示的闭环。另一种方式CreateDashboardModal 组件如果你的产品更希望复用 Metabase 自带的新建界面而不是自绘表单可以使用CreateDashboardModal组件其声明见 CreateDashboardModal.md入参类型为 CreateDashboardModalProps.md属性类型说明initialCollectionId?SdkCollectionId初始选中的集合可使用root、personal等系统值isOpen?boolean弹窗是否打开onClose?() void关闭弹窗的处理函数onCreate(dashboard: MetabaseDashboard) void创建成功后的回调参数即新建的仪表盘targetCollection?SdkCollectionId固定保存到指定集合设置后保存弹窗中的集合选择器会被隐藏该组件的属性同样建立在SdkCollectionId之上因此initialCollectionId与targetCollection支持与CreateDashboardValues.collectionId完全相同的取值集合。两种方式对比useCreateDashboardApi适合完全自定义 UI 与流程例如静默创建、批量创建CreateDashboardModal适合快速交付直接复用官方弹窗交互。底层调用链从前端 SDK 到后端接口为便于排查问题这里梳理创建仪表盘的完整链路均可从仓库源码验证SDK 入口create-dashboard.ts 接收CreateDashboardValues用getCollectionIdValueFromReference解析collectionIdRTK Query 层dashboard.ts 的createDashboardmutation 组装POST /api/dashboard请求体请求体类型CreateDashboardRequest含name、description?、parameters?、cache_ttl?、collection_id?等字段后端端点src/metabase/dashboards_rest/api.clj 中POST /端点接收并校验请求schema 要求name为NonBlankString非空白字符串description、cache_ttl、collection_id、collection_position均可选权限与落库后端先执行api/create-check :model/Dashboard确认当前用户对目标集合具备建盘权限随后在事务中调用insert-dashboard!写入并发布:event/dashboard-create事件、上报 Snowplow 分析事件见 api.clj响应后端返回补齐了last-edit-info、根集合信息等详情的仪表盘对象即MetabaseDashboard。这条链路意味着CreateDashboardValues中的name/description直接映射为后端同名字段而collectionId经过引用 → 真实 ID →collection_id的两步转换最终决定新仪表盘挂在哪个集合下——这也是创建请求在权限校验时依据的目标集合。常见错误与排查要点useCreateDashboardApi()返回nullSDK 尚未初始化完成需等待MetabaseProvider加载后再调用代码中务必判空You must be a tenant member to access the tenant collection.使用了tenant引用但当前用户无租户集合改用personal、root或具体集合 IDInvalid collection id...传入了类型允许之外的值例如all——该值仅存在于SdkBrowserCollectionId属于集合浏览器的虚拟顶层不能用于创建仪表盘名称/描述超长name超过 254、description超过 1500 字符会被表单校验或后端拒绝建议在 UI 侧先做长度提示权限不足目标集合无创建权限时后端create-check会拒绝请求可先确认当前嵌入用户的集合权限配置。综上CreateDashboardValues虽只有三个字段却是打通嵌入应用 → SDK → Metabase 后端创建链路的关键契约。理解SdkCollectionId的引用语义与默认值行为即可在嵌入场景中稳定、可预期地动态创建仪表盘。【免费下载链接】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），仅供参考