loading-states

加载与空状态

确保用户不会盯着空白或看起来卡住的屏幕：盘点应用中每个需要等待或可能为空的地方，根据预期延迟为每处选择合适的状态，并予以实现。**首要原则：根据等待时长和布局是否已知来选择指示器，而不是凭喜好。**提交一张涵盖所有异步界面及其已实现状态的审计表，而不是只做一个孤立的加载动画组件。

何时使用 / 何时不使用

适用于：加载指示器、骨架屏、进度条、空状态（首次使用、无搜索结果、错误空状态、成功空状态）以及“应用看起来卡住了”的问题。

如果实际需求是以下内容，请转交处理：

• 缩短等待时间或让等待不可见（乐观 UI、预加载、缓存）→ skills/frontend-design/performance-optimization — 始终先考虑这一点；最好的加载状态就是没有加载状态
• 超出简单重试空状态范畴的错误消息和恢复流程 → skills/frontend-design/error-handling-recovery
• 微调闪烁效果 / 旋转加载动画、时序令牌 → skills/frontend-design/interaction-physics

步骤 0 — 检查代码库，然后只询问尚未明确的内容

1. 盘点异步界面：搜索 fetch(、axios、useQuery/useSWR/createResource、isLoading/isPending/loading 标志、Suspense 边界以及路由级数据加载器。列出每个需要等待数据或变更操作的视图 / 组件。
2. 对每个界面，记录等待期间当前显示的内容：什么都没有（空白）、布局跳动、旋转加载动画、骨架屏，或已禁用的控件。“什么都没有”和“布局跳动”是应优先修复的问题。
3. 检查是否已有骨架屏 / 旋转加载动画 / 空状态组件 — 复用并扩展它们，而不是重复创建。
4. 根据证据估算每个界面的预期延迟：缓存的客户端状态（近乎即时）、同区域 API 读取（通常不到 1 秒）、搜索 / 聚合端点（数秒）、上传 / 导出 / 报告生成（耗时较长，通常可测量）。查找现有的超时配置或遥测数据。如果无法估算，请说明并采用 1 秒级处理方式作为安全默认值。
5. 列出所有可能为空的视图：每个列表、表格、网格、搜索结果和收件箱都可能为空。检查哪些视图当前只显示一片空白。

仅在无法推断时一次性询问用户：是否已知有任何耗时较长的操作（上传、导出、批处理作业），以及是否有针对插图 / 空状态的设计语言。否则说明假设并继续 — 绝不要因为代码已经能回答的问题而搁置审计。

工作流

1. 根据延迟阶梯选择每种加载状态

预期等待时间	处理方式
< 100ms	不显示 — 一闪而过的指示器比不显示更糟
100ms – 1s	微妙的内联提示：按钮旋转加载动画 / 降低不透明度、cursor: wait；不改变布局
1s – 10s	如果已知即将显示的布局，则使用骨架屏；如果未知，则使用旋转加载动画
> 10s	使用进度条 — 如果可测量，则显示确定进度及数量 / 百分比；否则显示不确定进度和说明文字

分支规则：

• **骨架屏还是旋转加载动画：**内容结构已知（卡片、列表、表格、个人资料）→ 使用精确模仿对应布局的骨架屏。结构未知 / 可变，或是按钮等小区域 → 使用旋转加载动画。绝不要为模态框、Toast 或下拉菜单使用骨架屏 — 它们必须让人感觉即时响应。
• **变更操作还是读取操作：**提交操作使用按钮级加载状态（在按钮中显示旋转加载动画、隐藏标签、保持宽度不变）；读取操作使用页面 / 区域级状态。不要因为局部变更操作而阻塞整个页面。
• **防止闪现：**如果等待时间可能很短，将指示器延迟约 150–200ms 再显示，以便快速响应时什么都不显示；显示后至少保持 300–500ms，避免闪烁。
• 只要总大小 / 数量可知，就优先使用确定进度，而非不确定进度（上传：字节数；批处理：已完成项数）。

2. 按类型设计每种空状态

每个空视图都采用以下四种处理方式之一——先分类，再应用：

类型	触发条件	必须包含
首次使用	用户尚无数据	说明此区域的用途 + 创建第一个项目的主要 CTA
无搜索结果	搜索／筛选没有匹配项	显示搜索内容 + 提供退出途径（“清除筛选条件”）
错误空状态	加载失败	通俗易懂的失败说明 + 重试操作（将复杂的恢复流程交给 skills/frontend-design/error-handling-recovery）
成功空状态	所有项目均已完成（收件箱为零）	正向确认；无需 CTA

规则：没有操作的空状态就是死胡同——只有成功空状态可以省略 CTA。

3. 按结构规则实现

• 骨架屏的尺寸应与实际内容一致——切换时不得造成布局偏移（这也能修复 CLS）。预留空间；文本行宽度应有所不同。
• 操作发生时（或防闪烁延迟结束后）立即显示加载状态——绝不要等到收到第一个字节。
• 无障碍性：加载区域添加 aria-busy="true" 和用于播报“Loading”的礼貌式实时区域；骨架屏添加 aria-hidden="true"；进度条使用 role="progressbar" 和 aria-valuenow/min/max；在 prefers-reduced-motion 生效时停止闪烁动画。
• 标准实现（骨架屏闪烁动画、按钮加载动画、确定／不确定进度、四种空状态、无障碍代码块）：references/patterns.md——编写代码时请阅读。

4. 验证

模拟慢速网络（使用开发者工具的网络限速或人为延迟），并确认：没有空白帧；内容切换时没有布局偏移；快速响应时指示器不会闪现；空状态会连同对应操作一起显示。

必需的输出格式

交付两项内容：

1. 代码——实现骨架屏／加载动画／进度条／空状态组件，并将它们接入每个异步界面，复用项目现有组件和设计令牌。

2. 加载与空状态审计（Markdown）：

## Async surface inventory
| Surface | Wait class | Current | Correct state | Status |
| Product grid | 1–10s (search API) | blank screen | card skeleton ×8 | implemented |
| Save button | 100ms–1s | none | inline button spinner | implemented |
| CSV export | >10s | spinner | determinate progress + count | implemented |
| Comments | unknown → assume 1s class | layout jump | skeleton, space reserved | implemented |

## Empty state coverage
| View | First use | No results | Error-empty | Success-empty |
| Projects list | ✓ CTA "Create project" | n/a | ✓ Retry | n/a |
| Search page | n/a | ✓ "Clear filters" | ✓ Retry | n/a |

## Assumptions
[Latency estimates you could not verify, flagged for the user]

质量标准（交付前检查）

• 清单中的每个异步界面都已分配状态——没有遗漏的空白
• 每种状态选择都有延迟阶梯依据，而非个人偏好
• 骨架屏与实际内容布局一致；内容切换不会造成任何布局偏移
• 模态框／Toast／下拉菜单中不使用骨架屏；局部变更不使用整页遮罩
• 对可能较短的等待时间，通过延迟显示、最短显示时长等方式防止指示器闪现
• 除成功空状态外，每种空状态都有操作
• 已添加 aria-busy、实时区域播报、role="progressbar" 值、骨架屏的 aria-hidden 属性及减少动态效果处理
• 操作耗时超过 10s 时显示进度或说明文字，绝不只显示一个加载动画

严格禁止：不能所有情况都用加载动画；不能向用户展示臆造的时间估算（例如“约 2 分钟”），除非该估算源自真实数据；不能为瞬间完成的操作显示加载状态。

集成

• skills/frontend-design/performance-optimization → 先运行或同时运行；乐观 UI 可以免去许多加载状态，骨架屏空间预留也属于 CLS 优化工作。
• skills/frontend-design/error-handling-recovery ← 使用你设置的错误空状态，并将其扩展为完整的恢复流程。
• skills/frontend-design/interaction-physics → 提供闪烁动画／加载动画的时长设置及减少动态效果的基线。
• skills/frontend-design/component-architecture → 提供骨架屏必须仿照的组件清单；在其中将 Skeleton／EmptyState 添加为共享组件。

参考资料

• references/patterns.md — 完整实现示例集：骨架屏基础组件和卡片示例、加载动画与按钮加载 CSS、确定／不确定进度条、四种空状态标记，以及无障碍代码块。编写代码时请阅读。