跳转至

图层协调与全局托管系统规范

{
  "scope": "global",
  "triggers": {
    "layering": ["FR4", "FR10", "DEC-1", "DEC-2", "DEC-3", "DEC-5", "DEC-6"]
  }
}

意图

让每一次分层交互都关闭预期的所有者或交互分支,不会出现瞬时表面遮蔽它,或一次指针手势将其关闭后又重新打开的情况。选定的应用全局系统必须通过浏览器有效的原生托管,在原生模态对话框之上保持可见且可操作。

完整的锚定层契约还必须如实说明其平台依赖性:原生 Popover API 加 CSS Anchor Positioning 提供完整行为;不受支持的浏览器获得可用的降级回退方案,而非等价行为。

非目标

  • 让每一层都能通过所有通道关闭。
  • 取代组件自有的焦点、模态性、外部关闭策略、背景遮罩、滑动阈值、悬停时序、打开状态 API、动画或视觉处理。
  • 为每个浮层提供全局或模态上层模式。
  • 用旧式定位和关闭 polyfill 取代原生 Popover 和 CSS Anchor Positioning。
  • 仅为暴露内部所有者、分支或手势记账而更改公共 API。

需求

交互所有权与关联

  • FR1 — 协调机制对交互角色进行建模。 已注册的表面可以是主动关闭所有者、阻塞所有者或被动依赖项。仅具有视觉效果的表面不注册为交互所有者。
  • FR2 — 主动所有者可以执行关闭。 主动所有者拥有任务或交互状态,并在所选通道参与时调用其组件自有的关闭行为。
  • FR3 — 阻塞所有者消耗通道而不关闭。 阻塞所有者阻止通道到达其后的所有者。Required Dialog 是 Escape/平台场景的典型代表。
  • FR4 — 被动依赖项永远不会遮蔽所有者。 未固定的 Tooltip 是被动依赖项。它不会赢得或阻止关闭,并且当其关联的所有者或触发器交互关闭时,它会随之消失。通过 useTooltip 的 show() 以按压方式固定打开的 Tooltip(component:Tooltip FR9、FR12),就像按压 component:InfoTip 所做的那样,是主动所有者:它优先接收 Escape 并关闭,而其下方的所有者在该次按压期间保持打开(DEC-6)。
  • FR5 — 关联是显式的。 每个主动或阻塞所有者都记录一个可选的父所有者和一个交互分支根。被动依赖项记录其关联的所有者或触发器,而不创建所有者节点或分支边界。

通道特定仲裁

  • FR6 — Escape 和平台关闭会选择一位符合条件的所有者。 每次只选一个的通道会选择与其关联的、层级最高的、且其组件策略参与的主动或阻塞所有者。主动所有者关闭,阻塞所有者消耗,被动和仅视觉表面被跳过。
  • FR7 — 外部交互解析分支。 外部交互根据所有者表面、关联的触发器或调用者以及分支关系进行评估。它不会复用视觉或注册顺序的顶层。
  • FR8 — 级联菜单作为一个分支整体关闭。 DropdownMenu 及其打开的浮出子菜单共享一个分支根。在该分支根之外进行的交互会关闭根及其每个打开的子菜单。
  • FR9 — 嵌套子分支可以独立关闭。 一个不同的嵌套 Popover 创建子分支。在父分支内部但在子分支外部的交互仅关闭子分支;在两个分支外部的交互则根据组件策略解析两个受影响的分支。
  • FR10 — 组件策略保留在组件中。 共享协调确定符合条件的所有者或受影响的分支。拥有该通道的组件或组件族决定该通道是关闭、阻塞还是传递。

同一交互保护

  • FR11 — 指针关闭在关闭前认领该交互。 每条可能与关联触发器冲突的指针驱动外部、轻触关闭、背景遮罩、触摸或滑动路径,都会在可见性改变之前记录分支认领。
  • FR12 — 每条重开路径都遵守该认领。 关联触发器、原生调用者、show() 和切换路径都会拒绝同一次物理手势。后续手势可以重新打开。
  • FR13 — 浏览器事件顺序无关紧要。 无论原生关闭是在点击之前还是之后被观察到,认领都有效。时间戳窗口不能替代手势身份。
  • FR14 — 菜单悬停抑制暴露引发的悬停。 当关闭中的面板暴露一个静止触发器时,由此产生的合成 mouseenter 不会重新打开分支。真正的离开和之后的悬停可以再次打开它。

