Alert Dialog Skills

设计原则

• 弹窗按交互语义选择, 不按业务文案新建组件
• 弹窗组件只负责结构、视觉、关闭语义、按钮 action 语义, 不理解业务接口
• 文案由业务传入, 基础组件只提供英文 fallback
• 标题文案要尽量短, 移动端最多保留两行, 过长标题应优先精简措辞
• 正文内容允许正常换行, 不要强行截断业务说明
• X 和 overlay 都是 close-only 语义, 不触发业务 action
• cancel 是取消 action, confirm 是确认/应用 action, undo 是撤回 action
• 异步 loading 绑定按钮 action, 不绑定弹窗整体
• 除 AdsAlertDialog 外, 支持用 loadingActions 显式声明哪些 action 需要 loading
• loading 默认是原地替换式面板, 复用普通弹窗 surface 尺寸和位置, 视觉上像弹窗内容切换成 Loading
• loading 默认用全屏透明交互锁阻塞后续操作, 但不使用遮罩压暗页面, 用户仍能看见页面内容
• 只有需要强阻断页面操作时, 才传 loadingFullPage={true} 使用全屏遮罩
• AdsAlertDialog 偏展示和跳转, 不承载 loading action 语义

组件选择

Alert Dialog 组件选择

Loading Action

通用 key 只有三个:

业务只需要记住: loadingActions 里填哪个 key, 就表示执行对应 onXxx 回调时显示 Loading

默认 loading 是非全页面板, 适合弹窗确认、按钮提交、局部批处理这类短耗时操作。

默认 loading 的视觉规则:

• 命中 loadingActions 后先建立全屏透明交互锁, 再关闭原弹窗
• 透明交互锁阻塞用户继续点击页面, 避免后端接口完成前重复操作
• 不使用 cursor-wait, Web 端鼠标不显示系统等待光标
• loading 面板复用 dialogSurfaceClass 的宽度、圆角、背景、边框、阴影和 min-h-[240px]
• loading 面板位置和普通弹窗一致, 都在屏幕中心
• Loading 组件自身必须以透明背景承载, 暗色模式也要覆盖为 dark:bg-transparent
• 设计目标是功能上已经关闭弹窗, 视觉上像原弹窗内容原地切换为 Loading

需要强阻断页面操作时, 传 loadingFullPage={true}:

命中 loadingActions 的行为顺序固定:

1. 点击按钮
2. 立即设置 loading, 建立全屏透明交互锁
3. 关闭原弹窗
4. 执行业务回调
5. Promise settle 后关闭 Loading

未命中 loadingActions 的普通 action 行为顺序:

1. 点击按钮
2. 关闭原弹窗
3. 执行业务回调

错误处理边界:

• 底层用 finally 保证 loading 关闭
• 底层不负责业务错误文案
• 调用方应该在自己的状态、toast 或页面区域里处理错误展示

关闭语义

关闭和 action 语义

UndoableConfirmDialog 特殊规则

UndoableConfirmDialog 有两个阶段:

• 首屏: cancel + 初始确认按钮
• pending 阶段: 倒计时 + undo

首屏确认按钮只进入倒计时, 不执行业务 onConfirm, 也不触发 loading

confirm 在 UndoableConfirmDialog 里表示: 倒计时结束后真正执行 onConfirm 的动作

如果倒计时自然完成和点击撤回都需要 loading:

InfoDialog

使用场景:

• 信息说明
• 成功或失败反馈
• 轻量警告
• 用户只需要知道并关闭

类型:

使用指导:

• 只有一个 confirm 按钮
• 不要用 InfoDialog 做二选一决策
• 如果 OK 后要等待异步操作, 使用 loadingActions={['confirm']}
• 标题尽量控制在简短表达内, 超长标题会在移动端占用更多垂直空间
• 正文可以正常换行, 适合承载补充说明和结果反馈

ConfirmDialog

使用场景:

• 是否继续
• 是否保存、应用、提交
• 是否删除、清空、重置
• 是否放弃已经生成或编辑的结果

核心参数:

• type="normal": 普通确认, confirm 按钮跟随主题色
• type="danger": 危险确认, confirm 按钮使用红色危险语义
• emphasis="confirm": 默认, confirm 是重点按钮
• emphasis="cancel": cancel 是重点按钮, 适合“放弃结果/丢弃内容”这类取消语义更危险的场景
• 标题尽量简短, 建议不要写过长的复合句
• 正文可以完整说明动作后果, 不需要为了适配标题去压缩内容

HighPriorityConfirmDialog

使用场景:

• 离开流程
• 未保存状态可能丢失
• 流程中断
• 用户必须立即决策

使用指导:

• 使用强遮罩和更高层级
• 点击外部不关闭
• X 仍然只关闭, 不触发 onCancel
• 不负责监听路由跳转、关闭 tab、刷新页面；那些应该由 guard/hook 层处理
• 弹框尺寸应和 InfoDialog 保持一致
• footer 按钮应贴近弹框底部, 不要额外制造底部留白
• 标题和正文遵循同一套文本规则：标题简短优先, 正文自由换行

AdsAlertDialog

使用场景:

• 广告弹窗
• 活动推广
• 图片公告
• 升级引导

使用指导:

• 图片展示优先, 不承载危险确认语义
• 按钮可选
• X 和 overlay 只关闭
• 不支持 loadingActions

文案规则

• 信息提示: OK、Got it、Close、Done
• 普通确认: Confirm、Continue、Apply、Save
• 删除: Delete
• 清空: Clear
• 重置: Reset
• 放弃: Discard、Discard Result
• 离开: Leave、Stay

不要把所有危险操作都写成 Confirm, 按钮文案要表达真实动作