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: '项目已创建' });
},
onError: (error) => {
console.error('createItem 失败:', 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>
);
};
反模式
加载状态
// 错误 - 数据存在时显示旋转器(导致闪烁)
if (loading) return <Spinner />;
// 正确 - 仅在没有数据时显示加载
if (loading && !data) return <Spinner />;
错误处理
// 错误 - 错误被吞没
try {
await mutation();
} catch (e) {
console.log(e); // 用户毫不知情!
}
// 正确 - 错误被暴露
onError: (error) => {
console.error('操作失败:', 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:应用表单提交模式