选定全局系统的原生托管

  • FR15 — 全局准入是显式的。 系统只能通过经所有者批准的 architecture:layer-runtime 更新获得模态层之上的全局托管。普通的触发器关联或任务关联浮层保持本地。
  • FR16 — Toast 采用全局托管。 ToastViewport 在当前原生模态之上保持可见且可操作。Toast 在图层关闭中保持被动:Escape/平台仲裁会跳过它,自动隐藏、显式控件或直接滑动 Toast 仅关闭该 Toast。
  • FR17 — CommandPalette 在启动器模式下是全局主动所有者。 普通 CommandPalette 使用后续的原生模态宿主,并在先前的模态之上形成一个主动交互分支。isInline 预览不是全局的,也不是模态的。
  • FR18 — 原生模态祖先链提供被动全局托管。 应用有一个根全局出口,每个活动中的原生模态在其 DOM 中提供一个出口。被动全局宿主渲染到最新的活动模态出口中,当没有模态活动时回退到根出口。普通的 body 传送门或 z-index 是不够的。
  • FR19 — 全局状态在重新托管中存续。 Toast 分发、可见条目、计时器、焦点交接和碰撞状态都位于所选出口之上,因此模态的打开或关闭不会重置它们。
  • FR20 — 当前不符合条件的系统保持本地。 Banner 和 FieldStatus 保持在文档流中;useAnnounce 保持非视觉;AlertDialog、命令式 Dialog、Lightbox 和普通 Popover 家族表面保持任务或触发器关联。

锚定层支持要求

  • FR21 — 原生特性定义完整的锚定行为。受支持的原生 Popover API 与 CSS Anchor Positioning 提供顶层提升、原生轻触关闭、自动 Popover 关联、逻辑锚点几何以及碰撞回退。
  • FR22 — 不支持的浏览器获得可用的简化回退。显式控件仍可显示和隐藏已挂载内容,回调与 React 状态照常更新,固定坐标也适用。回退方案不要求复现原生顶层、外部关闭、关闭请求、自动堆叠、调用方焦点顺序、锚点几何或碰撞行为。
  • FR23 — 公共文档说明边界。useLayer、Popover 及相关组件文档应区分完整原生行为与简化回退行为,而不将回退称为等效行为。

实现要求

  • IR1 — 协调暴露两种操作。共享基础设施为一次一个(one-at-a-time)通道提供合格所有者解析器,为外部交互提供关联分支解析器。单个通用 isTopmost 操作无法同时实现这两份契约。
  • IR2 — 分支身份可复用。DropdownMenu 子菜单上下文将其现有的根级关闭链投射到共享分支身份中。独立的嵌套 Popover 会创建子分支,而不是意外加入菜单级联。
  • IR3 — 手势声明扩展现有所有者。分支声明基于 gestureCounter 构建,而不是引入每个组件独立的时间戳启发式。
  • IR4 — 原生全局出口是窄基础设施。全局出口选择不会成为 Layer 或 Popover 上的公共 global prop。
  • IR5 — 运行时行为变更保持原子性。合格性、分支协调、手势声明、全局托管和支持文档可以作为独立变更发布,同时保留这一已接受的契约。

平台支持

  • 受支持的特性/引擎下限:在 Astryx 发布的浏览器矩阵支持原生 Popover API 和 CSS Anchor Positioning 的环境中,完整契约适用。
  • 不支持的行为:低于该特性下限的浏览器仅获得 FR22。原生模态 Dialog 行为仍受支持的对话框下限约束。
  • 浏览器证据:原生轻触关闭、调用方行为、顶层顺序、焦点/惰性、模态出口和锚点几何需要真实的 Chromium 和 WebKit。Playwright WebKit 不能作为 Safari 特定行为的证据。

当前状态影响

当前 main 并未完全满足本规范:

  • 栈具有 close 和 block,但没有被动角色;Tooltip 目前会在关联所有者之前消费 Escape;
  • 不存在共享的所有者/分支关联图或外部分支解析器;
  • DropdownMenuSubMenu 有本地父级关闭链,但外部通道不消费共享分支身份;
  • 原生轻触关闭具有手势记忆,菜单悬停具有重新悬停抑制,但本地背景遮罩、触摸、滑动和手动外部路径不共享分支声明;
  • body/root 上的 Toast 宿主仍位于活动原生模态对话框之后;
  • Toast 状态存在于 ToastViewport 内部,而不是位于可移动出口之上;
  • CommandPalette 使用原生 Dialog,但在本地处理 Escape;以及
  • 简化回退行为已在代码中实现,但未在公共文档中完整描述。

