跳转至

覆盖层关闭家族契约

{
  "scope": "global",
  "triggers": {
    "layering": ["FR1", "FR2", "FR3", "FR6"]
  },
  "concerns": {
    "focus-return": {
      "names": [
        "focusForLastInput",
        "isFocusDetached",
        "useFocusReturnVisibility"
      ],
      "claims": ["FR9"]
    }
  }
}

意图

用户关闭分层 UI 时,应只影响最顶层的相关表面。当逻辑深度或 DOM 包含关系确立了顺序时,嵌套表面不得在同一个 Escape 按键或平台关闭请求上关闭其宿主。在页面中,由触发器锚定的成员在关闭时会将焦点返回到其被打开的文档;当它渲染在同源 iframe 或 Picture-in-Picture 窗口中时,会在该处关闭并同样将焦点返回到其被打开的文档;BottomSheet、BottomSheetSwitcher 和 Lightbox 仅在 Picture-in-Picture 窗口中如此,而 Drawer 和 MobileNav 始终留在页面中。

成员规则

当一个组件拥有一个分层表面,且 Escape 或平台关闭请求是该表面的有效关闭命令时,该组件即属于成员。只要该表面存在,每个成员都必须参与共享关闭栈。成员资格遵循可观察的责任,而非当前实现是否已完成采用;本地 Escape 监听器是需要迁移的偏差,而非有意排除。

一个组件如果使用 usePopover、useLayer、焦点陷阱或原生对话框创建自己的弹出层,并且拥有该弹出层的关闭行为,则该组件就是成员。仅将另一个成员作为辅助内容组合进来的组件,会继承该成员的行为,但不因此加入。成员资格是开放式的:每个新发布且符合此规则的表面都必须加入共享栈,且本记录的当前成员快照必须随之更新。

  • 当前成员: Dialog、AlertDialog、Popover、DropdownMenu、DropdownMenuSubMenu、MoreMenu、Tooltip、HoverCard、Lightbox、MobileNav、BottomSheet、BottomSheetSwitcher、CommandPalette、ContextMenu、PowerSearchEditPopover、Drawer,以及下面列出的组件自有弹出层表面。
  • 组件自有的输入弹出层: ChatComposerInput、ComplexSelector、DateInput、DateRangeInput、DateTimeInput、Selector、MultiSelector、PowerSearch、BaseTypeahead、Typeahead 和 Tokenizer。TextInput、TextArea、NumberInput、TimeInput 和 FileInput 不拥有弹出层;为辅助文本或禁用文本渲染 Tooltip 并不会使输入组件本身成为成员。
  • 其他组件自有的弹出层: BreadcrumbItem、SideNavHeading、SideNavItem、TabMenu、TopNavHeading、TopNavMenu、TopNavMegaMenu、表格筛选、List 的重排模式提示、Lab TourStep 和 Lab ChatEmojiPicker。
  • Hook 自有的提示: useKeyboardHint 提示,由 Toolbar、TabList 和 SegmentedControl 渲染。
  • 协作者: useLayerDismissal、layerStack、LayerDepthProvider 和 useFocusTrap 拥有或适配共享协议。
  • 不参与的层: 没有关闭行为的层不是成员。仅通过 Layer 渲染的视觉轮廓就是典型示例:它既不处理 Escape,也不会收到平台关闭请求。

共享所有者

  • useLayerDismissal 注册活动表面,并将浏览器发起的关闭请求适配到共享的最顶层检查。
  • layerStack 负责存在过滤、排序以及文档级 Escape 监听器:在每一个持有已注册成员的文档中都有一个监听器(FR8)。
  • LayerDepthProvider 通过 React 树传递逻辑嵌套,供成员将其提供给后代。没有该提供器的成员,在后代内容脱离 DOM 包含关系后,不保证嵌套顺序。
  • 当 useFocusTrap 处于活动状态并接收 onEscape 回调时,它会加入同一栈。没有 onEscape 的焦点陷阱不是可关闭表面,也不会注册。

规范概念

