Alert
在内容上下文中持续显示提示。中文惯用名：警告提示。
稳定本期新增已接入
元信息
| 字段 | 值 |
|---|---|
| 规范 ID | component.alert |
| 名称 | Alert |
| 二级分类 | 反馈（feedback） |
| 用途 | 在内容上下文中持续显示提示 |
| 描述 | 中文惯用名：警告提示。 |
预览
静态结构：根节点 <div data-slot="alert" role="alert"> 为两列网格（grid-cols-[0_1fr]，带图标时经 has-[>svg] 让出图标列），border + rounded-lg + 语义色边框与文字（success / warning / info 读语义令牌，error 映射 vendored destructive）；message 渲染标题行（data-slot="alert-title"，font-medium），description 渲染说明行（data-slot="alert-description"，text-muted-foreground）；showIcon 或 icon 提供时前置 16px 图标（variant 映射 check-circle / info / warning / x-circle）。
DSL 结构
{
"type": "Alert",
"props": {
"variant": "success",
"showIcon": true,
"message": "保存成功",
"description": "所有更改已同步至云端。"
}
}何时用
何时使用
- 在内容上下文中持续显示提示：表单顶部、区块内的常驻说明，用户需要时它仍在原地（不自动消失）。
- 语义明确的四态提示：success / info / warning / error，用图标与语义色区分轻重。
- 需要标题 + 补充说明的静态提示：message 概括结论，description 展开原因。
何时不用
- 操作完成后的瞬时反馈：使用 Message（自动消失，不占版面）。
- 需要标题 + 正文、停留更久或可关闭的系统通知：使用 Notification。
- 需要用户确认或处理后才能继续的阻断提示：使用 Dialog；Alert 无交互区。
- 需要用户主动关闭的强提醒：使用 Notification，Alert 只做就地陈述。
变体
| 变体 | 视觉形态 | 适用场景 |
|---|---|---|
| info 信息（默认） | info 图标 + info 语义色边框文字 | 中性说明、版本更新提示；variant 缺省即 info |
| success 成功 | check-circle 图标 + success 语义色 | 操作成功后的就地确认（如「保存成功」） |
| warning 警告 | warning 图标 + warning 语义色 | 配额将满、配置即将过期等需留意但不阻断的提示 |
| error 错误 | x-circle 图标 + destructive 语义色 | 提交失败、校验不通过等阻断性说明 |
| 仅标题 / 标题 + 说明 | 省略 description 仅一行；或 message + description 两行 | 一句话提示用仅标题；需要展开原因时补说明 |
| 自定义图标 | icon 指定 Icon 白名单图标名 | 语义需更具体时替代默认四态图标（如「锁」「时钟」） |
API 属性
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
message | string | — | 提示主文案，渲染为 AlertTitle |
description | string | — | 辅助说明文案，渲染为 AlertDescription |
variant | `'success' | 'info' | 'warning' |
showIcon | boolean | false | 是否显示图标；true 时按 variant 显示默认图标（check-circle / info / warning / x-circle） |
icon | string | — | 自定义图标名（Icon 白名单，kebab-case / PascalCase 均可）；提供时隐含 showIcon |
className / style | string / CSSProperties | — | 通用：根节点 class 合并 / 内联样式 |
使用规范
- 标题写结论、说明写细节：message 一句话说清结果，description 补充原因或下一步。
- 语义色含义固定：error 只用于阻断性问题，warning 用于可继续但需留意，避免同页语义漂移。
- 图标仅强化识别、不替代文案：showIcon 打开时正文不必再写「错误：」之类的冗余前缀。
- Alert 常驻不自动消失：内容已处理完的提示要及时从数据源移除，避免陈旧提示长期占版。
- 与 Message / Notification 的分工：操作反馈用 Message（自动消失），系统通知用 Notification，常驻说明用 Alert。
正例
- ✓ 表单顶部常驻校验失败说明：variant=error、message「提交失败」、description 列出未通过字段。
- ✓ 配额提醒：variant=warning、message「本月 API 调用已达 90%」，常驻到配额恢复。
- ✓ 页面内版本公告：variant=info、message + description 说明变更内容与影响范围。
反例
- ✕ 用 Alert 做「保存成功」这类瞬时反馈（Alert 会一直占着版面，应使用 Message）。
- ✕ error 与 warning 混用表达同一含义，削弱语义色的预警效果。
- ✕ 把需要用户确认的操作写进 Alert（Alert 无按钮与交互，应使用 Popconfirm / Dialog）。
Design Token 映射
不适用：组件 tokenRefs 为空：样式 Token 数据尚未接入，三层映射（Primitive → Semantic → Component）待样式 Token 接入后回填。