迁移与采用计划

  1. 所有者与分支模型。扩展层注册,加入活动、阻塞和被动角色,以及父所有者与分支根关联。添加纯合格所有者与外部分支解析器。在迁移期间,保留现有活动/阻塞成员的当前 Escape/平台契约。
  2. 合格性迁移。使未固定的 Tooltip 变为被动,固定的 Tooltip 变为活动,并更新 Tooltip-over-owner 测试。保持 HoverCard 为活动,因为它可以拥有交互内容。将 CommandPalette 和由 family:overlay-dismissal 跟踪的本地 Escape 实现迁移到合格所有者投递。
  3. 分支迁移。将 DropdownMenuContext 的根/子菜单链投射到共享分支中。为嵌套的 Popover 添加独立子分支。迁移原生自动轻触关闭、ContextMenu 外部按下、对话框背景遮罩、触摸,以及 sheet 滑动/遮罩(scrim)通道,同时不改变它们各自的组件策略。
  4. 手势声明。将当前 Layer 的关闭记忆泛化为分支声明,在指针驱动的关闭之前记录。要求每个关联的重新打开路径都查询该声明。保留菜单悬停的曝光抑制。
  5. 全局原生宿主。添加具有激活顺序的根出口和模态出口。将 Toast 状态提升到渲染出口之上,将 Toast 的 manual-popover 视口渲染到所选出口内,并在重新托管时保留状态。保持 CommandPalette 使用原生 Dialog,并将其验证为后续的活动模态所有者。
  6. 支持说明。使用完整的原生契约和简化回退更新公共 Layer/Popover/组件文档。添加下文要求的浏览器矩阵。
  7. 架构提升。随着每项要求发布,将 architecture:layer-runtime 从观察到的差距更新为已发布的固定不变量。只有在所有完成标准均满足后,才将本规范移至 shipped。

默认情况下,任何迁移步骤都不会添加宽泛的公共 API。新的公共 prop 或 hook 仍须遵循 architecture:public-component-api 和 spec:AST-002。交互模态继续遵循 architecture:interaction-modality。

验证

契约 验证 代表性状态 变异或失败预期
FR1–FR6 纯注册表/解析器测试,以及家族交互测试 active、blocking、passive Tooltip、固定(pinned)Tooltip 覆盖在 Dialog 之上、纯视觉、受控属主 passive 表面获胜、固定表面让 Escape 穿透到底层属主、blocker 泄漏、或错误属主被关闭
FR7–FR10 分支解析器测试和真实浏览器外部交互测试 带两个子菜单层级的根菜单;父级 + 子级 Popover;关联触发器 外部点击根菜单时子菜单仍打开,或仅在子级外部点击却关闭了父级
FR11–FR14 手势计数器和浏览器事件顺序测试 原生 light dismiss 在点击之前/之后;菜单按钮;悬停打开;触摸;背景遮罩;滑动 同一手势重新打开任何关联触发器,或暴露的悬停重新打开面板
FR11–FR13 手势计数器测试;真实 Chromium 上下文菜单按下测试 从 contextmenu 打开的 layer 和 DropdownMenu;在区域内/外释放 打开该 layer 的按下操作在释放时将其关闭,或后续按下操作未将其关闭
FR15–FR20 Chromium/WebKit 原生宿主测试 Toast 位于根层;Toast 穿过一层/两层 modal;CommandPalette 位于 modal 之上;普通局部 Popover 全局表面位于底层/被惰性化、丢失状态,或普通覆盖层变成了全局
FR21–FR23 受支持/不受支持的浏览器矩阵和公开文档检查 anchor/fixed/custom;auto/manual;显式控件;缺失的功能 API 文档承诺等价能力或降级 fallback 不可用
IR1–IR3 API/类型测试以及针对解析器/声明的变更测试 单通道(one-at-a-time)与分支通道 最顶部的一次查询被复用于外部点击分支,或时间戳替代了身份标识
IR4, IR5 公开表面快照和原子变更审查 局部 Popover、全局 Toast、全局 CommandPalette 出现通用全局 prop,或无关行为在一次变更中被耦合

完成标准

