Phoenix 前端 Overlay 模块架构:模态层级、堆叠带与 React Aria Polyfill 实战指南

原创2026-09-23 21:06:071,434 阅读
文章标签:人工智能LLMOps可观测性链路追踪AI 评测模型评测大模型提示工程数据可视化MLOps后端前端

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 正交

模块为每个浮层定义两个互相独立的问题,任何实现都不得由一个推导另一个:

  1. Modality(模态性)——该表面打开时,用户还能不能操作页面其余部分?这是一个"交互契约"(interaction contract)。
  2. 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

三个补丁的源码依据:

  1. 区域级模态:ViewportModal.tsx 文件头详细列出了 8784/8796/7743/7954 四个上游 issue;补丁自己 portal 进帧的视口模态平面、向 frame 注册(由 frame 盖 inert)、用 FocusScope 收拢焦点。
  2. 外部点按消费:outsideInteraction.ts 解释了 usePopover 硬编码导致的缺口,并刻意保留了与 RA 的一处分歧:RA 从不对外部点按调用 preventDefault()(以保留 mousedown 焦点与文本选择),而本补丁调用——因为被消费的点按不能把焦点移进它被阻止激活的表面。
  3. 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:通过 ViewportModalOverlay portal 进 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-prop close 与 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 下维护了四组测试,是验证上述契约的最佳活文档:

小结

Phoenix 的 Overlay 模块用一个清晰的心智模型解决了一类最容易被忽视、却又最容易出问题的前端难题:Modality 决定"能不能碰",Stacking 决定"谁在上面",两者正交、互不推导。视口级模态(Tier 1)、窗口级模态(Tier 2)与非模态表面三层分工明确;帧(Frame)与平面(Plane)的职责切分(frame 管"是否阻塞",host 管"阻塞哪些区域")让"表单弹窗 + AI 助手侧栏并存"成为可能;堆叠带 + React context 钳制让嵌套浮层永远不可能画错层;三处有据可查、附移除条件的 polyfill 台账则保证了 react-aria 上游演进时,这些补丁可以安全地逐一退役。对需要深度定制浮层体系的前端团队而言,这份"契约式"模块设计本身就是一份可复用的架构范本。

登录后查看全文
phoenix