
关于
现代 React UI 模式,涵盖加载状态、错误处理和数据获取。适用于构建 UI 组件、处理异步数据或管理 UI 状态。
name: react-ui-patterns description: "现代 React UI 模式,用于加载状态、错误处理和数据获取。在构建 UI 组件、处理异步数据或管理 UI 状态时使用。" risk: unknown source: community date_added: "2026-02-27"
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} />;
// 错误 - 即使有缓存数据也显示加载动画
if (loading) return <LoadingState />; // 重新获取时会闪烁!
加载状态决策树
是否有错误?
→ 是:显示带重试选项的错误状态
→ 否:继续
是否正在加载且没有数据?
→ 是:显示加载指示器(骨架屏/加载动画)
→ 否:继续
是否有数据?
→ 是,有项目:显示数据
→ 是,但为空:显示空状态
→ 否:显示加载(兜底)
骨架屏 vs 加载动画
| 使用骨架屏的场景 | 使用加载动画的场景 | |-------------------|------------------| | 已知内容形状 | 未知内容形状 | | 列表/卡片布局 | 弹窗操作 | | 初始页面加载 | 按钮提交 | | 内容占位符 | 行内操作 |
错误处理模式
错误处理层级
1. 行内错误(字段级)→ 表单验证错误
2. Toast 通知 → 可恢复错误,用户可重试
3. 错误横幅 → 页面级错误,数据仍部分可用
4. 全屏错误 → 不可恢复,需要用户操作
始终显示错误
关键:永远不要静默吞掉错误。
// 正确 - 错误始终展示给用户
const [createItem, { loading }] = useCreateItemMutation({
onCompleted: () => {
toast.success({ title: 'Item created' });
},
onError: (error) => {
console.error('createItem failed:', error);
toast.error({ title: 'Failed to create item' });
},
});
// 错误 - 错误被静默捕获,用户毫不知情
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 ?? 'Something went wrong'}</h3>
<p>{error.message}</p>
{onRetry && (
<Button onClick={onRetry}>Try Again</Button>
)}
</div>
);
按钮状态模式
按钮加载状态
<Button
onClick={handleSubmit}
isLoading={isSubmitting}
disabled={!isValid || isSubmitting}
>
Submit
</Button>
操作期间禁用
关键:异步操作期间始终禁用触发器。
// 正确 - 加载时按钮禁用
<Button
disabled={isSubmitting}
isLoading={isSubmitting}
onClick={handleSubmit}
>
Submit
</Button>
// 错误 - 用户可以多次点击
<Button onClick={handleSubmit}>
{isSubmitting ? 'Submitting...' : 'Submit'}
</Button>
空状态
空状态要求
每个列表/集合必须有空状态:
// 错误 - 没有空状态
return <FlatList data={items} />;
// 正确 - 明确的空状态
return (
<FlatList
data={items}
ListEmptyComponent={<EmptyState />}
/>
);
上下文相关的空状态
// 搜索无结果
<EmptyState
icon="search"
title="No results found"
description="Try different search terms"
/>
// 列表还没有项目
<EmptyState
icon="plus-circle"
title="No items yet"
description="Create your first item"
action={{ label: 'Create Item', onClick: handleCreate }}
/>
表单提交模式
const MyForm = () => {
const [submit, { loading }] = useSubmitMutation({
onCompleted: handleSuccess,
onError: handleError,
});
const handleSubmit = async () => {
if (!isValid) {
toast.error({ title: 'Please fix errors' });
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}
>
Submit
</Button>
</form>
);
};
兼容工具
Claude CodeCursor
标签
前端开发