---
title: 弹窗
slug: 弹窗
category: 组件
figma_node_id: 1:39
figma_page_name: ＞弹窗
aliases: [Modal, Dialog, 对话框, 确认框, 弹框]
last_extracted: 2026-05-19
status: ok
---

# 弹窗

> 用于打断用户当前任务、强引导关键操作或反馈系统状态的对话框。覆盖系统升级、对话框、通知提醒、其他类型四大场景，按按钮数量分单 / 双 / 三按钮三档，桌面端与移动端共用一套设计语言。弹窗黑色蒙层为纯黑 `#000000` 透明度 32%，弹出位置于页面内居中展示。

## 类型与号型

按使用场景分四类（来自移动端 4 个分区标题）：

| 类型 | 适用场景 |
|---|---|
| 系统升级弹窗 | 客户端版本更新、新功能引导 |
| 对话框弹窗 | 关键操作的二次确认 / 信息确认（最高频） |
| 通知提醒弹窗 | 系统级通知、提醒类信息推送 |
| 其他类型弹窗 | 业务自定义弹窗 |

按结构分三档（对话框弹窗内的子型）：

| 子类型 | 含义 |
|---|---|
| 类型一 | 带主标题和正文的对话框弹窗（正文 ≥2 行，高度自适应） |
| 类型二 | 仅有正文的对话框弹窗（内容简短，1–2 行） |

按按钮数量分（标题区与按钮区上方均有标注：单按钮 / 双按钮 / 三按钮）：

| 数量 | 适用 |
|---|---|
| 单按钮 | 仅"知道了"类轻提示 / 确认 |
| 双按钮 | 主操作 + 取消（最常见） |
| 三按钮 | 三选一场景（如"保存 / 不保存 / 取消"） |

## 尺寸规格

数值取自 Figma `globalVars` 中各 layout token：

| 元素 | 宽 × 高 | 来源 / 说明 |
|---|---|---|
| 桌面端规范画板 | 1280 × 4902px | `layout_J1AIII` |
| 移动端规范画板 | 1280 × 7591px | `layout_J9BVDI` |
| 桌面端弹窗卡片（典型） | 396 × 340px | `layout_3EIVKD / WP175H / D3WSIJ` 三处 |
| 桌面端弹窗卡片（紧凑） | 396 × 314px | `layout_5N6Q4B / Y1EXOS / V8E0BJ` |
| 移动端弹窗容器 | 列布局 auto-layout，gap 16px，padding 20px | `layout_QWMQK1 / Y8KYOD / 9BZHXK` 等 9 个等价 token |
| 圆角 | 8px | 所有弹窗 `borderRadius: 8px` |
| 卡片投影（桌面） | 0 2 20px rgba(17,20,26,0.16) | `effect_xxx`（boxShadow #1） |
| 卡片投影（移动） | 0 2 20px rgba(0,35,82,0.08) | `effect_JJIJ32` |
| 标题（24px Medium 章节） | 144 × 24 / 120 × 24 | `style_WG0QM6`：24/24 Medium |
| 小节标签（12px Regular） | 含 24/36/41/60/67/81/92px 多档 | `style_TPS6CQ`：12/12 Regular |
| 子标题（12px Medium） | 34 × 12 / 37 × 12 等 | `style_QTO9N6`：12/12 Medium |
| 说明正文（14px Regular） | 多档 | `style_GIGTM7`：14/14 Regular |

## 状态

| 状态 | 含义 |
|---|---|
| 默认 | 按钮 / 弹窗常态 |
| 按钮 hover 态 | 桌面端鼠标悬停（标注于桌面端示意） |
| loading | 异步进行中（按钮文案常态保留，禁用） |

> 移动端"状态"区块出现了"绿色代表 xx / 红色代表 xx"占位说明，提示业务可按语义着色按钮主操作。

## 颜色与 token

| 用途 | hex | 说明 |
|---|---|---|
| 弹窗容器底色 | `#FFFFFF` = `White` | 所有弹窗的卡片底 |
| 蒙层 | `#000000` α 32% | 黑色蒙层，全屏遮罩 |
| 主操作按钮（强引导） | `#3377FF` | 品牌色高亮（与按钮页主蓝一致；与 `Brandblue60 #165DFF` 略有差异） |
| 警示操作按钮 | `#FF5040` | 警示语义色（同 `Vermilion60` 区段） |
| 次要操作按钮文字 | `#5C6473` | 与按钮页"状态标签灰"接近 |
| 常规按钮文字 | `#11141A` | 主文字色 |
| 章节标题文字 | `#11141A` | 24px Medium |
| 小节标签文字 | `#17181A` | 12px Medium / Regular |
| 演示用红 / 绿标尺 | `#FF0015` / 绿系 | 仅说明区使用，非组件本体色 |
| AI 渐变页头 | `linear-gradient(-64deg, rgba(51,119,255,0)→rgba(51,119,255,0.06))` | 页头装饰渐变 |

> 原文摘录：**主要操作按钮：`#3377FF`；警示操作按钮：`#FF5040`；次要操作按钮：`#5C6473`；常规按钮：`#11141A`**。
> 关联 token 详见 [色彩](../基础/色彩.md)。

## 间距与排布

- **移动端弹窗内部**（auto-layout column）：上下 padding 20px，元素间 gap 16px
- **居中展示**：弹窗弹出位置于页面内居中
- **蒙层覆盖**：纯黑 #000000 / 32% 全屏蒙层
- **桌面端示例卡片宽**：396px（结构示意 / 间距示意 / 按钮示意均同宽）
- **移动端示例卡片宽**：448.5px（"正文最小高度&最大高度限制"列宽 448.5×1224）

