PatternsFeedback
PageErrorFallback
@mox-hub/patterns 模式 · Feedback · canonical
page-error-fallback@mox-hub/patternsFeedbackcanonicalsrc/components/page-error-fallback.tsx变体演示page-error-fallback
EERR加载失败
连接后端失败,请稍后重试
Props API
| Prop | 类型 | 默认值 | 说明 |
|---|---|---|---|
| error* | unknown | — | — |
| className* | string | — | — |
| homeHref* | string | "/app" | — |
| renderHomeLink* | (props: { href: string; className: string; }) => ReactElement<unknown, string | JSXElementConstructor<any>> | — | — |
| onBack* | () => void | — | — |
| onRetry* | () => void | — | — |
| labels* | Partial<PageErrorFallbackLabels> | — | — |
源码
import { cloneElement, type ReactElement } from "react"
import { AlertTriangleIcon, RefreshCwIcon, HomeIcon, ArrowLeftIcon } from "lucide-react"
import { Alert, AlertDescription, AlertTitle } from "@mox-hub/ui/components/alert"
import { Button, buttonVariants } from "@mox-hub/ui/components/button"
import { cn } from "@mox-hub/ui"
import { usePatternLabels } from "../lib/i18n"
/* ============================================
PageErrorFallback — 页面级错误降级
放在 ShellLayout 子路由 errorElement 位置
不遮挡侧边栏和顶部导航,只覆盖内容区
库内不依赖 router:错误对象、返回/重试行为与首页地址均由 props 注入。
主仓适配层把 useRouteError() 的结果传给 error,并保留 history.back() 语义。
============================================ */
export interface PageErrorFallbackLabels {
notFoundTitle: string
errorTitle: string
notFoundMessage: string
genericMessage: string
back: string
retry: string
home: string
requestFailed: (status: number) => string
}
const DEFAULT_LABELS: PageErrorFallbackLabels = {
notFoundTitle: "页面未找到",
errorTitle: "加载失败",
notFoundMessage: "页面内容不存在",
genericMessage: "加载内容时遇到问题",
back: "返回",
retry: "重试",
home: "首页",
requestFailed: (status) => `请求失败 (${status})`,
}
export interface PageErrorFallbackProps {
/** 路由/运行时错误对象(Error、字符串或 { status, statusText, data } 形状) */
error?: unknown
className?: string
/** 首页链接(缺省 /app;路由型消费方传自己的首页地址) */
homeHref?: string
/** 首页链接渲染器:主仓传 router Link 保留 SPA 跳转;缺省 <a href={homeHref}> */
renderHomeLink?: (props: { href: string; className: string }) => ReactElement
/** 返回动作(缺省 window.history.back()) */
onBack?: () => void
/** 重试动作(缺省 window.location.reload()) */
onRetry?: () => void
/** 文案覆写;优先级高于 I18nProvider 的 pageErrorFallback section */
labels?: Partial<PageErrorFallbackLabels>
}
function readError(error: unknown): { message?: string; status?: number } {
if (error && typeof error === "object") {
const value = error as {
status?: unknown
statusText?: unknown
data?: { message?: unknown }
message?: unknown
}
if (typeof value.status === "number") {
const statusText =
typeof value.statusText === "string" && value.statusText ? value.statusText : undefined
const dataMessage =
typeof value.data?.message === "string" && value.data.message
? value.data.message
: undefined
return { status: value.status, message: statusText || dataMessage }
}
if (typeof value.message === "string" && value.message) {
return { message: value.message }
}
}
if (typeof error === "string" && error) return { message: error }
return {}
}
export function PageErrorFallback({
error,
className,
homeHref = "/app",
renderHomeLink,
onBack,
onRetry,
labels,
}: PageErrorFallbackProps) {
const D = usePatternLabels("pageErrorFallback", DEFAULT_LABELS)
const L = { ...D, ...labels }
const { message, status } = readError(error)
const isNotFound = status === 404
const title = isNotFound ? L.notFoundTitle : L.errorTitle
const errorMessage = isNotFound
? L.notFoundMessage
: message || (status ? L.requestFailed(status) : L.genericMessage)
return (
<div className={cn("flex-1 flex items-center justify-center p-6", className)}>
<Alert variant="destructive" className="max-w-md w-full text-start" role="alert">
<AlertTriangleIcon className="size-4 text-destructive" />
<AlertTitle className="flex items-center gap-2">
<span className="font-mono text-xs font-semibold text-destructive">
{isNotFound ? "E404" : "EERR"}
</span>
<span>{title}</span>
</AlertTitle>
<AlertDescription className="flex flex-col gap-3 pt-1">
<p className="text-sm text-muted-foreground">{errorMessage}</p>
<div className="flex flex-wrap gap-2">
<Button
size="xs"
variant="outline"
onClick={onBack ?? (() => window.history.back())}
>
<ArrowLeftIcon className="size-3 me-1 rtl:-scale-x-100" />
{L.back}
</Button>
<Button
size="xs"
variant="ghost"
onClick={onRetry ?? (() => window.location.reload())}
>
<RefreshCwIcon className="size-3 me-1" />
{L.retry}
</Button>
{renderHomeLink ? (
cloneElement(
renderHomeLink({
href: homeHref,
className: buttonVariants({ variant: "ghost", size: "xs" }),
}),
{},
<>
<HomeIcon className="size-3 me-1" />
{L.home}
</>,
)
) : (
<a
href={homeHref}
className={buttonVariants({ variant: "ghost", size: "xs" })}
>
<HomeIcon className="size-3 me-1" />
{L.home}
</a>
)}
</div>
</AlertDescription>
</Alert>
</div>
)
}
可访问性与 RTL
- 键盘:交互件保留
:focus-visible焦点环;浮层支持 Escape 关闭与焦点归还,菜单 / 页签按 Base UI 约定支持方向键。 筛选菜单、拖拽排序、执行树与模型 listbox 等关键键盘流由 Playwright 断言覆盖,见规范示例 · 交互与可访问性。 - RTL:间距、对齐与方向性图标使用逻辑属性 (
ms-*/text-start/rtl:-scale-x-100);通过ThemeProvider或I18nProvider的direction="rtl"驱动,`lint:rtl` 会拦截新增物理类。 - 文案:优先用组件
labels/translate/translatorprops,其次用I18nProvider目录;内置 zh-CN 默认值,en-US 为参考翻译。见Theming · i18n 与 RTL。 - 对比度:高对比度 token、2px 控件边框与 3px 焦点环由主题层统一提供,见Foundations · Contrast。
用法说明
页面级错误降级:error 支持 Error/字符串/路由错误形状,渲染 E404/EERR;返回/重试/首页动作可注入,缺省浏览器行为。