退出动效系统规格¶
意图¶
一个可以动效入场的表面也可以动效退场,这样用户就能看到它去了哪里,以及它露出了什么。在指针呈现中,某类表面是否播放其退场是一个主题决策:在没有任何主题设置的情况下,该表面会立即关闭,就像没有退场的表面一样。触摸呈现改为播放其原生对应物的退场(spec:AST-094 FR7),此处的开关不会触及它。
触摸呈现 是一种在水合之后、处于粗略主指针之下的呈现,如 spec:AST-094 FR13 所定义。所有其他呈现,包括服务端渲染和水合渲染,都是指针呈现。
本记录拥有退场词汇表、在指针呈现中为每种表面开启退场的开关、指针呈现的表面在离开期间如何表现,以及其层退场在哪些浏览器中播放。两种表面会获得退场:
- 对话框表面 是
Dialog,包括AlertDialog、CommandPalette、useImperativeDialog和useImperativeAlertDialog渲染出的对话框。 - 层表面 是一种播放共享层入场的锚定层。当前成员包括
Popover、Tooltip、HoverCard、DropdownMenu及其子菜单、ContextMenu、Selector、ComplexSelector、PowerSearch,以及BreadcrumbItem的菜单。此列表是一个快照,而非封闭集合。
design:motion 拥有动效意图,并把 token 和组件行为留给其他记录。architecture:theme-tokens 拥有 token 词汇表,而不是哪些组件读取某个 token,或它们在关闭时做什么。一个被十几个组件通过两个共享原语读取的开关,是一个系统事实。
非目标¶
- 触摸呈现的退场,由每个组件的记录在
spec:AST-094FR7 和 FR8 下给出(FR14)。此处的退场开关不会触及触摸退场;在以点按为主要交互的组件中,由点按、按键或程序启动的触摸退场会播放--duration-exit和--ease-exit;在手势组件(如 sheet 或 Lightbox)中,每个退场都播放其弹簧,而手势驱动的退场从释放速度开始(FR14)。 - 已经具有退场动画的表面(
Drawer、BottomSheet、MobileNav、Toast和TopNavMegaMenu面板)在指针呈现中保留各自的持续时间和曲线;对于手势驱动的退场,即带有速度的轻扫或拖拽,则保留其测得的弹簧。在触摸呈现中,由点按、按键或程序启动的退场,在以点按为主的组件中播放--duration-exit和--ease-exit;在手势组件中则播放组件的弹簧,包括BottomSheet的关闭(FR14)。BottomSheet在指针呈现中的关闭,会在其使用的曲线上读取--ease-exit(FR12);将其他组件的指针呈现退场迁入退场词汇表,是一个视觉变化,需另行决定。 - 没有入场的层(
Typeahead建议、MultiSelector、Tokenizer、日期和时间选择器、TabList溢出菜单、TopNav和SideNav菜单,以及 Chat 触发器菜单)在此不获得退场。 - 页面流中带有入场动画的元素,例如
FieldStatus和useEntryAnimation,在此不获得退场(OQ2)。 - 入场不变:它们的持续时间和曲线、悬停打开的层的入场,以及
Dialog背景遮罩的入场。 - 语义化动效词汇表的其余部分(入场、移动和状态曲线;入场、遮罩和揭示持续时间)不在此处确定。退场名称遵循
--ease-<job>和--duration-<job>模式,以便该词汇表无需重命名即可加入它们。 - 满足本契约时,等效的内部实现仍然有效。对话框在离开期间如何保持打开、离开中的层如何保持绘制在原位置,以及如何检测退场结束,都属于实现细节。
要求¶
FR1–FR13 规范指针呈现中的对话框和层表面。FR14 规范触摸呈现中的它们。
- FR1 — 默认关闭退场。
--duration-exit-dialog和--duration-exit-layer默认为0ms。主题将退场持续时间设置为对 tempo 缩放 token 的引用(如 FR12 的var(--duration-exit))时,会遵循该主题的 tempo;设置为字面量时则按所写值播放(spec:AST-108FR5)。某类表面的退场持续时间为零时,该表面立即关闭:它在关闭它的那次更新中被隐藏,焦点、回调和关闭行为与没有退场的表面一致。 - FR2 — 主题逐类开启退场。 当某类表面的退场持续时间(在该表面处解析后)大于零时,该表面播放退场。这两类彼此独立。这些持续时间与任何 token 一样解析,因此主题或嵌套的
Theme可为其所主题化的表面开启或关闭某一类。 - FR3 — 退场沿入场路径反向进行。 离开中的表面沿其入场路径反向移动并淡出,使用
--ease-exit,持续时间为该类的退场持续时间。对话框向打开它的元素收缩,若没有打开它的元素则向下收缩;全屏对话框仅淡出;层向其锚点收缩,在从右到左布局中与其入场一样镜像。对话框的背景遮罩在同一持续时间内淡出。--ease-exit适用于 CSS 计时的退场;弹簧驱动的退场播放自己的退场角色,旁边的 CSS 部分则采用弹簧的稳定时间(spec:AST-108FR3、FR4a)。 - FR4 — 离开中的表面不接受输入。 从其关闭开始的那一刻起,任何指针按下或按键都不得激活离开中表面自身内容中的任何内容。离开中的对话框所承载的 Toast 不属于其内容(FR13)。
- FR5 — 离开中的表面保留其关闭角色,关闭中的固定层除外。 在隐藏之前,离开中的表面保留其在打开时所拥有的关闭角色(
spec:AST-003FR1),但下方所述的关闭中的固定Tooltip除外。离开中的活动或阻塞所有者继续保留在共享关闭栈上(family:overlay-dismissalFR2),因此在退场期间按 Escape 或发出平台关闭请求不会到达其下方的所有者,但关闭中的固定Tooltip除外,后者在退场开始时离开该栈。离开中的被动依赖者(例如未固定的Tooltip)保持被动且不遮挡任何东西(spec:AST-003FR4)。正在关闭的固定Tooltip会播放退场,并在退场开始后不再接收 Escape:它不再是该栈的所有者,因此其下方的成员会接收下一次 Escape(spec:AST-003FR4、DEC-6)。 - FR6 — 焦点随关闭一起离开。 层表面在关闭开始时交还焦点,与退场关闭时的行为相同;此后,其退场对辅助技术隐藏:屏幕阅读器既不读取也不播报它。对话框表面在对话框隐藏时将焦点返回给打开它的元素;在此之前,模态对话框后面的页面无法获得焦点。
- FR7 — 回调报告关闭请求。 当请求关闭时,
onOpenChange(false)、onHide以及层的isOpen会发生变化,与退场关闭时相同。对话框的原生close事件在对话框隐藏时触发。 - FR8 — 中断无闪烁地解决。 重新打开一个正在离开的表面会使其保持在屏幕上并恢复到打开状态;它绝不会被隐藏后再显示。卸载正在离开的表面,或用 React
Activity隐藏其子树,会立即将其移除。 - FR9 — 离开中的表面绝不会滞留。 离开中的表面在退场持续时间结束后不超过 100ms 即被隐藏,无论浏览器是否报告其退场结束。这包括禁用动画和过渡的页面,以及在同一更新中打开和关闭的表面。
- FR10 — 减弱动态时立即关闭。 在
prefers-reduced-motion: reduce下,指针呈现中的对话框或层表面会立即关闭,无论其类别的退场持续时间是多少(design:reduced-motionDR3、DR4)。 - FR11 — 离开期间内容保持显示。 离开中的表面持续显示关闭开始时所显示的内容,直到被隐藏:hover card 的内容、菜单中打开的子菜单,以及 selector 的搜索查询,都会保持显示在屏幕上,直到表面被隐藏。
- FR12 — 退场词汇表。
--ease-exit默认为cubic-bezier(0.3, 0, 0.6, 0.6),这是一条缓慢移出、快速离开的曲线。对话框和层退场使用它,BottomSheet在指针呈现中的关闭也使用它。--duration-exit默认为var(--duration-fast),是标准关闭持续时间。主题通过将该类别的退场持续时间设置为var(--duration-exit)或任何其他持续时间来开启该类别的退场。 - FR13 — Toast 在离开中的对话框上方保持可操作。 离开中的对话框仍然是原生模态,因此它持续提供其模态出口(
spec:AST-003FR18),直到被隐藏。在整个退场期间,Toast 在其上方保持可见且可操作(spec:AST-003FR16)。当它被隐藏时,Toast 会带着完整的入场和计时器移动到最新剩余出口(spec:AST-003FR18、FR19)。 - FR14 — 触摸退场永不被移除;点按组件中由点按启动的退场播放主题的退场计时。 触摸呈现中的对话框或层表面会播放其组件记录在
spec:AST-094FR7 和 FR8 下规定的退场。在以点按为主要交互的组件中,触摸呈现中由点按、按键或程序启动的退场会播放主题的退场持续时间和缓动,即--duration-exit和--ease-exit;在手势组件(如 sheet 或 Lightbox)中,该退场从静止状态播放组件的弹簧,而手势驱动的退场保持其速度弹簧(spec:AST-094FR7、FR45)。退场开关不会改变该退场:让某一类别保持关闭的主题不会移除它,开启某一类别的主题也不会替换它。
平台支持¶
- 支持的功能与引擎基线:
browser-support使用方文档中的层级。 - 本节涵盖指针呈现;触摸退场遵循
spec:AST-094。 - Dialog 和 layer 退场在所有 Tier 1 和 Tier 2 浏览器中播放。
- 一个无法在顶层绘制其退场的 layer,例如缺少 Popover API 的环境,会立即关闭,无论其退场时长如何:这与退场关闭(exit off)的效果相同。
- 浏览器证据:在 Chromium 和 WebKit 中,对 dialog 退场和 layer 退场期间的帧进行真实浏览器采样,并对缺少 Popover API 的环境中的 layer 关闭进行采样。
当前状态影响¶
architecture:theme-tokens:--ease-exit、--duration-exit、--duration-exit-dialog和--duration-exit-layer加入规范词汇表,并附有其主题模板和生成的 token 文档投影(INV1、INV7)。architecture:layer-runtime:当请求关闭 layer 时,layer 即会关闭,与退场关闭(exit off)时一致;随后,其退场在运行时的共享退场副本上播放(INV14),并绘制在 layer 原先所在的顶层。原生关闭对账保持单次触发(INV6)。正在离开的 active 或 blocking 所有者会一直保留在关闭堆栈中的位置,直到其退场结束;但正在关闭的固定 Tooltip 除外,它会在退场开始时离开该堆栈(FR5)。正在离开的 Dialog 会持续提供其模态出口,直到其被隐藏(FR13);BottomSheet 的出口行为不变。architecture:component-style-authoring:无声明变更。layer 的退场是 INV7 所允许的那一个瞬态退场副本,由共享机制创建,并在退场结束时移除(FR9)。family:overlay-dismissal:无声明变更。正在离开的成员在 FR2 下保持存在,直到被隐藏;但正在关闭的固定 Tooltip 除外,它会在退场开始时离开堆栈(FR5);动画仍由成员持有(AV6)。spec:AST-003:无声明变更。正在离开的 surface 保持其交互角色(FR1);正在离开的被动依赖项(如未固定的Tooltip)仍然绝不会遮蔽所有者(FR4、DEC-1);正在关闭的固定Tooltip会在其退场开始时放弃 Escape(FR4、DEC-6)。正在离开的 dialog 仍是当前的原生模态框,因此它保留其出口,toast 在其上方保持可操作(FR16、FR18)。spec:AST-094:触摸呈现保留 FR7 和 FR8 赋予它的退场(FR14)。由点击、按键或程序启动的退场,在 tap 组件中播放--duration-exit和--ease-exit,在 gesture 组件中播放该组件的弹簧;由手势驱动的退场则保持其速度弹簧(spec:AST-094FR7、FR45、DEC-26)。spec:AST-108:无声明变更。其 FR2 在每个character上以相同的曲线接受--ease-exit;由弹簧驱动的退场播放其自身的退场角色,其旁的 CSS part 采用弹簧的稳定时间(FR3、FR4a);并且,作为对 tempo 缩放 token 的引用而设置的退场时长遵循tempo(FR5)。design:reduced-motion:无声明变更。在减少动态效果(reduced motion)下,指针呈现的退场立即完成(DR3、FR10);触摸呈现的退场通过spec:AST-094FR8 进行交叉淡化(DR2)。design:motion(草稿):退场应用 DR1、DR2 和 DR5。本记录保存其内容边界留给其他记录的退场 token 与行为。component:Dialog:其visibility概念(open、closed)增加了一个 leaving 阶段。在 dialog 退场开启时,调用方已关闭的 Dialog 会保持呈现,直到其退场结束;此期间其背后的页面保持 inert,toast 在其上方仍可操作(FR6、FR9、FR13)。AR2 保留其焦点返回声明;FR6 说明返回发生的时机。component:Popover:AR4 保留其焦点返回声明;FR6 说明 layer 的返回发生时机。component:BottomSheet:其指针呈现中的关闭采用--ease-exit。BottomSheet 是一个 gesture 组件:在触摸呈现中,由点击、按键或程序启动的关闭会从静止状态播放该 sheet 的弹簧;而关闭它的滑动或拖拽会保留自释放时测得的弹簧(spec:AST-094FR7、FR45)。实现差距:目前由点击或按键启动的粗指针关闭播放--duration-medium。- 使用方文档:
motion描述这两种曲线、指针呈现中退场默认关闭、主题如何开启每种类型、触摸退场永远不会被移除、tap 组件中由点击启动的退场播放主题的退场时序,以及 sheet 和 Lightbox 的触摸关闭弹簧(FR14);还描述了使用方在 surface 关闭期间保持内容渲染。token 表和主题模板列出新 token,每个成员组件的文档都描述其退场。
验证¶
| 契约 | 验证 | 代表性状态 | 变更或失败预期 |
|---|---|---|---|
| FR1 | 组件单元测试套件在默认 token 下无需更改即可运行 | 指针呈现中的每个 dialog 和 layer 成员,已打开和已关闭 | 使用默认 token 时,surface 在关闭后仍保持渲染 |
| FR2 | 在设置了一种类型的主题和精细主指针下进行真实浏览器测试 | 层关闭时对话框开启;对话框关闭时层开启;嵌套的 Theme |
未设置的类型会动画显示,或已设置的类型立即关闭 |
| FR3 | 退出过程中的真实浏览器帧采样 | 有和没有开启器的对话框、全屏对话框、每种放置位置的层、从右到左 | 表面偏离其进入路径,或保持进入曲线 |
| FR4 | 真实浏览器测试 | 在正在退出的表面内的控件上进行按下和 Enter 键操作 | 控件被激活 |
| FR5 | 关闭不变性测试 | 在正在退出的 Dialog 或 Popover 上按 Escape,其下方有拥有者;在 Dialog 上方正在退出的未固定 Tooltip 上按 Escape;在 Dialog 上方的固定 Tooltip 退出期间按 Escape | 正在退出的拥有者下方的拥有者关闭,正在退出的未固定 Tooltip 吸收按下事件,或正在关闭的固定 Tooltip 在其退出开始后接受一次 Escape |
| FR6 | 单元测试和真实浏览器的焦点与无障碍树测试 | 通过键盘和指针关闭 Dialog 和层;层退出期间的无障碍树 | Dialog 焦点在对话框隐藏之前返回,或落到 body 上;层焦点等待退出完成;正在退出的层的退出在无障碍树中 |
| FR7 | 单元测试 | 受控和非受控关闭 | 回调或 isOpen 等待退出完成 |
| FR8 | 单元测试和真实浏览器测试 | 退出期间重新打开、退出期间卸载、退出期间隐藏 Activity |
表面消失后又出现,或在卸载后仍然存在 |
| FR9 | 抑制结束事件的单元测试;页面范围内禁用动画和过渡的真实浏览器测试 | 在一次更新中打开和关闭;页面范围内 transition: none;没有结束事件 |
表面在其退出时长结束后仍存在超过 100ms |
| FR10 | 模拟减少动态的真实浏览器测试,精细主指针 | 每种类型均已开启 | 退出会播放 |
| FR11 | 退出过程中的真实浏览器帧采样 | 悬停卡片、带有打开的子菜单的菜单、带有搜索查询的选择器 | 正在退出的表面在被隐藏前显示其他内容,或不显示任何内容 |
| FR12 | Token 默认值测试、主题模板清单测试、Token 文档检查 | 默认值;BottomSheet 的关闭曲线 |
默认值偏离,或 BottomSheet 重新陈述该曲线 |
| FR13 | 真实浏览器测试 | 在对话框退出期间按下了一个 toast 操作,并关闭了一个 toast;对话框隐藏后同一个 toast 的状态 | 该 toast 在退出期间忽略输入或随对话框一起淡出,或在对话框隐藏时丢失其条目或计时器 |
| FR14 | 在 hydration 之后使用粗主指针的真实浏览器测试 | 一个 Dialog、一个 Popover 和一个菜单通过手指打开和关闭,每种类型都分别关闭再打开;同一组界面在减少动态效果模式下 | 某个开关改变了触摸退出;由轻触启动的触摸退出没有按照 --duration-exit 和 --ease-exit 播放;或者界面未按 spec:AST-094 FR7 和 FR8 所赋予的退出动画就关闭了 |
| Platform | Chromium 和 WebKit 中的真实浏览器测试 | 每种类型开启时的对话框退出和图层退出;缺少 Popover API 时的图层关闭 | 图层退出动画绘制到顶层之外或未播放,或在没有 Popover API 时关闭被延迟 |
决策日志¶
DEC-1 — 退出动画默认关闭,由主题开启¶
参考: spec:AST-090/DEC-1
决策者: cixzhang,2026-10-28
开启退出动画会同时改变每个产品中所有由指针呈现的对话框和图层的关闭方式,因此该能力默认关闭,由主题选择启用:也就是通过其运动比例尺调节运动的那一处。这些开关是 token,因为退出的时序是实现值,而不是每次调用的概念(spec:AST-002 FR3),也因为 prop 无法触达其他组件组合出的图层,例如每一个 tooltip prop。
已否决:在每个组件上增加一个 exit prop,这会在每个调用点重复声明时序并遗漏组合图层;退出动画默认开启,这会一次性改变所有覆盖层。
DEC-2 — 每种界面一个开关¶
参考: spec:AST-090/DEC-2
决策者: cixzhang,2026-10-28
用户会有意地关闭对话框,其退出动画展示出它揭示了什么。图层则在注意力转移时被关闭,常常一分钟许多次(design:motion DR2)。希望对话框以动画退出的主题,不必因此让每个 tooltip 和菜单都带动画。
已否决:所有界面共用一个开关。
DEC-3 — 退出动画沿加速曲线重走进入路径¶
参考: spec:AST-090/DEC-3
决策者: cixzhang,2026-10-28
动画退出会按照运动文档的要求沿进入路径返回。它使用自己的曲线:减速曲线在关闭的最初瞬间就走完行程,眼睛还来不及跟上;加速曲线则从静止开始移动并快速离开。BottomSheet 在这样曲线上关闭,--ease-exit 为其命名。
已否决:在 --ease-standard 上反向播放进入动画。
DEC-4 — 图层退出动画在图层绘制位置播放¶
参考: spec:AST-090/DEC-4
决策者: cixzhang,2026-10-28
浏览器在 Core 得知之前就把被轻关闭的图层隐藏了,因此图层的退出动画无法让活动图层保持打开。退出动画播放的是关闭开始时图层所显示的内容,绘制在图层原来所在位置的顶层;因为持续在顶层之外绘制的图层会画在错误的位置。
图层运行时共享的同一份退出副本会在所有支持 Popover API 的浏览器中把它绘制在那里(architecture:layer-runtime INV14、architecture:component-style-authoring INV7),因此图层退出动画可以在所有 Tier 1 和 Tier 2 浏览器中播放;在无法绘制的地方,图层会立即关闭,这也是默认行为。
已否决:通过 overlay 过渡将活动图层保留在顶层,这只能在支持该过渡的浏览器中播放。
DEC-5 — 触摸退出动画不会被移除;由 tap 启动的退出动画在 tap 组件中使用主题的退出时序¶
参考: spec:AST-090/DEC-5
决策者: cixzhang,2026-10-28
在触摸设备上,界面默认且无需选择启用,就保持其原生对应物的外观(spec:AST-094)。这一设定让主要交互是手势的组件获得弹簧运动,并让 tap 组件中由 tap 启动的运动在任何指针下都使用主题的 token(spec:AST-094 FR45)。这里的开关决定指针呈现的退出动画是否播放;而触摸呈现无论这些开关解析为何,都会保留其退出动画。在 tap 组件中,由 tap、按键或程序启动的触摸退出动画使用主题的退出时长和缓动,即 --duration-exit 和 --ease-exit;在手势组件中,它使用组件的弹簧,而由手势驱动的退出会保留其速度弹簧(spec:AST-094 FR45、DEC-26)。
已否决:让退出开关关闭触摸退出,这会移除 spec:AST-094 FR7 所要求的退出。
未决问题¶
- OQ1 — 指针呈现的对话框的退出是否默认开启,以及采用何种时长(
human-design)。选项:保持关闭;将--duration-exit-dialog默认设为var(--duration-exit);或默认采用进入区间的一个时长,因为有意关闭对话框的人会看着它消失。 - OQ2 — 页面流中的元素是否获得一种退出类型(
human-design)。FieldStatus和useEntryAnimation会通过动画进入,并在移除时消失。退出会让验证消息在离开期间保留在布局中,而design:motionDR4 对此持反对意见。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx