提示

概述

用于突出重要、有时效性信息——警告、错误或确认——并在其相关内容附近的提示框。SAlert 组合 AlertRoot/AlertTitle/AlertDescription/AlertClose 这一系列 Aria 基础组件（零样式）与 alertVariants 样式配方（6 个槽、8 种颜色 × 5 种变体 × 6 种尺寸）。

适用于不容错过的内联反馈。短暂、全局的通知请优先使用 toast；阻塞性确认请优先使用 dialog。全宽横幅（Banner）变体见 roadmap 中的 Banner 项。

用法

特性

🧩 Aria/样式分离 — AlertCompact 聚合基础组件并组合默认图标/标题/描述/关闭；SAlert 只注入样式并转发插槽/事件
🏷️ 标题 + 描述 — title/description prop 或对应插槽
❌ 可关闭 — closable 渲染带本地化 aria-label 的关闭 <button>，由 v-model:open 驱动
🎨 8 种颜色 — ThemeColor 值（primary/destructive/success/warning/info/carbon/secondary/accent）
🖌️ 5 种变体 — solid/pure/outline/soft/ghost
📐 6 种尺寸 — xs–2xl size
🖼️ 前导图标 — icon prop 或 leading 插槽
♿ 无障碍 — 关闭控件为真实 <button>，带本地化 aria-label；axe-core 零违规

组件家族

SAlert（样式层）— 入口包装组件；alertVariants 配方配合动态插槽转发
AlertRoot（Aria）— 容器；经 useControllableState 维护 open 并通过 provideAlertRootContext 下发
AlertContent（Aria）— 承载标题/描述的内容区
AlertTitle（Aria）— 标题
AlertDescription（Aria）— 描述
AlertClose（Aria）— 关闭 <button>；本地化 aria-label，发出 close 并切换 open
AlertCompact（Aria）— 聚合组件；组合图标/标题/描述/关闭并暴露各插槽

演示

基础

100%

Info

This is an info alert

插槽

100%

Flighting !!!

API

Aria 层

Alert

15 属性2 事件6 插槽

属性

属性名	类型	默认值	描述
class	ClassValue	—	根类
size	ThemeSize	—	组件的视觉尺寸。
color	ThemeColor	—	组件的主题颜色。
variant	AlertVariant	—	该组件的视觉变体。
ui	Partial<AlertUi>	—	该组件的按槽类重写。
title	string	—	由组件渲染的标题文本。
description	string	—	由组件渲染的描述文本。
icon	IconValue	—	由该组件渲染的图标。
closable	boolean	—	该组件是否可以闭合。
contentProps	AlertContentProps	—	转发给内容元素的属性。
titleProps	AlertTitleProps	—	传递给 title 元素的属性。
descriptionProps	AlertDescriptionProps	—	已将属性转发至 description 元素。
closeProps	AlertCloseProps	—	转发至 close 元素的属性。
open	boolean	true	alert 的受控打开状态。可通过 `v-model:open` 进行绑定。
role	'alert' \| 'status'	'alert'	alert 的 ARIA 实时区域角色。`role="alert"` 表示强制性实时区域（会打断当前操作），而 `role="status"` 表示礼貌型实时区域（不会打断当前操作）。

事件

事件名	参数	描述
update:open	boolean	当 open 发生变化时触发。
close	PointerEvent	点击关闭按钮时触发。

插槽

插槽名	参数	描述
default	—	默认插槽的自定义内容。
leading	—	为首行位置提供自定义内容。
title	—	标题槽位的自定义内容。
description	—	描述字段的自定义内容。
trailing	—	尾部槽位的自定义内容。
close	—	close 插槽的自定义内容。

AlertClose

4 属性1 事件

属性

属性名	类型	默认值	描述
type	ButtonType	'button'	按钮元素的类型。可以是 'button'、'submit' 或 'reset' 之一。
disabled	boolean	—	该组件是否已禁用。
asChild	boolean	—	将默认渲染元素替换为作为子元素传递的元素，并合并两者的属性及行为。
as	AsTag \| Component	'div'	该组件应渲染为的元素或组件。可通过 `asChild` 进行覆盖。

事件

事件名	参数	描述
close	PointerEvent	点击关闭按钮时触发。

AlertCompact

10 属性2 事件6 插槽

属性