## 文案规则

> 适用于正文至少 2 行的情况；高度自适应，有最大高度限制，超出最大高度后滚动；按钮文案建议 4 字以内。
> 适用于内容简短，2 行以内的对话框弹窗；高度固定，最少 1 行文案，最多 2 行；按钮文案建议 4 字以内。

- 按钮文案建议 **4 字以内**（与按钮页"≤6 字"互为参考，弹窗内更紧凑）
- 正文长度：
  - 类型一：正文 ≥2 行，超出最大高度滚动
  - 类型二：1–2 行固定高度
- 主标题与正文需层级清晰；可增加 icon 时整体改为左对齐
- 标题区默认居中 / 左对齐（不同子类型不同，见结构示意）

## 交互行为

> 弹窗黑色蒙层为纯黑 `#000000`，透明度 32%。
> 当需要对用户某一操作进行强引导时，按钮可以高亮（品牌色）显示。
> 在页面居中展示。

- **触发**：由系统事件或用户操作触发，遮挡当前页面交互
- **居中模态**：弹窗于页面内居中，蒙层 32% 全屏遮挡
- **强引导高亮**：当需强引导时，主操作按钮使用品牌色 `#3377FF`
- **滚动**：类型一正文超出最大高度时内部滚动，外框不撑高
- **按钮组**：
  - 单按钮 → 居中 / 右对齐
  - 双按钮 → 次要 + 主要，主按钮在右
  - 三按钮 → 排列遵循"次要 + 次要 + 主要"
- **可配置图标**：当顶部加 icon 时，整个弹窗内容改为左对齐
- **Win / Mac 端**：分别提供 Win 端、Mac 端示例（按钮顺序遵循各自平台规范）

## 示例

![桌面端弹窗-总览](../图片/组件/弹窗/desktopmodaloverview.png)
![桌面端弹窗-默认状态](../图片/组件/弹窗/desktopdefault.png)
![桌面端弹窗-结构与间距示意](../图片/组件/弹窗/desktopjie-gouspacingdemo.png)
![桌面端弹窗-单按钮-双按钮-三按钮](../图片/组件/弹窗/desktopan-niu-zu.png)
![桌面端弹窗-Win端Mac端对比](../图片/组件/弹窗/desktopWinMacdui-bi.png)
![移动端-系统升级弹窗](../图片/组件/弹窗/mobilexi-tongupgrademodal.png)
![移动端-对话框弹窗-类型一](../图片/组件/弹窗/mobilechatkuang-lei-xing-yi.png)
![移动端-对话框弹窗-类型二](../图片/组件/弹窗/mobilechatkuang-lei-xing-er.png)
![移动端-通知提醒弹窗](../图片/组件/弹窗/mobilenotifyremindermodal.png)
![移动端-其他类型弹窗](../图片/组件/弹窗/mobileqi-ta-lei-xingmodal.png)
![移动端-正文最小最大高度](../图片/组件/弹窗/mobilebodygao-du-xian-zhi.png)
![移动端-单双三按钮间距](../图片/组件/弹窗/mobilean-niuspacingbiao-zhu.png)

## 设计考量 / 原文摘录

> 类型一：带主标题和正文的对话框弹窗。
> 类型二：仅有正文的对话框弹窗。
> 适用于正文至少 2 行的情况；高度自适应，有最大高度限制，超出最大高度后滚动；按钮文案建议 4 字以内。
> 适用于内容简短，2 行以内的对话框弹窗；高度固定，最少 1 行文案，最多 2 行；按钮文案建议 4 字以内。
> 弹窗黑色蒙层为纯黑 #000000，透明度 32%。
> 当需要对用户某一操作进行强引导时，按钮可以高亮（品牌色）显示。
> 在页面居中展示。
> 主要操作按钮：#3377FF；警示操作按钮：#FF5040；次要操作按钮：#5C6473；常规按钮：#11141A。

- **场景四分**：把弹窗按"系统升级 / 对话框 / 通知提醒 / 其他"分四类，让设计师按目的而非按形状取用
- **结构三档**：单 / 双 / 三按钮覆盖确认、二选一、三选一场景
- **按钮 ≤4 字**：移动端胶囊宽有限，文案过长会换行破坏对齐
- **蒙层 32%**：在保证下层内容仍可见、能让用户感知到上下文的前提下提供足够对比

## 不推荐用法

- 把弹窗用于非阻断式提示（应改用 [Toast](Toast.md)）
- 同时打开两个及以上弹窗（蒙层叠加、信息层级混乱）
- 按钮文案超过 4 字（容易换行 / 截断）
- 三按钮以上（决策疲劳，应改流程或拆步骤）
- 自定义弹窗圆角 / 蒙层透明度（应统一 8px 与 32%）
- 主操作按钮使用警示红（红色仅用于警示语义，非"强引导"语义）

## 关联

- 弹窗中的按钮规范见 [按钮](按钮.md)
- 不打断流程的反馈见 [Toast](Toast.md)
- 由触发元素旁出现的弹层见 [浮层](浮层.md)、[指向弹窗](指向弹窗.md)
- 独立窗口形态见 [浮窗](浮窗.md)
- 色彩 token 见 [色彩](../基础/色彩.md)
- 字体 token 见 [字体](../基础/字体.md)
