Metabase Embedded Analytics SDK 全局事件处理SdkDashboardLoadEvent 仪表盘加载事件详解与实战【免费下载链接】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通过MetabaseProvider的eventHandlers配置向宿主应用暴露一组全局事件回调其中SdkDashboardLoadEvent是仪表盘加载完成阶段的核心事件类型。本文以仓库中该类型的官方 API 文档为主体结合 SDK 的 TypeScript 类型声明、加载处理器实现与单元测试完整讲解SdkDashboardLoadEvent的类型签名、MetabaseDashboard实体结构、两种触发时机onDashboardLoad与onDashboardLoadWithoutCards以及如何在宿主应用中监听仪表盘加载事件。事件类型签名与官方文档定位SdkDashboardLoadEvent的官方定义位于 docs/embedding/sdk/api/snippets/SdkDashboardLoadEvent.md其完整类型签名如下type SdkDashboardLoadEvent (dashboard: MetabaseDashboard | null) void;这是一条标准的事件处理器event handler类型别名它接收一个仪表盘对象作为参数不返回任何值。在 SDK 运行环境中该类型被用作SdkEventHandlersConfig中onDashboardLoad与onDashboardLoadWithoutCards两个属性的类型其运行时实现位于 frontend/src/embedding-sdk-bundle/types/events.tsimport type { MetabaseDashboard } from embedding-sdk-bundle/types/dashboard; export type SdkDashboardLoadEvent ( dashboard: MetabaseDashboard | null, ) void; export type SdkEventHandlersConfig { /** * Triggers when a dashboard loads with all visible cards and their content */ onDashboardLoad?: SdkDashboardLoadEvent; /** * Triggers after a dashboard loads, but without its cards (at this stage only the dashboard title, tabs, and cards grid are rendered, but the contents of the cards have yet to load. */ onDashboardLoadWithoutCards?: SdkDashboardLoadEvent; };可以看到源码中的声明与官方 API 文档完全一致二者相互印证。参数dashboardMetabaseDashboard实体结构根据官方文档中的 Parameters 表SdkDashboardLoadEvent仅有一个参数参数类型dashboardMetabaseDashboard|null其中MetabaseDashboard是 SDK 对 Metabase 仪表盘实体的前端类型建模官方文档位于 docs/embedding/sdk/api/snippets/MetabaseDashboard.md源码实现位于 frontend/src/embedding-sdk-bundle/types/dashboard.tstype 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; };各字段含义如下属性类型说明collection?MetabaseCollection|null仪表盘所属集合未归属集合或集合不可见时为nullcreated_atstring仪表盘创建时间descriptionstring|null仪表盘描述可为空entity_idSdkEntityId实体唯一标识用于 SDK 的实体定位idSdkDashboardId仪表盘 ID类型为number \| string \| SdkEntityId支持数字 ID、字符串 ID 与实体 IDlast-edit-info内联对象最近一次编辑者与编辑时间信息last-edit-info.emailstring编辑者邮箱last-edit-info.first_namestring编辑者名last-edit-info.idnumber编辑者用户 IDlast-edit-info.last_namestring编辑者姓last-edit-info.timestampstring编辑时间戳namestring仪表盘名称updated_atstring仪表盘最近更新时间需要注意类型签名中的| null当仪表盘数据加载失败或无法获取实体信息时回调会收到null。因此事件处理器内部应始终先做空值判断再访问dashboard的字段。返回值void官方文档 Returns 一节明确声明该事件处理器返回void。这意味着事件处理函数内不应返回任何值SDK 也不会使用回调的返回值事件处理器仅用于观察副作用用途例如上报埋点、展示通知或同步宿主应用状态而不参与仪表盘的渲染流程。两种触发时机onDashboardLoad 与 onDashboardLoadWithoutCardsSdkEventHandlersConfig官方文档见 docs/embedding/sdk/api/snippets/SdkEventHandlersConfig.md将SdkDashboardLoadEvent应用于两个语义不同的回调属性类型触发时机onDashboardLoad?SdkDashboardLoadEvent仪表盘连同所有可见卡片visible cards及其内容全部加载完成后触发onDashboardLoadWithoutCards?SdkDashboardLoadEvent仪表盘骨架加载完成后触发此时仅渲染了标题、标签页tabs与卡片网格cards grid卡片内容尚未加载完成两个回调的差异在于等待的内容不同onDashboardLoadWithoutCards触发得更早适合做「仪表盘已进入页面」这类轻量级打点或提前初始化 UIonDashboardLoad要等所有可见卡片的查询数据就绪后才触发适合展示完整加载态、计算仪表盘整体渲染耗时等场景。该行为在 frontend/src/embedding-sdk-bundle/components/public/dashboard/tests/SdkDashboard.unit.spec.tsx 中有明确的单元测试验证L92-L135it(should support onLoad, onLoadWithoutCards handlers, async () { const onLoad jest.fn(); const onLoadWithoutCards jest.fn(); const { dashboard } await setup({ props: { onLoad, onLoadWithoutCards }, }); expect(onLoadWithoutCards).toHaveBeenCalledTimes(1); expect(onLoadWithoutCards).toHaveBeenLastCalledWith(dashboard); await waitFor(() { return fetchMock.callHistory.called( path:/api/card/${dashboard.dashcards[0].card_id}/query, ); }); expect(onLoad).toHaveBeenCalledTimes(1); expect(onLoad).toHaveBeenLastCalledWith(dashboard); });测试首先断言onLoadWithoutCards已调用一次并携带 dashboard 实体随后等待卡片的查询接口/api/card/{card_id}/query被请求后才断言onLoad被调用——从源码结构看这正是「先骨架、后内容」两阶段加载语义的实现体现。在宿主应用中注册事件处理器官方配置文档 docs/embedding/sdk/config.md 的「Global event handlers」一节说明了注册方式通过给MetabaseProvider传入eventHandlersprop 来监听 SDK 全局事件。仓库中的完整示例位于 docs/embedding/sdk/snippets/config/config-with-event-handlers.tsximport type { PropsWithChildren } from react; import { MetabaseProvider, type SdkDashboardLoadEvent, defineMetabaseAuthConfig, } from metabase/embedding-sdk-react; const authConfig defineMetabaseAuthConfig({ metabaseInstanceUrl: , }); const Example ({ children }: PropsWithChildren) { const handleDashboardLoad: SdkDashboardLoadEvent (dashboard) { /* do whatever you need to do - e.g. send analytics events, show notifications */ }; const eventHandlers { onDashboardLoad: handleDashboardLoad, onDashboardLoadWithoutCards: handleDashboardLoad, }; return ( MetabaseProvider authConfig{authConfig} eventHandlers{eventHandlers} {children} /MetabaseProvider ); };要点如下eventHandlers是MetabaseProvider的可选 prop其类型为SdkEventHandlersConfig见 docs/embedding/sdk/api/snippets/MetabaseProviderProps.md 中的eventHandlers?一行建议像示例一样为回调标注SdkDashboardLoadEvent类型以获得dashboard参数的类型提示与空值检查约束由于eventHandlers定义在MetabaseProvider层级所有被 Provider 包裹的嵌入式仪表盘组件都会共享这套全局事件回调示例中把同一个处理函数同时赋给两个事件是合法且常见的做法但更精细的用法是分别处理onDashboardLoadWithoutCards中做轻量打点onDashboardLoad中做完整加载后的业务逻辑。源码级原理事件处理器如何被接线从源码结构看全局事件回调与组件级回调onLoad/onLoadWithoutCards会统一汇聚到仪表盘加载处理器中。核心实现位于 frontend/src/embedding-sdk-bundle/hooks/private/use-dashboard-load-handlers.tsexport const useDashboardLoadHandlers ({ onLoad, onLoadWithoutCards, }: PublicOrEmbeddedDashboardEventHandlersProps) { const sdkEventHandlers useSelector(getEventHandlers); // Hack: since were storing functions in the redux store there are issues // with timing and serialization. Well need to do something about this in the future const sdkEventHandlersRef useRef(sdkEventHandlers); useEffect(() { sdkEventHandlersRef.current sdkEventHandlers; }, [sdkEventHandlers]); const handleLoadWithoutCards useCallback( (dashboard: Dashboard) { onLoadWithoutCards?.(dashboard); sdkEventHandlersRef.current?.onDashboardLoadWithoutCards?.(dashboard); }, [onLoadWithoutCards], ); const handleLoad useCallback( (dashboard: Dashboard) { onLoad?.(dashboard); sdkEventHandlersRef.current?.onDashboardLoad?.(dashboard); }, [onLoad], ); return { handleLoad, handleLoadWithoutCards }; };这段代码揭示了几个实现细节双通道回调每次加载事件都会同时触发「组件级 prop 回调」与「全局eventHandlers回调」二者通过可选链调用互不阻塞Redux 存储与 ref 缓存全局eventHandlers存放在 Redux store 中源码注释也坦承了将函数放入 store 存在时序与序列化问题因此通过useRef持有最新引用避免因函数引用变化导致回调反复重建同一事件源handleLoad与handleLoadWithoutCards这两个内部处理器最终由仪表盘加载流程在对应阶段调用从而形成SdkDashboardLoadEvent的两阶段触发语义。此外MetabaseDashboard类型定义文件 frontend/src/embedding-sdk-bundle/types/dashboard.ts 中的DashboardEventHandlersProps还提供了组件级等效回调onLoad/onLoadWithoutCards/onVisualizationChange供单个嵌入式仪表盘组件使用与全局eventHandlers形成互补。测试验证与事件时序保证除上文引用的用例L92-L109外SdkDashboard.unit.spec.tsx 的 L111-L135 专门验证了通过providerProps.eventHandlers注册的全局事件处理器同样按预期工作it(should support global dashboard load event handlers, async () { const onLoad jest.fn(); const onLoadWithoutCards jest.fn(); const { dashboard } await setup({ providerProps: { eventHandlers: { onDashboardLoad: onLoad, onDashboardLoadWithoutCards: onLoadWithoutCards, }, }, }); expect(onLoadWithoutCards).toHaveBeenCalledTimes(1); expect(onLoadWithoutCards).toHaveBeenLastCalledWith(dashboard); await waitFor(() { return fetchMock.callHistory.called( path:/api/card/${dashboard.dashcards[0].card_id}/query, ); }); expect(onLoad).toHaveBeenCalledTimes(1); expect(onLoad).toHaveBeenLastCalledWith(dashboard); });测试传递到回调的dashboard对象与组件渲染所用的实体一致且严格保证了两次调用的时序先onLoadWithoutCards骨架就绪待所有卡片查询请求发出后再onLoad内容就绪。这为宿主应用依赖事件时序做加载状态管理提供了测试层面的保障。实践建议始终处理nulldashboard参数类型允许为null处理器内应先判空再访问字段避免加载失败场景下抛异常按需拆分两个回调轻量埋点放onDashboardLoadWithoutCards依赖完整数据的逻辑如计算渲染时长、触发通知放onDashboardLoad避免把重逻辑塞进早期回调造成 UI 卡顿保持处理器轻量回调返回void、仅在宿主侧产生副作用不要在其中发起会改变仪表盘状态的重型操作以免与 SDK 内部加载流程互相干扰类型复用在宿主应用中显式声明const handler: SdkDashboardLoadEvent ...可获得完整的参数类型提示并在仪表盘实体字段变更时得到编译期检查。总结SdkDashboardLoadEvent是 Metabase Embedded Analytics SDK 中监听仪表盘加载状态的标准事件类型它以MetabaseDashboard | null为参数、返回void通过MetabaseProvider的eventHandlers属性以onDashboardLoad与onDashboardLoadWithoutCards两个时机对外暴露。无论是做加载态管理、性能监控还是用户行为埋点掌握该类型的签名、实体结构与触发时序都是构建高质量嵌入式分析体验的基础。进一步深入可继续阅读 SdkEventHandlersConfig 官方文档、MetabaseProvider 配置说明以及 SDK 源码目录 frontend/src/embedding-sdk-bundle/types 与 frontend/src/embedding-sdk-bundle/hooks/private。【免费下载链接】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），仅供参考