属性名	类型	默认值	描述
title	string	—	由组件渲染的标题文本。
description	string	—	由组件渲染的描述文本。
icon	IconValue	—	由该组件渲染的图标。
closable	boolean	—	该组件是否可以闭合。
contentProps	AlertContentProps	—	转发给内容元素的属性。
titleProps	AlertTitleProps	—	传递给 title 元素的属性。
descriptionProps	AlertDescriptionProps	—	已将属性转发至 description 元素。
closeProps	AlertCloseProps	—	转发至 close 元素的属性。
open	boolean	true	alert 的受控打开状态。可通过 `v-model:open` 进行绑定。
role	'alert' \| 'status'	'alert'	alert 的 ARIA 实时区域角色。`role="alert"` 表示强制性实时区域（会打断当前操作），而 `role="status"` 表示礼貌型实时区域（不会打断当前操作）。

事件

事件名	参数	描述
update:open	boolean	当 open 发生变化时触发。
close	PointerEvent	点击关闭按钮时触发。

插槽

插槽名	参数	描述
default	—	默认插槽的自定义内容。
leading	—	为首行位置提供自定义内容。
title	—	标题槽位的自定义内容。
description	—	描述字段的自定义内容。
trailing	—	尾部槽位的自定义内容。
close	—	close 插槽的自定义内容。

AlertContent

AlertDescription

AlertRoot

2 属性1 事件

属性

属性名	类型	默认值	描述
open	boolean	true	alert 的受控打开状态。可通过 `v-model:open` 进行绑定。
role	'alert' \| 'status'	'alert'	alert 的 ARIA 实时区域角色。`role="alert"` 表示强制性实时区域（会打断当前操作），而 `role="status"` 表示礼貌型实时区域（不会打断当前操作）。

事件

事件名	参数	描述
update:open	boolean	当 open 发生变化时触发。

AlertTitle

注意事项

架构与对标差异

AlertCompact 负责图标/标题/描述/关闭的默认装配，所有基础组件保持零样式，仅由 UI 包装组件注入 alertVariants 类。这与 shadcn/ui 的 headless/样式分离一致；而 Ant Design、Element Plus、Mantine、Naive UI 则提供带 type/closable/showIcon prop 的单一样式化提示。VeanUI 暴露完整的逐槽 *Props 通道与单包库通常缺失的 size 尺寸体系，并将关闭按钮的 aria-label 本地化（alert.close），而非依赖纯 × 字形。

能力	VeanUI	shadcn/ui	Ant Design Alert	Element Plus Alert	Mantine Alert	Naive UI Alert
Aria/样式分离	✅	✅	—	—	—	—
标题 + 描述	✅	✅	✅	✅	✅	✅
可关闭	✅	—	✅	✅	✅	✅
前导图标	✅	—	✅	✅	✅	✅
变体（solid/soft/ghost）	✅	✅	—	—	—	—
颜色（8）	✅	✅	✅	✅	✅	✅
尺寸（6）	✅	—	—	—	—	—
本地化关闭标签	✅	—	—	✅	—	—

— = 不支持或采用不同交互模型。

运行时注意

关闭按钮的 aria-label 由 alert.close（如 关闭提示）本地化而来。可通过 SAlert 上的 aria-label 或自定义 close 插槽覆盖。
open 默认 true；closable 显示关闭按钮。用 v-model 绑定 open 以控制关闭。
variant="solid" 将文本切换为颜色前景色；soft/ghost 用半透明色给背景着色。
icon 前导图形为装饰性；消息内容由标题/描述承载。
Alert 是静态提示框——不设置 live/alert role，也不自动消失；短暂通知请使用 toast。

Roadmap

全宽 Banner 变体记录在 docs/roadmap/README.md（P2）。

FAQ

如何显示标题与描述？

传入 title/description prop（或对应插槽）：

<SAlert color="warning" title="请注意" description="您的会话即将过期。" />

如何让提示可关闭？

设置 closable 并用 v-model 绑定 open：

<SAlert v-model:open="open" closable title="关闭我" />

如何改变颜色与变体？

使用 color（8 个值）与 variant（solid/pure/outline/soft/ghost）：

<SAlert color="success" variant="soft" title="已保存" description="所有更改均已存储。" />

如何添加图标？

使用 icon prop（经 ConfigProvider iconRender）或 leading 插槽：

<SAlert icon="lucide:info" title="信息" description="请阅读文档。" />

如何自定义关闭控件？

使用 close 插槽读取关闭行为（或自行提供 aria-label）：

<SAlert v-model:open="open" closable title="自定义关闭">
  <template #close><button type="button" aria-label="关闭" @click="open = false">×</button></template>
</SAlert>

快速跳转

同分类组件

提示

概述

用法

特性