空状态
概述
用于突出「内容缺失」并引导用户采取下一步操作的轻量级空状态组件。SEmpty 是 UI-only 组件：root/header/media/title/description/content 解剖节点由普通元素自绘，默认媒体图标走 SIcon，样式统一来自 emptyVariants 配方（6 个槽、6 种尺寸）。
适用于「无结果」、空收件箱、空表格或引导提示。关于状态的纯内联反馈请优先使用 alert；内容仍在加载（而非缺失）时请优先使用 skeleton。
Aria 层不存在 empty 家族：空状态不含需要在多个包装层之间复用的键盘、焦点、ARIA 或状态逻辑，因此整份装配留在 UI 层，并保留 data-vean-empty-* 属性供样式与测试使用。
用法
特性
- 🧩 UI-only 解剖壳 —
SEmpty自持 header/media/title/description 编排，纯样式驱动；没有可供组合的 Ariaempty家族 - 🖼️ 媒体 / 图标 —
iconprop 或media插槽，用于插图、emoji 或自定义图形 - 🏷️ 标题 + 描述 —
title/descriptionprop 或对应插槽 - ⚡ 操作区 —
content/default插槽，用于按钮或后续指引 - 🎨 6 种尺寸 — 匹配
ThemeSize的 xs–2xlsize - 🎛️ 逐槽控制 —
headerProps/mediaProps/contentProps/titleProps/descriptionProps转发到各部件 - ♿ 无障碍友好 — 标题渲染为真实标题元素，
axe-core零违规
组件家族
SEmpty 是单一导出。它自绘整份解剖结构，并在对应节点上暴露 data-vean-empty-root / -header / -media / -title / -description / -content，因此 class/ui 与逐部件 *Props 可以作用到每个部件。
演示
基础
No projects yet
Create your first project to start organizing work.
插槽
Nothing matched your filters
Try broadening the criteria or resetting the filters to see more results.
自定义样式
No activity
Custom styles can adapt the empty state to different scenes.
API
Aria 层
7Empty
属性
| 属性名 | 类型 | 默认值 | 描述 |
|---|---|---|---|
class | ClassValue | — | 应用于根元素的额外类名。 |
ui | Partial<EmptyUi> | — | 该组件的按槽类重写。 |
size | ThemeSize | — | 该组件的尺寸变体。 |
title | string | — | 由组件渲染的标题文本。 |
description | string | — | 由组件渲染的描述文本。 |
icon | IconValue | — | 由该组件渲染的图标。 |
headerProps | EmptyHeaderProps | — | 转发至 header 元素的属性。 |
mediaProps | EmptyMediaProps | — | 转发给媒体元素的属性。 |
contentProps | EmptyContentProps | — | 转发给内容元素的属性。 |
titleProps | EmptyTitleProps | — | 传递给 title 元素的属性。 |
descriptionProps | EmptyDescriptionProps | — | 已将属性转发至 description 元素。 |
插槽
| 插槽名 | 参数 | 描述 |
|---|---|---|
default | — | 默认插槽的自定义内容。 |
media | — | 媒体槽位的自定义内容。 |
title | — | 标题槽位的自定义内容。 |
description | — | 描述字段的自定义内容。 |
content | — | 内容插槽的自定义内容。 |
EmptyContent
EmptyDescription
EmptyHeader
EmptyMedia
EmptyRoot
EmptyTitle
注意事项
架构与对标差异
SEmpty 在 UI 层自持 header/media/title/description 编排——空状态是一个没有行为支撑的解剖壳，因此刻意没有 Aria 家族。这与 shadcn/ui 的「组合优先」一致；而 Ant Design、Element Plus、Mantine、Naive UI 则提供带 image/description prop 的单一样式化 Empty。VeanUI 提供完整的逐部件 *Props 通道与单包库通常缺失的 size 尺寸体系，默认媒体由 SIcon 渲染。
| 能力 | VeanUI | shadcn/ui | Ant Design Empty | Element Plus Empty | Mantine | Naive UI Empty |
|---|---|---|---|---|---|---|
| Aria/样式分离 | ✅ | ✅ | — | — | — | — |
| 媒体 / 图标 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| 标题 | ✅ | — | ✅ | ✅ | ✅ | ✅ |
| 描述 | ✅ | — | ✅ | ✅ | ✅ | ✅ |
| 操作 / 内容插槽 | ✅ | — | ✅ | ✅ | ✅ | ✅ |
| 尺寸变体（6） | ✅ | — | — | — | — | — |
逐部件 *Props | ✅ | ✅ | — | — | — | — |
— = 不支持或采用不同交互模型。
运行时注意
- 默认媒体由
SIcon渲染，开箱可直接用任意 Iconify 名称或组件；需要插图或 emoji 时请改用media插槽。 - 标题渲染为标题元素；请让空状态标题与周围文档大纲的标题层级匹配。
- 根节点默认使用虚线边框——嵌入卡片或实色表面时请通过
class/ui覆盖。 Empty纯展示、不持有状态；不拦截焦点，也不提供交互语义。
Roadmap
核心空状态 API 无阻塞缺口。
FAQ
如何显示图标或插图？
传入 icon（由 SIcon 渲染）或使用 media 插槽渲染任意内容：
<SEmpty title="暂无消息" description="收件箱为空" icon="lucide:inbox" />如何添加操作按钮？
使用 content（或 default）插槽：
<SEmpty title="暂无项目" description="创建一个以开始">
<SButton color="primary">新建项目</SButton>
</SEmpty>如何改变尺寸？
传入 size（xs–2xl）：
<SEmpty size="lg" title="大号空状态" />如何自定义外观？
使用 class/ui 控制样式（参考 custom-styling 示例）；也可传入逐部件 props 单独调整 header/media/content。
是否无障碍？
标题为真实标题元素，组件通过 axe-core 零违规检查；你放入插槽中的任何操作都会保留自身的可访问语义。