概念 值或状态 默认语义 稳定性
成员资格 成员或不参与 具有 Escape/平台关闭行为的表面即为成员 当前
采用 共享、部分或本地 本地处理是需要迁移的偏差,而不是成员资格例外 当前
注册 活动或不活动 只有活动且启用的表面才参与 当前
存在 存在或不存在 不存在的已注册表面会被跳过 当前
Escape 行为 close 或 block close 调用成员的关闭回调;block 消费该请求但不关闭 当前
逻辑深度 非负嵌套层级 提供器将后代表面标记为比其宿主更深 当前
关闭请求 Escape 或平台请求 最顶层的已注册存在成员决定结果 当前

跨组件不变量

  • FR1 — 每个可关闭的分层表面都参与。 成员在存在期间必须加入共享关闭栈。组件特定的 Escape 监听器或注册表不满足此不变量。
  • FR2 — 一次请求只影响一个表面。 未被认领的 Escape 按键会被路由到恰好一个最顶层的已注册存在成员。该成员要么调用其关闭回调,要么阻止该请求;该请求不会继续传递到其后面的成员。
  • FR3 — 平台关闭请求使用同样的最顶层规则。 成员收到浏览器或平台关闭请求时,仅当它是最顶层的已注册存在成员时才关闭。针对较低层成员的请求会被拒绝。
  • FR4 — 可用的嵌套信号优先于宿主位置。 当成员提供 LayerDepthProvider 时,React 树深度会将其后代层排在成员之前,即使两者在同一提交中挂载。DOM 包含关系可以解决同深度的嵌套;稳定的活动周期注册顺序可以解决无关表面。没有该提供器的成员,对于不再被 DOM 包含的后代内容,不保证此顺序。
  • FR5 — 内容可以先认领 Escape。 共享监听器在冒泡阶段运行,当内容已经处理了事件时,它会退出。
  • FR6 — 文本组合不是层关闭。 用于取消活动 IME 组合的 Escape 会被消费而不关闭成员,且在组合活动期间,平台关闭请求会被拒绝。
  • FR7 — 注册不定义打开状态的所有权。 栈调用所选成员的关闭回调。该请求是否立即关闭表面,由成员的组件契约和调用者决定。
  • FR8 — 成员在其渲染所在的文档中工作。 成员在其注册元素所在的文档中打开并接收 Escape 和平台关闭请求,也就是它渲染的位置:Dialog(以及经由它的 AlertDialog 和 CommandPalette)、Lightbox、MobileNav、BottomSheet、BottomSheetSwitcher 和 Drawer 注册其对话框,ContextMenu 注册其菜单,焦点陷阱注册其容器。由触发器锚定的成员、Dialog、Popover 以及所有基于 Popover 构建的成员、DropdownMenu、ContextMenu、Tooltip 和 HoverCard,渲染在页面、同源 iframe 或 Document Picture-in-Picture 窗口中。BottomSheet、BottomSheetSwitcher 和 Lightbox 覆盖它们渲染所在的窗口,并且在页面和 Picture-in-Picture 窗口中工作,而不是在嵌入式 iframe 内部。Drawer 和 MobileNav 是页面级的,并且只在页面的文档中工作。Escape 按键或平台关闭请求仅在其到达的文档中已注册存在的成员之间参与排序,且 FR2 和 FR3 在该文档内适用,因此宿主及其内部嵌套的成员无论渲染在哪里都保持一个顺序。属于另一个文档的成员永远不会成为候选。未固定的 Tooltip 永远不会在与另一个成员的 Escape 按键竞争中获胜或阻止它;通过按键固定为打开的 Tooltip 会优先接收 Escape(spec:AST-003 FR4、DEC-6):Escape 仅在未固定 Tooltip 是其所在文档中唯一存在成员时才关闭它。该栈在每个持有一个成员的文档中只监听一次,并在最后一个成员离开时停止。
  • FR9 — 焦点返回到打开者的文档。 关闭触发器锚定成员时,如果焦点在其他情况下会丢失,焦点将返回到该成员在打开者文档中的返回目标,并带有该文档中最后一次输入所要求的焦点环(architecture:interaction-modality INV1);BottomSheet、BottomSheetSwitcher 或 Lightbox 在 Picture-in-Picture 窗口中也如此。返回操作不会将页面或任何滚动容器滚动到返回目标。浏览器可能会将按下控件的一个可聚焦祖先记录为返回目标(WebKit 会聚焦被点击按钮的最近可聚焦祖先,例如 tabindex="-1" 的主区域);显示该祖先会将页面滚动到其顶部边缘。

  • FR10 — 背景按下在背景上开始和结束。 使用 purpose="info" 的 Dialog、Drawer 的遮罩层,以及通过其 Dialog 实现的 CommandPalette,仅当按下操作既在背景上开始又在背景上结束时,才通过背景按下关闭。按下操作无论从哪个方向越过成员边缘,例如文本选择或滑块拖动到边缘外释放,都不会将其关闭;已取消的指针会结束该按下。此规则对鼠标、笔和手指相同,并且这些成员共享同一实现。

  • FR11 — 最顶层表面消费其外部按下。 关闭最顶层表面的外部按下会被该表面消费;其下方的宿主表面不会在同一次按下中也被关闭。背景按下关闭在 Dialog(purpose="info")、带遮罩层的 Drawer 或 CommandPalette 内部打开的层(菜单、弹出框、组合框列表、日期日历、固定 Tooltip 或上下文菜单)时,宿主保持打开,下一次背景按下才关闭宿主。自行隐藏的层(例如其触发器失去焦点的 Tooltip)不会消费该按下。仅关闭该层的按下会将焦点留在宿主内:要么位于被关闭层返回焦点的地方,要么位于宿主本身。此规则对鼠标、笔和手指相同。