本规范仅在以下条件全部满足时才算完整:

  • 未固定的 Tooltip 在 Escape/platform 和外部分支协调中保持 passive,固定的 Tooltip 优先响应 Escape;
  • 由 family:overlay-dismissal 指定的所有成员,在其相关通道上共享并采用 eligible-owner 和关联分支操作;
  • 在 dropdown/menu 根外部点击会关闭整个打开的子菜单级联,而子分支外部行为在适当时保留其父级;
  • 每个指针驱动的分支关闭都使用分支手势声明,并且每个关联的重新打开路径都遵守该声明;
  • Toast 在零个、一个和两个活动原生 modal 之上保持可见且可操作,不会丢失条目、计时器、主题或焦点交接;
  • 普通 CommandPalette 在现有 modal 之上打开,并作为选中的活动属主参与;
  • 普通覆盖层保持局部,在没有经过批准的记录变更时不能选择加入全局托管;
  • 公开文档准确描述完整的原生支持和降级 fallback;
  • 必需的 Chromium 和 WebKit 浏览器矩阵全部通过;并且
  • architecture:layer-runtime 和 family:overlay-dismissal 反映已发布的实现,且不将这些条目列为缺口。

决策日志

DEC-1 — 关闭遵循符合条件的交互属主

参考: spec:AST-003/DEC-1 决策者: cixzhang,2026-08-30

Escape 和平台关闭选择最顶层的合格活动或 blocking 属主,而不是最顶层的可见或已注册表面。未固定的 Tooltip 是 passive 的,不能遮蔽其下方的 Popover、菜单、Dialog 或关联交互元素;固定 Tooltip 属于用户自身的交互(DEC-6)。

已否决:让每个可见的瞬态 layer 都消耗一次 Escape。这会让补充信息阻止用户试图关闭的交互。

DEC-2 — 外部交互解析关联分支

参考: spec:AST-003/DEC-2 决策者: cixzhang,2026-08-30

外部交互的范围与 Escape 不同。在 dropdown 或菜单级联外部点击会关闭整个关联根分支,包括每个已打开的子菜单。仅在某个独立嵌套子分支外部交互时,会在事件仍处于父分支内的情况下关闭该子分支,同时保留父分支。

已否决:为每个通道复用同一个视觉上的最顶层门控。单次交互和分支范围交互具有不同的用户意图。

DEC-3 — 关闭手势在分支范围内被声明

参考: spec:AST-003/DEC-3 决策者: cixzhang,2026-08-30

关闭某个分支的指针手势在关闭前即被声明。该手势不能继续进入关联触发器并立即重新打开该分支中的任何表面。菜单悬停还会抑制关闭面板暴露其触发器时产生的合成悬停。

已否决:仅基于时间戳的去抖。手势身份必须能在任一浏览器事件顺序下存续,同时不延迟下一次有意的交互。

DEC-4 — 选定的全局系统使用原生 above-modal 托管

参考: spec:AST-003/DEC-4 决策者: cixzhang,2026-08-30

Toast 和普通 CommandPalette 是当前选定的全局系统。它们可以通过浏览器有效的原生托管出现在活动原生模态对话框之上。这并不会让普通覆盖层变成全局。

已拒绝:依赖 body portal 或高 z-index。二者都无法跨越原生模态框的顶层(top-layer)边界。

DEC-5 — 完整的锚定行为依赖于原生平台特性

参考: spec:AST-003/DEC-5 决策者: cixzhang, 2026-08-30

原生 Popover API 与 CSS Anchor Positioning 共同定义了完整的锚定层(anchored-layer)契约。不支持的浏览器会获得有文档记录、可用的简化回退方案,而不是等同的定位、层叠、关联或关闭行为。

已拒绝:将当前的 display 回退方案描述为 polyfill。它并未实现浏览器缺失的系统。

DEC-6 — 被固定的层是用户自己的交互

参考: spec:AST-003/DEC-6 决策者: cixzhang, 2026-10-31

如果用户通过按压操作,借助 useTooltip 的 show() 将某个 Tooltip 固定为打开状态(正如按压 InfoTip 那样),那么这个 Tooltip 就是用户主动要求保留的内容,因此它是一个活动属主(active owner);Escape 会先关闭它,再关闭其下方的属主。仅在悬停或聚焦时进行预览的 Tooltip 则保持被动。

已拒绝:让所有 Tooltip 都保持被动,因为这样 Escape 会关闭用户固定住的提示后面的 Dialog。

未决问题

无。

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