[ PROMPT_NODE_24802 ]
loading-and-error-states
[ SKILL_DOCUMENTATION ]
# 加载与错误状态
**关键**：正确的加载和错误状态处理可防止布局偏移并提供更好的用户体验。
---
## ⚠️ 关键规则：严禁使用早期返回 (Early Returns)
### 问题所在
typescript
// ❌ 严禁这样做 - 带有加载旋转器的早期返回
const Component = () => {
const { data, isLoading } = useQuery();
// 错误：这会导致布局偏移和糟糕的用户体验
if (isLoading) {
return ;
}
return ;
};
**为什么这样做不好：**
1. **布局偏移**：加载完成时内容位置跳动
2. **CLS (累积布局偏移)**：核心 Web 指标得分低
3. **突兀的用户体验**：页面结构突然改变
4. **滚动位置丢失**：用户在页面上的位置丢失
### 解决方案
**选项 1：SuspenseLoader (新组件首选)**
typescript
import { SuspenseLoader } from '~components/SuspenseLoader';
const HeavyComponent = React.lazy(() => import('./HeavyComponent'));
export const MyComponent: React.FC = () => {
return (
);
};
**选项 2：LoadingOverlay (用于遗留的 useQuery 模式)**
typescript
import { LoadingOverlay } from '~components/LoadingOverlay';
export const MyComponent: React.FC = () => {
const { data, isLoading } = useQuery({ ... });
return (
);
};
---
## SuspenseLoader 组件
### 作用
- 在懒加载组件加载时显示加载指示器
- 平滑的淡入动画
- 防止布局偏移
- 在整个应用中提供一致的加载体验
### 导入
typescript
import { SuspenseLoader } from '~components/SuspenseLoader';
// 或
import { SuspenseLoader } from '@/components/SuspenseLoader';
### 基础用法
typescript
### 配合 useSuspenseQuery 使用
typescript
import { useSuspenseQuery } from '@tanstack/react-query';
import { SuspenseLoader } from '~components/SuspenseLoader';
const Inner: React.FC = () => {
// 无需 isLoading!
const { data } = useSuspenseQuery({
queryKey: ['data'],
queryFn: () => api.getData(),
});
return ;
};
// 外部组件包装在 Suspense 中
export const Outer: React.FC = () => {
return (
);
粤公网安备44030002003366号