允许的组件变体

  • AV1 — 焦点。 成员自行决定焦点进入、包含、移动和返回目标。FR9 规定文档焦点返回的目标,并规定返回时不发生滚动。
  • AV2 — 模态性。 成员可以是模态或非模态,并自行决定任何 inert 或背景行为。
  • AV3 — 定位与宿主。 成员可以使用原生 dialog 定位、CSS 锚点定位、固定坐标或组件自有的宿主。
  • AV4 — 外部关闭。 成员自行决定指针、悬停、失焦、背景、触摸或手势交互是否以及如何关闭它们;FR10 所指成员的背景按下遵循 FR10 和 FR11。
  • AV5 — 开启状态 API。 成员自行决定受控和非受控状态、默认值、回调名称和命令式命令。
  • AV6 — 呈现。 成员自行决定动画、视觉处理和主题样式结构。关闭注册表不暴露主题目标或渲染后的包装器。

代表性矩阵

成员与状态 共享不变量 有意变体
Dialog 内的 Dialog 内层 Dialog 处理第一次请求 Dialog 提供原生模态性和焦点行为
Dialog 内的 Popover Popover 处理第一次 Escape Popover 提供锚定、Portal 放置和焦点策略
CommandPalette 内的已注册后代 后代处理第一次 Escape CommandPalette 继承 Dialog 的共享栈参与
页面中 Dialog 内的 Tooltip 或 HoverCard 打开的 HoverCard 处理第一次 Escape;Dialog 优先于未固定的 Tooltip 处理它;固定 Tooltip 则最先处理 Hover 组件族自行决定它们何时出现以及受控状态如何响应
必需 Dialog 之上的 Lightbox 或 MobileNav 最顶层成员处理请求 必需 Dialog 仅在其为最顶层时使用 block
单独的必需 Dialog 请求被消费但不关闭 Dialog 的 purpose 选择 block 行为
输入组件自有的弹出层 弹出层存在时参与 输入组件拥有选择、焦点、开启状态、定位和外部关闭
两个无关的已注册表面 活动周期中较晚的注册位于最顶层 两个表面都不被视为嵌套
发送到下层 Dialog 的平台关闭请求 下层 Dialog 保持打开 平台以宿主为目标;共享检查决定其是否可以关闭
iframe 中的 Popover,页面中的 Dialog 请求发送到其自身文档的最顶层成员 应用通过 portal 渲染到第二个文档中
iframe 中 Dialog 内的 Popover Popover 处理该 iframe 的第一次请求 两者都注册自己的元素,因此它们按 iframe 中的顺序排列
iframe 中 Dialog 内的 Tooltip 或 HoverCard 打开的 HoverCard 在那里处理第一次 Escape;在未固定的 Tooltip 上时,Dialog 处理它;固定的 Tooltip 首先处理它 未固定的 Tooltip 绝不会赢得或阻止其他成员的 Escape;固定的 Tooltip 首先处理它(spec:AST-003 FR4、DEC-6)
画中画窗口中的 ContextMenu Escape 关闭它;焦点在那里返回到其 opener 菜单在用户按下的位置打开(FR8、FR9)
画中画窗口中的 BottomSheet 或 Lightbox Escape 关闭它;焦点在那里返回到其返回目标 该 surface 覆盖该窗口(FR8、FR9)
嵌入式 iframe 中的 BottomSheet 或 Lightbox 不支持 覆盖其窗口的 surface 仅在该窗口就是应用本身时才有效(FR8)
Drawer 或 MobileNav 仅页面级 页面级 surface 保留在页面的 document 中(FR8)

