React 构建高质量加载与错误 UI 状态 #

解决用户等待焦虑与数据缺失问题：通过遵循现代 React UI 模式规范，正确区分加载、空状态、错误和成功展示，避免页面闪烁并提供清晰的操作反馈。

为什么需要这个技能 #

在异步数据加载（如 GraphQL 查询、API 请求）场景中，糟糕的 UI 状态处理会导致用户困惑。常见痛点包括：刷新列表时加载指示器与骨架屏同时出现造成闪烁、用户提交表单后未收到任何反馈、网络错误被静默吞没等。

本技能旨在建立标准化的 UI 展示逻辑，确保用户始终处于“感知中”的状态，无论是正在发生、等待结果还是遭遇失败，界面都能即时响应。

适用场景 #

• 构建包含复杂异步操作（文件上传、搜索请求、列表加载）的应用组件。
• 设计需要区分“内容缺失”（无数据）与“系统繁忙”（加载中）的列表或卡片视图。
• 处理表单提交、按钮点击等交互，防止重复提交并提升操作感知。
• 编写 Robust 的错误处理逻辑，告知用户具体问题并提供重试或备选方案。

核心工作流 #

构建每个组件时，请严格执行以下状态优先级判断：

1. 确定数据状态：检查是否有错误、是否正在加载中、数据是否已获取。
2. 应用优先展示规则：
   • 错误优先：如果发生错误，优先展示错误状态（带重试选项）。
   • 无数据加载中：仅在无法显示具体数据时展示加载指示器（Spinner 或 Skeleton）。
   • 有数据：直接展示数据列表。
   • 空数据：展示空状态（Empty State），引导用户操作。

状态判断逻辑示例 #

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} />;

骨架屏与加载动画的选择 #

错误处理分层策略 #

不要将错误静默吞没，按照以下层级向上展示错误信息：

1. Inline error：表单字段级别的验证错误。
2. Toast notification：可恢复的错误（用户可重试）。
3. Error banner：页面级错误，部分数据仍可用。
4. Full error screen：不可恢复错误，需用户介入。

// 正确的错误处理：总是向用户展示错误
const [createItem, { loading }] = useCreateItemMutation({
  onCompleted: () => {
    toast.success({ title: 'Item created' });
  },
  onError: (error) => {
    console.error('createItem failed:', error);
    toast.error({ title: 'Failed to create item' });
  },
});

按钮交互状态规范 #

在异步操作期间，必须禁用按钮并显示加载状态，防止用户重复点击：

// 正确：禁用状态并显示加载中
<Button
  disabled={isSubmitting}
  isLoading={isSubmitting}
  onClick={handleSubmit}
>
  Submit
</Button>

// 错误：未禁用，允许重复点击
<Button onClick={handleSubmit}>
  {isSubmitting ? 'Submitting...' : 'Submit'}
</Button>

空状态 (Empty State) 设计 #

所有列表组件都必须定义空状态。区分“从未搜索到”和“搜索词无结果”：

// 正确：明确定义空状态组件
return (
  <FlatList
    data={items}
    ListEmptyComponent={<EmptyState />}
  />
);

Checklist #

在提交组件代码前，请检查：

• [ ] 错误状态已向用户展示，且提供重试或解决方案。
• [ ] 加载指示器仅在无数据时显示（避免与骨架屏同时出现）。
• [ ] 空状态组件已包含图标、标题和引导操作。
• [ ] 异步操作期间按钮已禁用。
• [ ] 所有用户操作都有反馈（Toast 或视觉变化）。

下载和安装 #

下载 react-ui-patterns 中文版 Skill ZIP

解压后将目录放入你的 AI 工具 skills 文件夹，重启工具后即可使用。具体路径参考内附的说明文档。

你可能还需要 #

暂无推荐