Refine v5 shadcn/ui打造可复用的 ErrorComponent 404 错误页【免费下载链接】refineA React Framework for building internal tools, admin panels, dashboards B2B apps with unmatched flexibility.项目地址: https://gitcode.com/GitHub_Trending/re/refine在 Refine v5 的 shadcn/ui 技术栈中ErrorComponent是 refine-ui 组件注册表registry提供的一个 404 错误页组件当用户访问了不存在的链接或导航到了尚未实现的资源页面时它会展示一个带有清晰文案、404 视觉图形和返回首页按钮的错误页帮助用户优雅地从错误中恢复而不是面对浏览器默认的 404 提示。读完本文你将掌握通过 shadcn CLI 安装该组件、将其接入路由作为 catch-all 404 页面的完整流程并能基于源码理解其国际化文案、资源缺失提示Tooltip与useGo导航跳转的实现机制以及它与refinedev/core内置ErrorComponent的差异。组件概览根据文档 shadcn/ui ErrorComponent该组件的定位是为管理后台提供一个打磨过的错误页面包含明确的错误消息、视觉图形和导航选项且会自动适配你的主题设置与仪表盘其余部分保持视觉一致。在仓库中该组件的源码实现位于 error-component.tsx其 shadcn registry 元数据安装清单位于 error-component.json。从 registry 清单可以确认它的关键属性属性值说明nameerror-componentregistry 中的组件名typeregistry:component作为 shadcn 组件被安装dependenciesrefinedev/core、lucide-react安装时自动加入 npm 依赖registryDependenciesbutton、tooltip安装时一并拉取的 shadcn 基础组件files[0].targetsrc/components/refine-ui/layout/error-component.tsx落地到项目中的目标路径categorieserror、layout、404、pages分类标签也就是说它依赖refinedev/core提供的useGo、useResourceParams、useTranslate三个 Hook依赖lucide-react提供ChevronLeft、InfoIcon图标并复用 shadcn 的Button与Tooltip组件。安装文档给出的安装命令是npx shadcnlatest add https://ui.refine.dev/r/error-component.json这条命令会从 refine 的 shadcn registry 拉取 error-component.json 清单自动安装refinedev/core与lucide-react两个包依赖以及button、tooltip两个 registry 基础组件将组件文件写入项目的src/components/refine-ui/layout/error-component.tsx对应清单中的target字段。安装完成后你得到的就是一个带返回首页导航的完整 404 错误页无需再手写任何布局代码。使用将组件作为 404 页面直接使用import { ErrorComponent } from /components/refine-ui/layout/error-component; export default function NotFoundPage() { return ErrorComponent /; }组件会自动提供友好的错误消息和返回应用首页的按钮并适配主题设置保持与仪表盘其他部分的视觉一致性。与路由集成作为 catch-all 404 路由在大多数 React Router 项目中可以把该组件用作通配路由catch-all route// In your routing configuration import { ErrorComponent } from /components/refine-ui/layout/error-component; function App() { return ( Routes {/* Your other routes */} Route path* element{ErrorComponent /} / /Routes ); }这个catch-all 写法并不是孤立的示例。从源码结构看Refine CLI 在检测到项目已有 React Router 配置时就会自动生成完全相同的路由形态react-router.ts 会向App中注入refinedev/core的ErrorComponent并添加Route path* element{ErrorComponent /} /其测试夹具 with-existing-react-router-setup.ts 中展示的正是这一结构。对于 shadcn 技术栈只是把导入源换成了 refine-ui registry 中样式更精致的这个实现。另外需要注意 v5 的导入位置变化v5 的 codemod 测试 rename-themed-v2-imports.test.ts 显示旧版本中ErrorComponent从refinedev/antd、refinedev/mui等 UI 包导出v5 迁移时会被自动改写导入路径。如果你在老项目中看到import { ErrorComponent } from refinedev/antd可以运行 codemod 或手动改为从 core / refine-ui 导入。源码深潜shadcn 版 ErrorComponent 如何工作下面结合 error-component.tsx 的完整实现逐段拆解。三个核心 HookuseTranslate、useGo、useResourceParamsconst [errorMessage, setErrorMessage] useStatestring(); const translate useTranslate(); const go useGo(); const { resource, action } useResourceParams();useResourceParams()从当前路由中解析出resource资源如posts与action动作如create、list。这是 Refine 路由约定/:resource/:action的直接产物useGo()Refine 的跨路由导航 Hook底层委托给路由 providerReact Router、Next.js Router 等的go实现useTranslate()国际化 Hook所有可见文案都通过它渲染未配置 i18n 时使用传入的英文默认值。资源缺失提示Tooltip 的显示逻辑组件通过useEffect监听路由参数决定是否需要显示一条开发者提示源码 L28-L41useEffect(() { if (resource action) { setErrorMessage( translate( pages.error.info, { action: action, resource: resource?.name, }, You may have forgotten to add the ${action} component to ${resource?.name} resource., ), ); } }, [resource, action, translate]);这里体现了一个很有价值的错误页设计思路访问的是任意不存在的路径如/foo/barresource与action都为空只显示通用 404 文案访问的是符合 Refine 约定但组件缺失的页面如路由解析出了resource: posts、action: create却没有注册对应的 Create 页面错误页会在描述文案旁显示一个InfoIcon图标悬停 Tooltip 提示You may have forgotten to add the create component to posts resource.直接告诉开发者缺的是哪个资源的哪个页面大幅缩短排障时间。对应源码 L98-L117 的渲染结构为TooltipProvider Tooltip TooltipTrigger(asChild, InfoIcon) TooltipContent且只有errorMessage存在时才渲染图标上还带有data-testiderror-component-tooltip便于 E2E 测试定位。视觉与布局组件使用 Tailwind 类名通过cn工具函数合并见源码 L43-L52构建外层容器flex items-center justify-center bg-background my-auto让 404 页面在整个视口中垂直水平居中并使用主题 tokenbg-background保证深浅色主题下都正确中间的404字样是一个内联 SVGL55-L81使用#D4D4D8 - #E4E4E7的线性渐变填充宽度固定w-48、高度自适应标题text-2xl font-semibold text-foreground描述文案text-muted-foreground同样全部使用语义化颜色 token天然跟随主题切换。返回首页按钮按钮实现源码 L121-L129Button onClick{() { go({ to: / }); }} className{cn(flex, items-center, gap-2, mx-auto)} ChevronLeft className{cn(h-4, w-4)} / {translate(pages.error.backHome, Back to hompeage)} /Button点击后调用go({ to: / })导航回应用根路径。由于useGo抽象了具体路由实现同一段代码在 React Router、Next.js、Remix 等任何 Refine 支持的路由器下都能工作。国际化文案键shadcn 版组件使用以下翻译键第二个参数为无 i18n 配置时的英文回退值翻译键默认文案出现位置pages.error.titlePage not found.页面标题h1pages.error.descriptionThe page youre looking for does not exist.描述段落pages.error.infoYou may have forgotten to add the {action} component to {resource} resource.资源缺失时的 Tooltippages.error.backHomeBack to hompeage返回按钮如果你的应用配置了i18nProvider只需在语言包中提供这些键的翻译整个错误页即可完全本地化。与 refinedev/core 内置 ErrorComponent 的关系Refine core 一直内置一个无样式的ErrorComponentpackages/core/src/components/pages/error/index.tsx逻辑与 shadcn 版几乎一致同样使用useTranslate/useGo/useResourceParams同样在存在resource与action时生成资源缺失提示文案按钮同样执行go({ to: / })。两者的差异主要在呈现层core 版仅输出原生h1、p、button翻译键为pages.error.404/pages.error.info/pages.error.backHome适合 headless 场景或自定义 UI 的基础shadcn 版使用 shadcnButton/Tooltip、内联 404 SVG 与 Tailwind 主题 token标题与描述拆分为pages.error.title/pages.error.description两个键视觉更精致且自带交互提示。core 版的行为有完整测试佐证index.spec.tsx当 mock 路由 provider 给出action: create、resource: { name: posts }时页面会渲染You may have forgotten to add the create component to posts resource.点击 Back Home 后go恰被调用一次且参数为{ to: / }。这验证了两版组件共享同一套错误语义。小结与最佳实践安装npx shadcnlatest add https://ui.refine.dev/r/error-component.json组件落地到src/components/refine-ui/layout/error-component.tsx自动补齐refinedev/core、lucide-react与 button/tooltip 依赖路由接入在Routes末尾声明Route path* element{ErrorComponent /} /即可覆盖所有未匹配路径利用资源提示当 URL 符合/:resource/:action约定但页面缺失时错误页 Tooltip 会直接指出缺失的资源与动作这是排查路由配了但忘写页面类问题最快的入口跟随主题与 i18n组件只使用语义化颜色 token 与翻译键接入你的 shadcn 主题和 i18nProvider 后无需任何额外适配区分使用场景headless 项目可用refinedev/core内置版自行定制shadcn 技术栈则优先使用 refine-ui registry 的这版实现保持与 refine-ui 其他视图list/create/edit 等一致的视觉语言。相关参考路径组件源码 packages/refine-ui/registry/new-york/refine-ui/layout/error-component.tsx、registry 清单 packages/refine-ui/public/r/error-component.json、core 内置实现 packages/core/src/components/pages/error/index.tsx 及其测试 packages/core/src/components/pages/error/index.spec.tsx。【免费下载链接】refineA React Framework for building internal tools, admin panels, dashboards B2B apps with unmatched flexibility.项目地址: https://gitcode.com/GitHub_Trending/re/refine创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考