采用与例外情况

组件或 surface 采用情况 当前的偏差或限制
Dialog、AlertDialog、Popover、MobileNav、Drawer、CommandPalette 共享 owner;CommandPalette 组合 Dialog 无
Tooltip、HoverCard 共享 owner,并带有 DOM 存在性报告 两者都没有为后代层提供嵌套深度。实现缺口:当 Tooltip 是最顶层 layer 时,它会消耗 Escape,因此其下方的 layer 在该次按键时保持打开;另一个 document 中的 Tooltip 永远不会被 Escape 关闭(component:Tooltip FR6);FR8 将该次按键交给下方的 layer,并关闭其自身 document 中孤立的 Tooltip。通过 useTooltip 的 show()(如 InfoTip 上的按键那样)被按键固定打开的 Tooltip 会首先处理 Escape(spec:AST-003 FR4、DEC-6;component:Tooltip FR9、FR12);HoverCard 没有按键固定。
带 onEscape 的焦点陷阱 通过 useFocusTrap 共享属主 它们提供 DOM 包含,而非后代层级深度
BreadcrumbItem, ChatComposerInput, ComplexSelector, DateInput, DateRangeInput, DateTimeInput, Selector, MultiSelector, PowerSearch, BaseTypeahead, Typeahead, Tokenizer, SideNavHeading, SideNavItem, TabMenu, TopNavHeading, TopNavMenu, TopNavMegaMenu, Table, Lab ChatEmojiPicker 通过 usePopover 或组合的 Popover 属主共享属主 Table 过滤功能拥有受控的 Popover 状态,并在关闭时丢弃其草稿;ChatEmojiPicker 拥有受控的 Popover 状态
Lab TourStep 通过其上下文层级上的 useLayerDismissal 共享属主 按 Escape 会结束导览;没有背景遮罩时,该步骤无法通过外部点击关闭;有背景遮罩时,点击提示框外部会以 'backdrop' 结束导览(component:Tour FR1)
DropdownMenu root, MoreMenu, ContextMenu, Selector, MultiSelector, TopNavHeading, TopNavMenu, TopNavMegaMenu, SideNavHeading, SideNavItem, BottomSheet, BottomSheetSwitcher, Lightbox 共享属主 实现缺口:在另一个文档中(对于 BottomSheet、BottomSheetSwitcher 和 Lightbox,即画中画窗口),每个组件都会在页面文档和最后输入之间决定焦点返回,因此焦点可能返回到 frame 元素或页面,或在没有焦点环时聚焦到其文档所要求的最后输入(FR9)
List 的重排模式提示 共享属主,在重排模式开启时注册 无
DropdownMenuSubMenu, PowerSearchEditPopover 仅本地 必须从组件特定的监听器或注册表迁移到共享所有者

标记为 partial(部分)或 local(本地)的行是相对 FR1 而言的当前采用差距,而标注为实现差距的行是相对 FR8 或 FR9 而言的差距。它们并非经批准的例外。所列出的实现差距是已知差距,而非完整清单:一位成员发现,决定焦点返回或处理页面 document 中的 Escape 属于同一已知差距。迁移必须保留每个组件现有的焦点、模态、定位、外部关闭和打开状态契约。

