Metabase Embedding SDK 错误组件 Props 完全解析：从 SdkErrorComponentProps 到自定义错误 UI

Metabase Embedding SDK 错误组件 Props 完全解析从 SdkErrorComponentProps 到自定义错误 UI【免费下载链接】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 Modular Embedding SDK 中SdkErrorComponentProps这一错误组件属性契约它定义了 SDK 在遇到错误时向宿主应用的自定义错误组件传入的全部数据包括错误对象、提示消息、展示模式、关闭回调等。读完本文你将掌握该类型的每个字段的语义与默认值、SDK 内置错误组件的实现原理relative/fixed两种渲染模式、如何在MetabaseProvider上通过errorComponent接入自己的 React 错误组件以及如何利用error携带的错误码渲染官方文档链接。一、错误组件在 SDK 中的定位在 Metabase 的模块化嵌入 SDKModular Embedding SDK中嵌入的组件如StaticDashboard、InteractiveQuestion在加载、失败或查询无结果时会渲染一套 SDK 自带的界面。Metabase 允许宿主应用通过MetabaseProvider的两个 props 替换其中两个状态loaderComponent替换默认的加载界面errorComponent替换默认的错误界面。官方文档 Customize loading, error, and empty states 明确指出这些自定义能力是 SDK 专有的loaderComponent与errorComponent是MetabaseProvider上的 props且没有对应的 web component 版本。MetabaseProvider的类型定义docs/embedding/sdk/api/snippets/MetabaseProviderProps.md中这样描述errorComponentA custom error component to display when the SDK encounters an error.即“当 SDK 遇到错误时用于展示的自定义错误组件”。所有位于该 Provider 内部的嵌入组件都会继承这个自定义错误组件。而SdkErrorComponentProps正是 Metabase 传给这个自定义错误组件的 props 的类型契约——它决定了你的自定义组件能拿到哪些数据、如何区分不同展示形态。二、类型定义一个只有 5 个字段的精简契约SdkErrorComponentProps的完整类型定义来自 docs/embedding/sdk/api/snippets/SdkErrorComponentProps.mdtype SdkErrorComponentProps { error?: Error; message: ReactNode; onClose?: () void; type?: relative | fixed; withCloseButton?: boolean; };该类型在仓库中的实际定义位于 frontend/src/metabase/embedding-sdk/types/error-component.ts与文档一致并随之导出了错误组件的签名export type SdkErrorComponent ({ type, message, error, }: SdkErrorComponentProps) JSX.Element;也就是说一个合法的自定义错误组件就是一个接收SdkErrorComponentProps、返回JSX.Element的 React 函数组件。注意SdkErrorComponent的签名只显式解构了type、message、error三个字段onClose与withCloseButton是可选的辅助能力。三、属性表完整字段速览PropertyType说明error?Error可选的错误对象携带错误码code等附加信息可据此渲染官方文档链接messageReactNode必填。要展示的错误提示消息可以是任意 React 节点onClose?() void可选的关闭回调用于实现“关闭/收起”错误提示type?relative|fixed展示模式relative在组件流内展示fixed以浮层类 toast方式覆盖页面withCloseButton?boolean是否显示关闭按钮为true时 SDK 才会把onClose传入你的组件error的类型指向标准Error对象见 MDN Error 文档message的类型ReactNode是 React 的标准节点类型可以渲染字符串、元素或 Fragment这给了自定义组件极大的自由度。四、字段逐一精讲语义、默认值与源码证据4.1message必填错误提示消息message是唯一必填字段类型为ReactNode。SDK 内部在组装错误展示时会优先尝试使用error.message并附带文档链接没有文档链接时才回退到传入的message。内置实现位于 SdkError.tsxconst errorMessage useMemo(() { if (error code in error typeof error.code string) { const docsLink ERROR_DOC_LINKS[error.code as MetabaseErrorCode]; if (docsLink) { return ( span {error.message || message}{ } Anchor href{docsLink} target_blank relnoopener noreferrer {tRead more.} /Anchor /span ); } } return message; }, [message, error]);从这段源码可以看到message的三种处理路径error携带字符串形式的code且该错误码在ERROR_DOC_LINKS中登记了文档链接 → 展示error.message并附“Read more.”链接error存在但无登记的错误码 → 展示传入的message无error→ 展示传入的message。4.2type可选默认relative决定错误以何种布局呈现type告知宿主应用 Metabase 原本打算如何展示这个错误relative错误信息嵌在组件的内容流中随组件布局流动fixed错误信息应覆盖在页面上方类似 toast 提示。官方文档 loading-and-errors.md 对该字段的注释与源码实现完全吻合。内置SdkError组件对两种模式的处理逻辑如下return ( {type relative errorMessageElement} {type fixed ( SdkPortalErrorWrapper{errorMessageElement}/SdkPortalErrorWrapper )} / );其中SdkPortalErrorWrapper把错误内容通过 React Portal 渲染到固定在视口底部的容器中posfixedbottom: 1remzIndex: 500Portal 的目标元素 id 为metabase-sdk-portal-root定义在 frontend/src/metabase/embedding-sdk/config.tsexport const EMBEDDING_SDK_PORTAL_ROOT_ELEMENT_ID metabase-sdk-portal-root;type的默认值在组件签名中为relativeexport const SdkError ({ message, error, type relative, withCloseButton false, }: OmitSdkErrorComponentProps, onClose) { ... }4.3withCloseButton可选默认false与onClose可选可关闭的错误提示withCloseButton控制是否渲染关闭按钮只有当它为true时SDK 才会把内部的关闭函数包装成onClose传给自定义错误组件ErrorMessageComponent type{type} message{errorMessage} {...(withCloseButton { onClose: handleBannerClose, })} /内部实现使用mantine/hooks的useDisclosure管理可见性点击关闭后组件返回null即错误提示被收起。关闭按钮的渲染逻辑体现在内置的DefaultErrorMessage中Alert colorerror icon{Icon namewarning /} withCloseButton{Boolean(onClose)} onClose{onClose} ... 需要注意withCloseButton为true只是把onClose传给你的组件最终是否显示关闭按钮、如何布局完全由你的自定义组件决定——这也是该字段被设计为“SDK 端开关、宿主端渲染”的原因。4.4error可选携带错误码与文档链接的错误对象error是标准Error实例但 Metabase 会向其上附加一个字符串形式的code字段如EXISTING_USER_SESSION_FAILED。错误码与官方文档链接的映射表定义在 frontend/src/embedding-sdk-shared/errors/error-docs-links.tsexport const ERROR_DOC_LINKS: ErrorDocLinks { EXISTING_USER_SESSION_FAILED: https://www.metabase.com/docs/latest/embedding/authentication#configure-session-cookies-when-testing-locally, };文件注释解释了为何要单独维护这张表“自定义字段在错误序列化时会被移除所以需要单独存储文档 URL”。这一点对你的自定义组件很有参考价值如果后端返回的错误对象经过序列化/反序列化附加字段可能丢失判断时要做防御性处理源码中即用code in error做存在性检查。五、实战接入自定义错误组件把自定义错误组件挂到MetabaseProvider上Provider 内部的每个嵌入组件都会自动使用它。完整示例来自 docs/embedding/sdk/snippets/appearance/customizing-loader-and-components.tsximport { MetabaseProvider, StaticDashboard, } from metabase/embedding-sdk-react; const authConfig {} as MetabaseAuthConfig; const Example () { return ( MetabaseProvider authConfig{authConfig} loaderComponent{() divAnalytics is loading.../div} errorComponent{({ type, message, onClose }) { switch (type) { case fixed: return ( div style{{ position: fixed, left: 0, right: 0, bottom: 0 }} There was an error: {message}. span onClick{onClose}X/span /div ); case relative: default: return divThere was an error: {message}/div; } }} StaticDashboard dashboardId{1} / /MetabaseProvider ); };这个示例演示了自定义错误组件最核心的用法依据type分支渲染不同的布局fixed固定在页面底部、relative内联展示同时消费onClose实现关闭交互。因为message是ReactNode你还可以在消息里嵌入图标、按钮、链接甚至整个品牌化错误页。六、内置默认实现与测试场景6.1 默认错误组件长什么样不传errorComponent时SDK 使用 SdkError.tsx 中的内置实现一个带 warning 图标的Alert最大宽度 600px长消息两行截断-webkit-line-clamp: 2data-testidsdk-error-container。此外该文件还导出了几个开箱即用的错误组件QuestionNotFoundError/DashboardNotFoundError/CollectionNotFoundError资源不存在提示会以Code形式高亮展示传入的资源 IDSdkError通用错误组件本体。6.2 官方 Storybook 场景即测试用例仓库为错误组件提供了完整的 Storybook 用例SdkError.stories.tsx可以当作可运行的测试清单Story验证点Defaultmessagetype: relative的基础渲染WithCloseButtonwithCloseButton: true时关闭按钮出现、onClose生效WithDocLink构造Object.assign(new Error(Existing user session failed.), { code: EXISTING_USER_SESSION_FAILED })验证错误码 → 文档链接的映射渲染Fixedtype: fixed时错误进入 Portal 浮层LongMessage超长 JWT 校验错误消息的截断与换行表现QuestionNotFound/DashboardNotFound内置“资源未找到”组件其中WithDocLink用到的EXISTING_USER_SESSION_FAILED错误码与 4.4 节中的ERROR_DOC_LINKS映射表一一对应展示了“错误码 → 官方文档链接”这条链路在真实场景下的形态该错误通常对应本地测试时未正确配置会话 Cookie 的鉴权问题。七、SDK 内部的传递链路从源码结构可以梳理出errorComponent从配置到渲染的完整链路宿主应用把errorComponent传给MetabaseProvider类型见 docs/embedding/sdk/api/snippets/MetabaseProviderProps.mdComponentProvider通过setErrorComponentaction 把它写入 SDK 的 Redux store见 frontend/src/embedding-sdk-bundle/components/public/ComponentProvider/ComponentProvider.tsxstore 中errorComponent字段初始值为null通过setErrorComponent更新见 frontend/src/embedding-sdk-bundle/store/reducer.tsSdkError组件通过 selectorgetErrorComponent取回自定义组件若为null则回退到内置DefaultErrorMessageconst CustomError useSdkSelector(getErrorComponent); ... const ErrorMessageComponent CustomError || DefaultErrorMessage;这条链路意味着自定义错误组件是全局配置在 Provider 上的Provider 内的所有嵌入组件共享同一套错误 UI而SdkErrorComponentProps中的type、message、error等字段则是 SDK 在渲染时按具体错误场景动态注入的。八、使用建议与注意事项type是布局信号不是安全边界fixed模式由 SDK 通过 Portal 渲染但自定义组件内如果选择自己实现浮层需自行处理层级参考内置实现的zIndex: 500与滚动穿透问题防御式读取error.code错误对象经过序列化后自定义字段可能丢失判断时应使用code in error之类的存在性检查而不是直接读取message的 ReactNode 特性值得善用可以把错误码、操作按钮、重试入口直接嵌入消息节点比纯字符串提示更有操作性withCloseButton与onClose配合使用只有withCloseButton: true时 SDK 才传入onClose自定义组件据此决定是否渲染关闭按钮该能力仅限 React SDKloaderComponent、errorComponent没有 web component 等价物无结果插图则通过pluginsConfig中的getNoDataIllustration/getNoObjectIllustration插件配置详见 loading-and-errors.md 与 plugins.md。九、延伸阅读本类型定义的源码出处frontend/src/metabase/embedding-sdk/types/error-component.ts默认错误组件实现frontend/src/embedding-sdk-bundle/components/private/PublicComponentWrapper/SdkError.tsx错误组件 Storybook 测试场景frontend/src/embedding-sdk-bundle/components/private/PublicComponentWrapper/SdkError.stories.tsx自定义加载/错误/空状态总览docs/embedding/sdk/loading-and-errors.md可复制示例代码docs/embedding/sdk/snippets/appearance/customizing-loader-and-components.tsxSDK 全局配置docs/embedding/sdk/config.md【免费下载链接】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），仅供参考