vf_react/src/components/ErrorPage

ErrorPage 通用错误页面组件

通用错误页面组件，用于显示加载失败、网络错误、404 等异常状态。

设计风格：黑色背景 (#1A202C) + 金色边框 (#D4A574)

效果预览

┌─────────────────────────────────────┐
│           ╭──────────╮              │
│           │    ⚠️    │  (金色圆形)  │
│           ╰──────────╯              │
│                                      │
│          事件走丢了                   │
│          ID: ZXY-101                │
│                                      │
│  ┌──────────────────────────────┐   │
│  │ 抱歉，我们找不到您请求的事件... │   │
│  │                              │   │
│  │ 🔍 事件ID输入错误             │   │
│  │    请检查URL中的事件ID是否正确 │   │
│  │                              │   │
│  │ 🗑️ 该事件已被删除或下架       │   │
│  │    该事件可能因过期而被移除    │   │
│  │                              │   │
│  │ 🔄 系统暂时无法访问该事件     │   │
│  │    请稍后重试或联系技术支持    │   │
│  │                              │   │
│  │ [查看技术信息 ▼]              │   │
│  └──────────────────────────────┘   │
│                                      │
│       [返回]    [重试]               │
│                                      │
│        点击右下角联系客服            │
└─────────────────────────────────────┘

快速开始

基础用法

import ErrorPage from '@/components/ErrorPage';

// 最简单的用法 - 使用所有默认配置
<ErrorPage />

// 自定义标题和描述
<ErrorPage
  title="事件走丢了"
  description="抱歉，我们找不到您请求的事件"
/>

完整配置示例

<ErrorPage
  // 基础配置
  title="事件走丢了"
  subtitle="ID: ZXY-101"
  description="抱歉，我们找不到您请求的事件，这可能是因为："

  // 错误原因列表
  reasons={[
    {
      icon: '🔍',
      title: '事件ID输入错误',
      description: '请检查URL中的事件ID是否正确',
    },
    {
      icon: '🗑️',
      title: '该事件已被删除或下架',
      description: '该事件可能因过期或内容调整而被移除',
    },
    {
      icon: '🔄',
      title: '系统暂时无法访问该事件',
      description: '请稍后重试或联系技术支持',
    },
  ]}

  // 技术详情（可展开）
  techDetails={{
    requestUrl: 'http://localhost:3000/event-detail?id=ZXY-101',
    errorType: '404 - Event Not Found',
    errorMessage: 'Unexpected token...',
    timestamp: '2024-01-15 14:30:22',
    relatedId: '101',
  }}

  // 操作按钮
  showBack
  showRetry
  onRetry={() => window.location.reload()}
  showHome
  homePath="/community"

  // 网络状态检查
  checkOffline

  // 错误上报
  onErrorReport={(info) => {
    analytics.track('error_page_view', info);
  }}
/>

API 参考

基础配置

属性	类型	默认值	说明
title	string	'加载失败'	错误标题
subtitle	string	-	错误副标题（如显示错误 ID）
description	string	'我们无法找到您请求的内容，这可能是因为：'	错误描述信息
detail	string	-	详细信息值（与 subtitle 二选一）
detailLabel	string	'ID'	详细信息标签

错误原因配置

属性	类型	默认值	说明
reasons	ErrorReasonItem[]	默认 3 条	错误原因列表

ErrorReasonItem 结构：

interface ErrorReasonItem {
  icon: string | React.ReactNode;  // 图标（emoji 或组件）
  title: string;                    // 原因标题
  description: string;              // 原因描述
}

默认错误原因：

[
  { icon: '🔍', title: 'ID 可能输入错误', description: '请检查 URL 中的 ID 是否正确' },
  { icon: '🗑️', title: '内容可能已被删除', description: '该内容可能因过期或调整而被下架' },
  { icon: '🔄', title: '系统暂时无法访问', description: '请稍后重试或联系技术支持' },
]

技术详情配置

属性	类型	默认值	说明
techDetails	TechDetails	-	技术详情（可展开查看）

TechDetails 结构：

interface TechDetails {
  requestUrl?: string;              // 请求 URL
  errorType?: string;               // 错误类型
  errorMessage?: string;            // 错误信息
  timestamp?: string;               // 时间戳
  relatedId?: string;               // 相关 ID
  customFields?: Record<string, string>;  // 自定义字段
}

操作按钮配置

快捷配置

属性	类型	默认值	说明
showBack	boolean	false	是否显示返回按钮
onBack	() => void	history.back()	返回回调
showRetry	boolean	false	是否显示重试按钮
onRetry	() => void	-	重试回调
showHome	boolean	false	是否显示返回首页按钮
homePath	string	'/'	首页路径

自定义按钮

属性	类型	默认值	说明
actions	ActionButton[]	-	自定义操作按钮列表（覆盖快捷配置）

ActionButton 结构：

interface ActionButton {
  label: string;                               // 按钮文本
  icon?: string;                               // 按钮图标（可选）
  variant?: 'primary' | 'secondary' | 'outline';  // 按钮类型
  onClick?: () => void;                        // 点击回调
  href?: string;                               // 跳转链接（与 onClick 二选一）
}

示例：

<ErrorPage
  actions={[
    { label: '刷新页面', variant: 'primary', onClick: () => location.reload() },
    { label: '返回列表', variant: 'outline', href: '/events' },
  ]}
/>

布局配置

属性	类型	默认值	说明
fullScreen	boolean	true	是否全屏显示
maxWidth	string	'500px'	最大宽度

功能增强

属性	类型	默认值	说明
checkOffline	boolean	true	是否检查网络状态并显示离线提示
enableBuiltInReport	boolean	true	是否启用内置 PostHog 错误上报
onErrorReport	(errorInfo: Record<string, unknown>) => void	-	自定义错误上报回调（与内置上报同时生效）

内置错误上报：

组件默认会自动上报错误到 PostHog，上报事件名为 error_page_view，包含以下数据：

{
  error_title: string;       // 错误标题
  error_detail: string;      // 详细信息（如事件ID）
  error_type: string;        // 错误类型（如 "404 - Event Not Found"）
  error_message: string;     // 错误信息
  page_url: string;          // 当前页面 URL
  referrer: string;          // 来源页面
  user_agent: string;        // 用户代理
  event_id: string;          // 相关 ID
  timestamp: string;         // 时间戳（自动添加）
}

禁用内置上报：

<ErrorPage enableBuiltInReport={false} />

自定义上报回调示例：

<ErrorPage
  onErrorReport={(errorInfo) => {
    // 自定义上报逻辑（与内置 PostHog 上报同时生效）
    customAnalytics.track('custom_error_event', errorInfo);
  }}
/>

场景示例

1. 事件详情 404 页面

<ErrorPage
  title="事件走丢了"
  subtitle={`ID: ${eventId}`}
  description="抱歉，我们找不到您请求的事件，这可能是因为："
  reasons={[
    { icon: '🔍', title: '事件ID输入错误', description: '请检查URL中的事件ID是否正确' },
    { icon: '🗑️', title: '该事件已被删除或下架', description: '该事件可能因过期或内容调整而被移除' },
    { icon: '🔄', title: '系统暂时无法访问该事件', description: '请稍后重试或联系技术支持' },
  ]}
  techDetails={{
    requestUrl: window.location.href,
    errorType: '404 - Event Not Found',
    errorMessage: error.message,
    timestamp: new Date().toISOString(),
    relatedId: eventId,
  }}
  showRetry
  onRetry={() => window.location.reload()}
  showBack
  showHome
  homePath="/community"
/>

2. 网络错误页面

<ErrorPage
  title="网络连接失败"
  description="无法连接到服务器，请检查网络后重试"
  reasons={[
    { icon: '📶', title: '网络连接中断', description: '请检查您的网络连接是否正常' },
    { icon: '🔧', title: '服务器维护中', description: '服务器可能正在进行维护，请稍后重试' },
  ]}
  showRetry
  onRetry={() => window.location.reload()}
/>

3. 简洁模式（无原因列表）

<ErrorPage
  title="加载失败"
  description="数据加载失败，请重试"
  reasons={[]}  // 不显示原因列表
  fullScreen={false}
  maxWidth="400px"
  showRetry
  onRetry={refetch}
/>

类型导出

组件导出以下 TypeScript 类型，方便外部使用：

import ErrorPage, {
  ErrorPageProps,
  ErrorReasonItem,
  ActionButton,
  TechDetails,
} from '@/components/ErrorPage';

设计说明

• 配色：黑色背景 (#1A202C) + 金色边框/按钮 (#D4A574)
• 图标：金色圆形背景 (50px) + 黑色感叹号
• 布局：居中卡片式布局，最大宽度 500px
• 底部提示："点击右下角联系客服"（纯文本，无链接）