组件
States 空白、错误与等待
解释当前状况，并让用户知道能继续做什么。
首次加载用 ListSkeleton，没有内容用 EmptyState，区域失败用 ErrorState；已有内容刷新失败时用 RefreshNotice 保留上下文。Alert 适合局部说明和任务结果。
安装
pnpm dlx shadcn@4.22.1 add http://127.0.0.1:3040/r/v0.3.0/states.json首次使用请先完成 Registry 与主题接入。
变体与状态
EmptyState 提供 default、onboarding、compact；Alert 提供 info、success、warn、danger。说明要回答发生了什么和接下来做什么，而非只显示“暂无数据”。
Props
| API / 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
EmptyState.title | ReactNode | 必填 | 当前状态 |
description / action / icon | ReactNode | — | 原因、下一步和图形 |
EmptyState.variant | default / onboarding / compact | default | 状态呈现规模 |
ListSkeleton.rows / label | number / string | 5 / 正在加载 | 行数限制在 1–20 |
Alert.tone | danger / success / info / warn | info | danger 使用 alert 角色 |
Alert.title / icon / action | ReactNode | — | 局部说明与恢复 |
ErrorState.title | ReactNode | 暂时无法加载 | 失败名称 |
ErrorState.onRetry / retryLabel | 回调 / 文案 | — / Provider 的“重试” | 仅提供回调时显示按钮 |
ErrorState.details | ReactNode | — | 可公开的辅助详情 |
RefreshNotice.retryLabel | string | 重新刷新 | 轻量刷新动作 |
RefreshNotice 要求 children；ErrorState 可传 description。默认提供中文基础文案，实际产品应补充与当前任务相关的原因和下一步。
键盘与约束
恢复动作使用真实按钮。加载区域使用 status / aria-busy，失败使用 alert；不可自动抢走正在输入的焦点。可重试只表示用户能再发起任务，不代表网络已恢复。
避免这样使用
不要用空状态掩盖请求失败；不要用整页错误清掉仍可阅读的缓存内容；不要在 details 中暴露堆栈或凭据。
来源与版本
0.1.0，来自 Subtic apps/web/components/states.tsx 与路由状态呈现。组件不调用路由 reset、请求或错误上报。
查看由当前源码生成的类型参考
只展示 Kitseed 自身定义的属性，原生 HTML 与 Base UI 透传属性请参阅对应上游说明。
ListSkeleton
| 属性 | 类型 | 默认值 |
|---|---|---|
rows? | number | 5 |
label? | string | "正在加载" |
className? | string | — |
EmptyState
| 属性 | 类型 | 默认值 |
|---|---|---|
icon? | ReactNode | — |
title | ReactNode | — |
description? | ReactNode | — |
action? | ReactNode | — |
variant? | "default" | "onboarding" | "compact" | "default" |
className? | string | — |
Alert
| 属性 | 类型 | 默认值 |
|---|---|---|
tone? | "danger" | "success" | "info" | "warn" | "info" |
title? | ReactNode | — |
icon? | ReactNode | — |
action? | ReactNode | — |
ErrorState
| 属性 | 类型 | 默认值 |
|---|---|---|
title? | ReactNode | "暂时无法加载" |
description? | ReactNode | — |
onRetry? | () => void | — |
retryLabel? | string | — |
details? | ReactNode | — |
className? | string | — |
RefreshNotice
| 属性 | 类型 | 默认值 |
|---|---|---|
children | ReactNode | — |
onRetry? | () => void | — |
retryLabel? | string | "重新刷新" |
className? | string | — |