验证映射

契约 验证 代表性成员和状态 变更或失败预期
FR1, FR2, FR4, FR5 useLayerDismissal.test.tsx; BottomSheetSwitcher.test.tsx; ContextMenu.test.tsx; CommandPalette.test.tsx 合成 provider 深度、同 DOM 包含关系、非模态切换器嵌套、ContextMenu 嵌套层、CommandPalette 后代嵌套、无关、阻塞、内容已处理、存在/缺失 移除深度、存在性过滤或事件延迟会将 Escape 发送至错误的界面
FR2, FR3, FR4, FR6 layerDismissalInvariants.test.tsx 嵌套的同 DOM Dialog、覆盖 Dialog 的 Lightbox、BottomSheet 中的 Dialog、平台取消、IME 一次请求关闭两个界面、先于子层关闭宿主,或在组合期间关闭
FR1, FR2, FR3, FR7 layerDismissalFamilies.test.tsx Dialog、Lightbox、MobileNav、BottomSheet、Tooltip、HoverCard;受控状态和阻塞状态 某个组件族绕过堆栈、下层成员处理请求,或受控所属关系被忽略
FR1 useFocusTrap.test.tsx 激活、嵌套和已停用的焦点陷阱,带 onEscape 一个可关闭的焦点陷阱未加入共享堆栈,或嵌套的陷阱会一起响应
FR1, FR2 ListReorder.test.tsx List 的重排模式提示持有焦点,并位于一个已打开的层之上 Escape 穿透到下方的层,或重排模式在按下 Escape 后仍然存在
FR8 useLayerDismissal.test.tsx; Popover.test.tsx 页面中的层成员和同源 iframe 中的层成员;一个 Popover 单独存在以及位于 Dialog 内部,均在 iframe 中 在一个文档中的按下操作会关闭另一个文档中的成员,或宿主会关闭其嵌套层
FR8 PopoverSecondDocument.a11y.chromium.spec.ts 位于 iframe 中的 Popover 和位于画中画窗口中的 Popover,单独存在,或页面中也有一个打开的 Popover 在第二个文档中的按下操作未命中自身的层,或关闭了页面中的层
FR9 DialogSecondDocument.a11y.browser.spec.ts 位于 iframe 中的 Dialog 和位于画中画窗口中的 Dialog,通过 Escape 或其内部控件关闭;以及一个从页面打开的、位于 iframe 中的 Dialog 焦点落在打开者的文档之外,或其焦点环未跟随关闭输入
FR9 BottomSheetCloseScroll.a11y.browser.spec.ts; DialogCloseScroll.a11y.browser.spec.ts 一个 BottomSheet 和一个 Dialog,其触发器位于已滚动页面中一个很高的可聚焦区域内,分别通过内部控件、背景遮罩和 Escape 关闭,在 Chromium 和 WebKit 中运行 页面滚动偏移量或触发器在屏幕上的位置在关闭过程中发生变化
FR8, FR9 真实浏览器第二文档检查;实现差距:只有 Dialog、Popover 和 HoverCard 具备这些检查 Dialog、Popover、DropdownMenu、MoreMenu、ContextMenu、Selector、MultiSelector、TopNavHeading、TopNavMenu、TopNavMegaMenu、SideNavHeading、SideNavItem、Tooltip 和 HoverCard,各自在同源 iframe 和画中画窗口中:在其渲染所在的文档中打开并接收 Escape(未固定的 Tooltip 仅在不存在其他成员时;固定的 Tooltip 则在其下方成员之前),并将焦点返回打开者所在文档 成员在另一个文档中打开或参与层级排序,固定的 Tooltip 让 Escape 到达其下方的成员,或焦点落在 frame 元素、页面或 body 上
FR8, FR9 真实浏览器第二文档检查;实现差距:这些组件均无此类检查 BottomSheet、BottomSheetSwitcher 和 Lightbox 在画中画窗口中:打开,接收 Escape,并将焦点返回到该窗口中的返回目标 该表面在页面中参与层级排序,或焦点落在页面或 body 上
FR8 对 Drawer 和 MobileNav 的源码检查 Drawer 和 MobileNav 由第二个文档中的控件渲染 页面级表面移入第二个文档
FR10 useBackdropPress.test.tsx;BackdropPress.a11y.chromium.spec.ts Dialog(purpose="info")、Drawer 遮罩和 CommandPalette,使用鼠标和手指:一次在背景遮罩上开始并结束的按压,一次在内部开始并在背景遮罩上结束的按压,一次在背景遮罩上开始并在内部结束的按压,一次被取消的指针,以及先按在背景遮罩上、随后在内部按下的操作 按压无论从哪个方向越过边缘都会关闭,被取消或更早的按压会延续,或仅在背景遮罩上的按压不会关闭
FR11 useBackdropPress.test.tsx;BackdropPress.a11y.chromium.spec.ts Dialog(purpose="info")和 Drawer 遮罩,内部打开有菜单,使用鼠标和手指:先按一次背景遮罩,然后再按一次;一个 Dialog,其内部打开有 Typeahead 列表、DateInput 日历、固定的 InfoTip 或 ContextMenu,使用鼠标;一个 DateTimeInput 时间列表,其字段在 mousedown 时失焦;在 tooltip 自行隐藏时的一次按压;一次不关闭任何上层的按压 一次关闭菜单的按压也关闭宿主,或第二次按压让宿主保持打开

