Phoenix 前端 Overlay 模块架构:模态层级、堆叠带与 React Aria Polyfill 实战指南
Phoenix 前端 Overlay 模块架构:模态层级、堆叠带与 React Aria Polyfill 实战指南
Phoenix(AI Observability & Evaluation 平台)的前端 UI 中,几乎所有浮层——弹窗(Modal)、抽屉(Drawer)、弹出框(Popover)、菜单(Menu)以及承载它们的应用框架(Frame)——都由 js/app/src/components/core/overlay 这个自包含模块统一管理。本文以模块官方文档 overlay/README.md 为主体,结合 frame.tsx、ViewportModal.tsx、outsideInteraction.ts 等源码与测试用例,系统讲解该模块的"模态三层级 + 堆叠带"模型、帧与平面的工作原理、关闭(dismissal)语义,以及它针对 react-aria 维护的三处 polyfill 台账与宿主 token 契约。读完本文,你将理解 Phoenix 如何做到"表单弹窗不阻断 AI 助手侧栏"这类精细交互控制,并能遵循同样的模式在项目里扩展新的浮层表面。
模块定位:可整体搬走的 vendored 包
Overlay 模块的设计目标非常明确:凡是出现在 Phoenix UI 上方的表面,都归它管——弹窗、抽屉、弹出框、菜单(经 Popover),以及把它们锚定在一起的应用框架(frame)。
模块在架构上刻意保持自包含:
- 模块不 import 任何应用代码,只依赖
react、react-dom、react-aria(-components)、react-stately、@emotion/react、clsx与react-hotkeys-hook,外加 README 中约定的 CSS 设计 token; - 应用只能通过唯一入口
index.ts使用它,目录外禁止深路径 import 兄弟文件(见 index.ts 的模块头注释); - 因此它被当作一个"vendored(本地固化的第三方)包"对待:如果将来要抽出为独立包,边界已经画好。
README 还指出,本模块有一个交互式配套文档,位于 Storybook 的 stories/OverlayStacking.mdx("Overlay stacking and modality"),建议结合阅读。
核心模型:Modality 与 Stacking 正交
模块为每个浮层定义两个互相独立的问题,任何实现都不得由一个推导另一个:
- Modality(模态性)——该表面打开时,用户还能不能操作页面其余部分?这是一个"交互契约"(interaction contract)。
- Stacking(堆叠)——当两个表面重叠时,谁画在上层?这是一个"绘制顺序"(paint order)。
模态性的三个层级
| 层级 | 组件 | 阻塞范围 | 用途 |
|---|---|---|---|
| 1 — 视口级模态(viewport modal) | ViewportModalOverlay + ViewportModal |
只阻塞应用视口;AI 助手侧栏(assistant rail)保持可交互;永远不使用 aria-modal |
表单、编辑器——用户可能需要助手帮忙的任何场景 |
| 2 — 窗口级模态(window modal) | ModalOverlay + Modal(纯 React Aria) |
阻塞一切,包括侧栏 | 破坏性确认、必须阻断的决策 |
| 非模态(non-modal) | Popover、Drawer、菜单 |
不阻塞任何东西——但会消费(consume)一次用于关闭的点按,绝不透传 | 菜单、选择器、边查边干的面板、详情抽屉 |
三个层级在源码中有清晰对应。Tier 2 直接复用 React Aria Components 的 ModalOverlay / Modal,见 Modal.tsx:ModalOverlay 默认 isDismissable={props.isDismissable ?? true}(点击遮罩默认关闭,除非调用方显式关闭),Modal 通过 data-size 与 centeredModalCSS 支持 S / M / L / fullscreen 四种尺寸,并带淡入(modalFade)、缩放(modalZoom)与遮罩退场动画。
Tier 1 的 ViewportModal 是 Phoenix 对 react-aria 最重要的定制:它只阻塞应用视口,锚定的 AI 助手侧栏仍是普通可交互的兄弟节点。由于一旦设置 aria-modal 就会对辅助技术隐藏仍然可交互的侧栏,所以它永远不设 aria-modal(见 ViewportModal.tsx 文件头注释)。
非模态层级则通过 Popover 的 isNonModal + closeOnInteractOutside 组合实现"不阻塞,但关闭点按被消费"的语义,详见下文"Dismissal"一节。
应用框架:OverlayFrameProvider 与三个 Plane
应用在根上只渲染一次 OverlayFrameProvider,并在其视口内部挂载如下结构(README 的 "The frame" 一节,源码见 frame.tsx):
DrawerPlane——Drawer的 portal 目标;当视口级模态打开时进入inert状态。源码中它inert={frame?.isViewportBlocked || undefined}(frame.tsx)。ViewportModalPlane——ViewportModalOverlay的 portal 目标,自身从不inert,因为它承载的就是阻塞层本身(frame.tsx)。ViewportPortal—— 把 React Aria 的 portal(如 toast)"重新落户"到应用视口内,使提示居中于工作区而非整个窗口;帧外回退到document.body(frame.tsx)。
阻塞状态归谁:Frame 管"是否",Host 管"哪些区域"
OverlayFrameProvider 通过 viewportOverlayCount 计数维护 isViewportBlocked 标志:每个打开的 ViewportModalOverlay 在 useLayoutEffect 里注册自己(registerViewportOverlay),关闭时注销(frame.tsx)。而"具体给哪些区域盖上 inert"由宿主应用决定——只有宿主才知道自己的布局。README 给出的约定是:
inert={useOverlayFrame()?.isViewportBlocked || undefined}
把这个属性盖在每个视口级模态需要阻塞的区域上。
视口模态豁免属性:刻意不用 React Aria 的顶层标记
对必须保持在 Tier 1 之上可交互的控件(典型如助手侧栏的开关),模块提供了专属的豁免属性:
{...viewportModalInteractionExemptProps}
frame.tsx 中定义了 data-viewport-modal-interaction-exempt 属性及其选择器 VIEWPORT_MODAL_INTERACTION_EXEMPT_SELECTOR(frame.tsx)。这个设计是有意为之:它刻意不是 React Aria 的 data-react-aria-top-layer,因为后者会让元素同时豁免于 Tier 2(窗口级模态)——而 Tier 2 必须阻塞一切(见 frame.tsx 注释)。
Plane 是纯 portal 目标
两个 plane 共用 planeCSS(frame.tsx):pointer-events: none、无布局、几何完全由宿主通过 className/css 提供;z-index、inert 行为、注册机制等"其余一切"都属于模块。注意这里 overflow: clip 用的是 clip 而非 hidden——这样进入动画中 overlay 内部的自动聚焦滚动显现永远不会滚动到 plane 本身,从而避免 transform 滑入动画被永久偏移。
堆叠:用带(bands),不用裸数字
绘制顺序来自应用级 z-index token 阶梯(由宿主定义,见下文"Token 契约")。Popover 通过 stacking prop 申请一个带(band);嵌套 popover 会被钳制到至少父级的带(钳制跟随 React context 传播,因此能跨 portal 生效)。
只有两个带可以被请求
stacking.ts 定义了可请求的带:
app-floating—— 用于持久的面板式表面,模态应该能盖住它;app-portaled-overlay(默认)—— 用于瞬态的轻关闭表面(菜单、选择器、picker),必须压过启动它的内容。
阶梯上的其它档位(drawer、modal、notification)属于各自专用组件,由它们钉死自己的带(例如 Modal 使用 APP_MODAL_Z_INDEX、ModalOverlay 使用 APP_MODAL_BACKDROP_Z_INDEX,见 Modal.tsx);如果让 popover 也能请求这些档位,调用方就能把瞬态表面画到 toast 之上——这是不允许的。
常量命名刻意与 --global-z-index-app-* token 一一对应(stacking.ts),这样常量、token、以及任何 prop 值里命名的带共享同一套词汇,grep 任何一个都能找到其它几个。
嵌套钳制原理
resolveStackingBand(stacking.ts)比较请求带与继承带在 OVERLAY_STACKING_BANDS 数组中的下标,取更靠后者。Popover 渲染时通过 OverlayStackingContext.Provider 把自己的解析结果下发给 React 子树(Popover.tsx)——context 而非 DOM 承载该值,正是因为嵌套 overlay 会 portal 出自己的父 DOM。
测试 Popover.test.tsx 完整验证了这套语义:
- 默认栈在
app-portaled-overlay带(zIndex为var(--global-z-index-app-portaled-overlay)); - 请求
app-floating时生效; - 父在 portaled-overlay、子请求 app-floating 时,子被钳制回父的带(否则子会画在"生下它"的 overlay 之下);
- 父在
app-floating时,子的默认app-portaled-overlay请求保留不变。
README 给出了铁律:如果嵌套 overlay 被埋住了,是组合方式或带分配错了,绝不能用裸 z-index 去修。
Dismissal:三层各自如何关闭
Tier 1 与 Tier 2:进入 React Aria overlay 栈
两个模态层级都参与 React Aria 的 overlay 栈,因此 Escape 与外部点按会以自顶向下的顺序,对叠在其上的菜单、popover 依次解析。
关键实现细节:ViewportModal 的 useOverlay 调用正是它进入 React Aria 内部 overlay 栈的登记点——这是为什么 Escape 和外部点按能正确地从栈顶向下解析到弹在模态上方的菜单与 popover。它是承重结构,不能用裸 keydown 监听器替换(ViewportModal.tsx 与 ViewportModal.tsx)。
ViewportModalOverlay 还有两个值得注意的关闭策略:
- 视口外点按永不关闭:
canCloseForTarget检查目标是否落在应用视口元素内(applicationViewport.contains(target)),以及是否命中豁免选择器;两者都不满足才交给调用方的shouldCloseOnInteractOutside(ViewportModal.tsx)——即点助手侧栏不会关掉视口级模态; - 同步释放阻塞态:
close通过flushSync(unregisterViewportOverlay)先同步释放 frame 的阻塞态,让被inert的区域恢复可交互,再做焦点恢复。这是因为焦点原目标若位于被 frame 盖inert的区域,FocusScope自带的restoreFocus会在竞态中落败(焦点掉到 body),于是requestAnimationFrame里手工把焦点还回去(ViewportModal.tsx)。
Drawer:栈之外,用 frame 状态做守卫
Drawer 不在 React Aria 的 overlay 栈里(它不是 RA overlay)。它的文档级 Escape 监听器改用 react-hotkeys-hook 的 useHotkeys,并以 frame?.isViewportBlocked 作为守卫(Drawer.tsx):
useHotkeys("Escape", () => onClose?.(), {
enabled: isOpen && !(frame?.isViewportBlocked ?? false),
});
这样,当视口级模态打开时(Escape 归模态所有),抽屉的全局 Escape 不会与之抢键。
非模态 Popover/菜单:closeOnInteractOutside 与点按消费
非模态 popover/菜单通过 closeOnInteractOutside 显式加入关闭行为,其保证是:用于关闭的那次点按会被消费掉,从而不会激活底下躺着的内容——这正是模态遮罩层提供的保证,却没有滚动锁(scroll lock)和应用级 aria-hiding 的开销。
实现细节见 outsideInteraction.ts 的 useConsumeOutsidePress:
- 用
useInteractOutside监听onInteractOutsideStart与onInteractOutside,对外部交互调用preventDefault()+stopPropagation()并state.close()(outsideInteraction.ts); - 点在 popover 自己的 trigger 上也被消费并关闭(模态对等切换,下次点按再重开)——这是指针策略,与失焦策略(
shouldCloseOnInteractOutside默认排除 trigger 自身,见 Popover.tsx)区分开; - 后代 overlay 内部的交互被放过:通过 overlay 树(
OverlayTreeContext+useOverlayTreeNode)跨 portal 识别后代,父 popover 既不会消费子 overlay 内部的点按,也不会因之关闭自己(outsideInteraction.ts)。
测试 Popover.test.tsx 验证了关键行为:点击外部按钮时 popover 关闭且外部按钮的 pointerdown/click 均不触发;再次点击外部按钮则正常触发——"消费但不透传"的保证成立。同时 popoverInteractionBoundaryProps 用 onClick: stopPropagation 阻止 portal 化后的点击冒泡激活 trigger 祖先(如可点击的表行),见 Popover.tsx。
Polyfill 台账:针对 react-aria 的三处补丁
模块刻意携带了三个针对 react-aria 的补丁,每个都在实现处标注了上游 issue 链接与移除条件。汇总如下:
| Polyfill | 原因 | 移除条件 |
|---|---|---|
区域级模态(ViewportModal.tsx、frame.tsx) |
react-aria 的模态性硬编码绑定到窗口;ariaHideOutside 的 root 选项没有贯通到 hooks/RAC(adobe/react-spectrum#8784 已关闭未修复,#8796 未合并,#7743/#7954 开放中) |
react-aria 提供区域模态 → 折叠回 RAC Modal |
非模态 overlay 的外部点按消费(outsideInteraction.ts) |
usePopover 硬编码 isDismissable: !isNonModal;非模态 RAC popover 既不因外部点按关闭,也不保护底层内容 |
react-aria 允许非模态 popover 选择"可关闭且消费点按" |
Trigger 状态冒充(triggerState.ts) |
RAC 通过 OverlayTriggerStateContext 接线 Dialog 的 close/slot="close";RAC 不拥有的 overlay 必须自己提供一个 |
react-aria 暴露公开方式提供 overlay close context |
三个补丁的源码依据:
- 区域级模态:ViewportModal.tsx 文件头详细列出了 8784/8796/7743/7954 四个上游 issue;补丁自己 portal 进帧的视口模态平面、向 frame 注册(由 frame 盖
inert)、用FocusScope收拢焦点。 - 外部点按消费:outsideInteraction.ts 解释了
usePopover硬编码导致的缺口,并刻意保留了与 RA 的一处分歧:RA 从不对外部点按调用preventDefault()(以保留 mousedown 焦点与文本选择),而本补丁调用——因为被消费的点按不能把焦点移进它被阻止激活的表面。 - Trigger 状态冒充:triggerState.ts 是唯一的"冒充点",用
satisfies OverlayTriggerState让缺失成员在构建期报错而非静默改变行为。其中useResolvedOverlayTriggerState支持三种驱动方式:受控(isOpen)、非受控默认(defaultOpen)、以及两者都缺时收养祖先 RAC trigger 的状态(复用其aria-expanded、焦点恢复与 toggle 行为);createDismissTriggerState为Drawer这类开启状态完全活在 RA 之外的 overlay 提供恒开状态,所有关闭路径收敛到onClose;withInterceptedClose让ViewportModalOverlay在卸载前同步释放 frame 阻塞态。
Token 契约:宿主必须定义的 CSS 自定义属性
宿主应用必须定义以下 CSS 自定义属性(Phoenix 中定义于 GlobalStyles.tsx):
--global-z-index-local-raised、--global-z-index-local-overlay(frame 平面内部使用的局部档位)--global-z-index-app-floating、--global-z-index-app-portaled-overlay、--global-z-index-app-modal-backdrop、--global-z-index-app-modal(应用级堆叠带)- 表面样式使用的设计 token:
--global-background-color-*、--global-border-color-*、--global-rounding-*、--global-dimension-*、--global-modal-width-*、--global-popover-*、--global-overlay-*、--focus-ring-*
从源码看,这些 token 的具体使用点包括:Modal 的遮罩背景 var(--global-overlay-backdrop-color) 与四种 --global-modal-width-*(Modal.tsx)、Drawer 的圆角/边框/焦点环(Drawer.tsx)、Popover 的箭头描边 var(--global-popover-border-color)(Popover.tsx)。常量与 token 名一一对应,保证"常量、token、prop 值"三处 grep 互通(stacking.ts)。
扩展指南:新增浮层的决策路径
README 的 "Extending" 一节给出了三类扩展的决策路径,结合源码补充如下:
新增一个阻塞型表面 → 先定层级
- Tier 2:直接用普通 RAC
ModalOverlay/Modal即可(Modal.tsx)。 - Tier 1:通过
ViewportModalOverlayportal 进ViewportModalPlane;或照它的形状实现——向 frame 注册(驱动isViewportBlocked)、调用useOverlay进入 overlay 栈(保证 Escape/外部点按自顶向下解析)、用FocusScope做焦点收拢(ViewportModal.tsx)。
新增一个非模态表面 → 基于 Popover 或 Drawer
- 基于
Popover:带(band)+ 点按消费免费获得——stacking走OverlayStackingContext,closeOnInteractOutside走useConsumeOutsidePress,后代识别走 overlay 树。 - 帧锚定面板:照
Drawer的样式——portal 进 plane、用createDismissTriggerState接线 RAC 的 close 机制(让Dialog的 render-propclose与slot="close"正常工作,见 Drawer.tsx 与 triggerState.ts)、任何全局快捷键用isViewportBlocked做守卫。
新增一个堆叠需求 → 加 token,绝不加裸数字
往宿主阶梯加 token;只有当 popover 必须请求它时,才在 stacking.ts 的 OVERLAY_STACKING_BANDS 里加一个带。
实战细节:Drawer 的尺寸契约
虽然 README 未展开,但 Drawer 作为非模态表面的代表,其尺寸约束在 constants.ts 中有完整的契约,使用抽屉时值得了解:
| 常量 | 值 | 含义 |
|---|---|---|
DRAWER_DEFAULT_SIZE |
"35%" |
无持久化尺寸时的初始宽度(应用视口百分比) |
DRAWER_DEFAULT_MIN_SIZE |
"40%" |
默认最小宽度 |
DRAWER_DEFAULT_MAX_SIZE |
"95%" |
默认最大宽度;额外受侧导航间隙约束 |
DRAWER_HARD_MIN_SIZE_PX |
320 |
绝对像素下限,小视口下也不可覆盖的硬安全界 |
DRAWER_SIDE_NAV_GAP_PX |
28 |
侧导航右缘与最大化抽屉之间的呼吸空间,导航宽度被实时测量并随 resize 观察 |
DRAWER_VISIBLE_GUTTER_PX |
80 |
无侧导航可测时(Storybook、测试、未托管渲染)页面必须保持可见的下限 |
Drawer 的尺寸拖拽使用 pointer capture + rAF 合帧(Drawer.tsx),并把拖拽状态放在 ref 中绕过 React 批处理,避免 pointermove 读到过期状态;键盘可调(ArrowLeft/ArrowRight 步进 5%,Home/End 跳最小/最大),并暴露 onResize 与 useDefaultDrawerSize.ts 配合做跨访问尺寸持久化(Drawer.tsx 与 Drawer.tsx 的使用示例)。
测试保障
模块在 tests 下维护了四组测试,是验证上述契约的最佳活文档:
- Popover.test.tsx——500 次重复点击不外泄到 trigger 祖先、默认/请求/嵌套钳制的堆叠带、外部点按消费、trigger 关闭不重开、后代 overlay 内部点按不受干扰;
- ViewportModal.test.tsx——视口级模态的注册/阻塞/豁免行为;
- Drawer.test.ts 与 useDefaultDrawerSize.test.ts——抽屉的尺寸解析与持久化。
小结
Phoenix 的 Overlay 模块用一个清晰的心智模型解决了一类最容易被忽视、却又最容易出问题的前端难题:Modality 决定"能不能碰",Stacking 决定"谁在上面",两者正交、互不推导。视口级模态(Tier 1)、窗口级模态(Tier 2)与非模态表面三层分工明确;帧(Frame)与平面(Plane)的职责切分(frame 管"是否阻塞",host 管"阻塞哪些区域")让"表单弹窗 + AI 助手侧栏并存"成为可能;堆叠带 + React context 钳制让嵌套浮层永远不可能画错层;三处有据可查、附移除条件的 polyfill 台账则保证了 react-aria 上游演进时,这些补丁可以安全地逐一退役。对需要深度定制浮层体系的前端团队而言,这份"契约式"模块设计本身就是一份可复用的架构范本。