Ordo UI
PatternsFeedback

PageErrorFallback

@mox-hub/patterns 模式 · Feedback · canonical

page-error-fallback@mox-hub/patternsFeedbackcanonicalsrc/components/page-error-fallback.tsx
变体演示page-error-fallback

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>——

源码

packages/patterns/src/components/page-error-fallback.tsx
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 /translator props,其次用I18nProvider目录;内置 zh-CN 默认值,en-US 为参考翻译。见Theming · i18n 与 RTL。
  • 对比度:高对比度 token、2px 控件边框与 3px 焦点环由主题层统一提供,见Foundations · Contrast。

用法说明

页面级错误降级:error 支持 Error/字符串/路由错误形状,渲染 E404/EERR;返回/重试/首页动作可注入,缺省浏览器行为。