DEC-1 — 成员资格遵循关闭责任

决策者: cixzhang, 2026-08-30

每一个分层表面,只要 Escape 或平台关闭请求是有效的关闭命令,就属于该家族,并且必须参与共享堆栈。成员资格是开放式的:每个新发布且符合此规则的表面都必须加入堆栈。现有的组件本地监听器和注册表是采用差距,而非有意排除。拥有自己的输入弹出层的组件是成员;仅将另一个成员作为辅助内容组合的组件,则不因此成为成员。成员元数据和采用表是经审计的当前快照,而非封闭集合。

没有关闭行为的层不参与。通过 Layer 渲染的纯视觉轮廓是典型的不参与示例。

DEC-2 — 每个浮层在其所属的文档中工作

决策者: cixzhang,2026-10-31

一次按键和一次平台关闭请求只到达其发生所在的文档,每个文档保留自己的浏览器顶层(top layer)以及自己的焦点。因此,成员在其渲染所在的文档中打开并排序,并在其打开者的文档中归还焦点。由触发器锚定的成员渲染在页面、同源 iframe 或画中画(Picture-in-Picture)窗口中。覆盖窗口的浮层——BottomSheet、BottomSheetSwitcher 或 Lightbox——在窗口即应用的场景下工作:页面或画中画窗口,而非内嵌 iframe。页面级浮层停留在页面中。一次请求仍然只影响恰好一个浮层:即用户操作所在文档中最顶层的那个浮层。

已否决:跨文档的单一顺序,即在一个窗口中的按键会关闭另一个窗口中的浮层。

开放问题

无。焦点进入、包含关系、移动、返回目标、模态性、定位、外部关闭以及打开状态 API 均属于该家族契约之外;FR9 仅规定焦点返回所在的文档,并规定返回不触发滚动。已映射的测试并未通过真实 portal 渲染嵌套层;在真实 portal fixture 就绪之前,本契约不能声称已验证 portal 覆盖。

内容边界

本文件拥有家族成员关系、最顶层已注册的 Escape 与平台关闭行为,以及当前用于对这些请求排序的逻辑深度与 DOM 包含关系信号。成员仅在提供 LayerDepthProvider 时才保证后代深度;本记录不声称已通过真实 portal 验证嵌套。它拥有成员打开、关闭并归还焦点的文档(FR8、FR9)。它不定义焦点进入、包含关系、移动、返回目标、模态性、定位或锚定、portal 放置、外部交互、程序化组件命令、打开状态 API、动画或主题化。这些仍属于组件、家族或架构的职责。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx