name: react-ui-patterns description: 现代 React UI 模式，用于加载状态、错误处理和数据获取。在构建 UI 组件、处理异步数据或管理 UI 状态时使用。

React UI 模式

核心原则

永不显示过时的 UI - 仅在实际加载时显示加载指示器
始终显示错误 - 用户必须知道何时失败
乐观更新 - 使 UI 感觉即时
逐步披露 - 随着内容变得可用而显示内容
优雅降级 - 部分数据总比没有数据好

加载状态模式

黄金法则

仅在没有数据可显示时显示加载指示器。

// 正确 - 仅在没有数据时显示加载
const { data, loading, error } = useGetItemsQuery();

if (error) return <ErrorState error={error} onRetry={refetch} />;
if (loading && !data) return <LoadingState />;
if (!data?.items.length) return <EmptyState />;

return <ItemList items={data.items} />;

// 错误 - 即使我们有缓存数据也显示 spinner
if (loading) return <LoadingState />; // 重新获取时会闪烁！

加载状态决策树

有错误吗？
  → 是的：显示错误状态并提供重试选项
  → 否：继续

正在加载并且我们没有数据吗？
  → 是的：显示加载指示器（spinner/skeleton）
  → 否：继续

我们有数据吗？
  → 是的，有项目：显示数据
  → 是的，但是空的：显示空状态
  → 否：显示加载（回退）

Skeleton vs Spinner

使用 Skeleton 的情况	使用 Spinner 的情况
已知内容形状	未知内容形状
列表/卡片布局	模态操作
初始页面加载	按钮提交
内容占位符	内联操作

错误处理模式

错误处理层次结构

1. 内联错误（字段级别）→ 表单验证错误
2. Toast 通知 → 可恢复的错误，用户可以重试
3. 错误横幅 → 页面级错误，数据仍然部分可用
4. 全错误屏幕 → 不可恢复的，需要用户操作

始终显示错误

关键：永远不要默默地吞下错误。

// 正确 - 错误总是向用户显示
const [createItem, { loading }] = useCreateItemMutation({
  onCompleted: () => {
    toast.success({ title: '项目已创建' });
  },
  onError: (error) => {
    console.error('createItem failed:', error);
    toast.error({ title: '未能创建项目' });
  },
});

// 错误 - 错误被默默地捕获，用户一无所知
const [createItem] = useCreateItemMutation({
  onError: (error) => {
    console.error(error); // 用户什么也看不到！
  },
});

错误状态组件模式

interface ErrorStateProps {
  error: Error;
  onRetry?: () => void;
  title?: string;
}

const ErrorState = ({ error, onRetry, title }: ErrorStateProps) => (
  <div className="error-state">
    <Icon name="exclamation-circle" />
    <h3>{title ?? '出了点问题'}</h3>
    <p>{error.message}</p>
    {onRetry && (
      <Button onClick={onRetry}>再试一次</Button>
    )}
  </div>
);

按钮状态模式

按钮加载状态

<Button
  onClick={handleSubmit}
  isLoading={isSubmitting}
  disabled={!isValid || isSubmitting}
>
  提交
</Button>

在操作期间禁用

关键：在异步操作期间始终禁用触发器。

// 正确 - 按钮在加载时禁用
<Button
  disabled={isSubmitting}
  isLoading={isSubmitting}
  onClick={handleSubmit}
>
  提交
</Button>

// 错误 - 用户可以多次点击
<Button onClick={handleSubmit}>
  {isSubmitting ? '提交中...' : '提交'}
</Button>

空状态

空状态要求

每个列表/集合都必须有一个空状态：

// 错误 - 没有空状态
return <FlatList data={items} />;

// 正确 - 明确的空状态
return (
  <FlatList
    data={items}
    ListEmptyComponent={<EmptyState />}
  />
);

上下文空状态

// 搜索无结果
<EmptyState
  icon="search"
  title="未找到结果"
  description="尝试不同的搜索词"
/>

// 列表中尚无项目
<EmptyState
  icon="plus-circle"
  title="尚无项目"
  description="创建您的第一个项目"
  action={{ label: '创建项目', onClick: handleCreate }}
/>

表单提交模式

const MyForm = () => {
  const [submit, { loading }] = useSubmitMutation({
    onCompleted: handleSuccess,
    onError: handleError,
  });

  const handleSubmit = async () => {
    if (!isValid) {
      toast.error({ title: '请修复错误' });
      return;
    }
    await submit({ variables: { input: values } });
  };

  return (
    <form>
      <Input
        value={values.name}
        onChange={handleChange('name')}
        error={touched.name ? errors.name : undefined}
      />
      <Button
        type="submit"
        onClick={handleSubmit}
        disabled={!isValid || loading}
        isLoading={loading}
      >
        提交
      </Button>
    </form>
  );
};

反模式

加载状态

// 错误 - 数据存在时显示 spinner（导致闪烁）
if (loading) return <Spinner />;

// 正确 - 仅在没有数据时显示加载
if (loading && !data) return <Spinner />;

错误处理

// 错误 - 错误被吞下
try {
  await mutation();
} catch (e) {
  console.log(e); // 用户一无所知！
}

// 正确 - 错误被显示
onError: (error) => {
  console.error('operation failed:', error);
  toast.error({ title: '操作失败' });
}

按钮状态

// 错误 - 提交期间按钮未禁用
<Button onClick={submit}>提交</Button>

// 正确 - 禁用并显示加载
<Button onClick={submit} disabled={loading} isLoading={loading}>
  提交
</Button>

清单

在完成任何 UI 组件之前：

UI 状态：

[ ] 错误状态已处理并显示给用户
[ ] 加载状态仅在没有数据时显示
[ ] 为集合提供空状态
[ ] 在异步操作期间禁用按钮
[ ] 按钮在适当时显示加载指示器

数据 & 突变：

[ ] 突变有 onError 处理程序
[ ] 所有用户操作都有反馈（toast/视觉）

与其他技能的集成

graphql-schema: 使用具有适当错误处理的突变模式
testing-patterns: 测试所有 UI 状态（加载、错误、空、成功）
formik-patterns: 应用表单提交模式