本地堆叠与浏览器顶层路由系统规范¶
意图¶
Astryx 组件应当能够对自身绘制的各个部分进行排序,而不改变无关组件、页面内容或应用界面框架(chrome)的堆叠方式。菜单、对话框以及其他浮动交互表面应当通过 Astryx 的 Layer 系统与浏览器顶层脱离普通文档堆叠,而不是通过更大的 z-index 值。
本规范区分两种机制:
- local stacking(本地堆叠):对单个组件自有表面内部的各部分进行排序;
- top-layer routing(顶层路由):通过
architecture:layer-runtime承载浮动交互表面。
局部数值永远不会成为对整个页面的声明。
非目标¶
- 定义阴影、边框或感知高度。这些仍属于视觉设计范畴。
- 创建全局数值型 z-index 刻度或语义化的页面级 z-index 令牌。
- 更改由哪种交互来关闭菜单、对话框、弹出层(popover)或其他浮层。
- 要求没有局部绘制顺序关系的组件使用
isolation: isolate。 - 将 React portal 视为等同于浏览器顶层提升。
术语¶
- Local layer(本地层): 已定位(positioned)或具有堆叠上下文(stacking-context)的后代元素,其绘制顺序仅在单个组件自有表面内部有意义。
- Isolation owner(隔离所有者): 为某个本地堆叠关系建立
isolation: isolate的组件自有元素。 - Surface owner(表面所有者): 绘制或直接拥有组件表面的元素,该表面的各部分正在被排序,包括其背景、边框、裁剪或高度边界。
- Floating interaction surface(浮动交互表面): 菜单、对话框、弹出层、工具提示(tooltip)、悬停卡片(hover card)、面板(sheet)、命令表面(command surface)或类似 UI,必须脱离普通内容或裁剪才能执行其交互角色。
- Browser top layer(浏览器顶层): 通过 Popover API 或模态
<dialog>等原生机制进入的平台堆叠平面。
要求¶
本地堆叠¶
- FR1 — z-index 仅限本地。 Astryx 中的
z-index值 MUST 对单个组件自有堆叠关系内的各部分进行排序。它 MUST NOT 针对无关组件、应用内容、AppShell chrome 或另一个页面区域建立排序约定。 - FR2 — 表面拥有隔离边界。 每个本地堆叠关系 MUST 在包含该关系的组件表面上拥有一个
isolation: isolate所有者。隔离边界 MUST 位于表面所有者上,而不是任意的页面包装器或遥远祖先上。 - FR3 — 隔离所有者不会自我升级。 外层隔离所有者 MUST 保持在其正常的父级绘制级别。局部
z-index值属于该所有者内部的后代。如果嵌套表面必须在更大的组件内部排序,则该更大的组件提供另一个本地隔离所有者。 - FR4 — 局部数值没有系统级排名。 诸如
-1、0、1、2或动态局部深度之类的值 MAY 表达隔离所有者内部的关系。同样的值在另一个组件中 MAY 表示不同的含义。Astryx MUST NOT 记录或依赖诸如“输入框在 1”、“粘性内容在 10”或“浮层在 1000”之类的页面级分区。 - FR5 — 修复泄漏的所有者,而不是无关的邻居。 当组件的一部分绘制在无关 UI 之上时,修复方法 MUST 将该部分限制在其组件自有表面内。将无关的页头、外壳或邻居提升到更大的数值并不是符合规范的修复。
- FR6 — 每个局部状态都保持受控。 悬停、聚焦、校验、拖拽、粘性、选中、调整大小、动画以及负层级状态 MUST 保持在同一个隔离边界内。状态变化 MUST NOT 将组件表面提升为页面级堆叠竞争者。
浮动交互表面¶
- FR7 — 浮动交互使用 Layer 系统。 菜单、对话框、弹出层、工具提示、悬停卡片、面板、命令表面以及等效的浮动交互 MUST 使用
architecture:layer-runtime所拥有的承载与提升机制。本地组件 MUST NOT 使用定位 DOM 和页面级z-index来重建该系统。 - FR8 — 浏览器提升拥有跨表面顺序。 必须脱离普通内容或裁剪的浮动交互 MUST 通过适用的 Layer/原生宿主进入浏览器顶层。body portal、固定定位或更大的数值都不能替代。
- FR9 — 顶层宿主内部的数值仍然是本地的。 被提升的表面 MAY 使用局部隔离的 z-index 值来对其自身的背景层(backdrop)、面板、箭头、控件或动画板进行排序。这些数值 MUST NOT 被视为该表面出现在页面内容或另一个原生宿主之上的原因。
- FR10 — 现有 Layer 支持边界保持权威性。 原生 Popover 与模态对话框行为、矫正性 portal、锚定定位、功能受限浏览器的回退以及全局宿主准入继续遵循
architecture:layer-runtime和 AST-003。当原生支持不可用时,本规范并不授权组件绕过这些契约。 - FR11 — 文档流内 UI 保持在文档流中。 标签、状态消息、横幅、粘性页面区域、焦点环或其他文档流内呈现,不会仅仅因为需要局部绘制排序就变成浮动交互。除非其所属契约明确将其分配给 Layer,否则它遵循 FR1–FR6。
实现要求¶
- IR1 — 每个已发布的 z-index 都被分类。 在本规范发布之前,已发布包源码和 CLI 生成的模板源码中的每个生产环境
z-indexMUST 被分类为:受包含的本地关系、Layer/原生顶层宿主内部的本地关系,或迁移缺口。未分类的值会使迁移失败。 - IR2 — 新的泄漏在机制上失败。 仓库检查 MUST 拒绝没有组件自有隔离表面的新增本地 z-index 关系。对于无法静态推导所有者的关系,检查 MAY 使用源码元数据或狭窄的允许列表,但允许列表条目 MUST 指明其所有者和验证方式。
- IR3 — 绕过 Layer 的行为在机制上失败。 仓库检查 MUST 拒绝使用页面级 z-index 而非共享 Layer 或原生顶层路径的新增菜单、对话框、弹出层、工具提示、悬停卡片、面板、命令表面或等效浮层。
- IR4 — 迁移移除过时的分区。 当某个表面被包含或移入顶层时,过时的页面级 z-index 注释、常量、令牌、测试以及补偿性的邻居数值 MUST 在同一变更中移除。
平台支持¶
- 支持的功能/引擎下限:
isolation: isolate在 Astryx 支持的每个浏览器中定义局部层叠上下文。浮动表面支持遵循architecture:layer-runtime中的矩阵和降级方案。 - 不支持的行为:低于原生 Layer 功能下限的浏览器将获得文档化的降级方案。它 MUST NOT 获得未文档化的全局 z-index 阶梯作为尝试性的 top-layer polyfill。
- 浏览器证据:局部包含需要真实浏览器的绘制和命中测试证据。Popover、模态对话框、焦点/惰性以及 top-layer 排序需要
architecture:layer-runtime指定的真实浏览器矩阵;Playwright WebKit 不能替代 Safari 特有的证据。
当前状态影响¶
仓库中已包含预期局部模式的良好示例:Thumbnail、Calendar、ChatComposer、ChatLayout、CodeBlock、CheckboxInput、RadioList、Switch、Slider、Field 的 attached-status 包装器,以及触屏 DateInput 面板,都将内部 z-index 关系置于局部 isolation: isolate 所有者之下。它们只是迁移参考,并非所有后代均正确的全面证明。
本次源码审计覆盖了已发布包源码和 CLI 生成的模板源码:packages/{core,lab,charts,richtext}/src 与 packages/cli/assets/templates,不包括测试和 stories。共在 40 个文件中发现 56 条生产声明,以及以下当前缺口:
| 表面 | 当前机制 | 本规范下的影响 | 所需迁移或证明 |
|---|---|---|---|
| 共享 Field 输入包装器,包括 TextInput、FileInput、TextArea、NumberInput 和 RichTextEditor | inputWrapperStyles.base 将已绘制的输入表面本身置于 z-index: 1;只有 attached-status 组合添加了隔离包装器;RichTextEditor 还在未隔离的表面内部将其状态图标置于局部 1 |
已确认泄漏。 分离式和 tooltip Field 组合会直接与 AppShell 以及后续页面内容竞争 | 为每种变体的 Field 所属表面添加隔离,将包装器和状态图标层保持在其下方,并移除已绘制输入表面的外部层级 |
| 生产环境 docsite 组件页面 | 对 /components/TextInput 的实时 Chromium 探测发现,渲染的输入框和粘性 AppShell 头部都处于 z-index: 1,且 isolation: auto;当输入框滚动到头部区域后,它在浏览器的命中测试中获胜 |
已确认对用户可见的泄漏。 一个真实组件示例在生产路由上覆盖了导航 | 保留该路由和重叠控件关系作为 Chromium 回归测试夹具;证明受包含的字段在无关的粘性 chrome 下方通过 |
| AppShell 头部和跳转链接 | 粘性头部使用 1,聚焦的跳转链接使用 9999,且 shell 根节点未隔离;仅透明内容建立了局部隔离边界 |
已确认页面级耦合。 AppShell 为普通 shell 部件暴露了数值分层带 | 隔离 AppShell 所属表面,并仅使用其中的局部层级;跳转链接仍是 AppShell 的局部内容,而不是可复用的全局分层带 |
| ChatComposerDrawer 和 ChatDictationButton | 单独导出的抽屉根节点和听写条使用 z-index: 1,但不拥有隔离;放置在 ChatComposer 内部只是使用方约定 |
已确认隐式包含缺口。 这两个导出物都可以在 ChatComposer 的隔离根节点之外组合使用 | 为每个导出部分提供一个组件拥有的隔离表面,并使其内部排序保持局部;不要依赖使用方的祖先节点 |
| InputGroup 焦点排序 | 聚焦的连接子项使用 z-index: 1;InputGroup 通过分离路径组合 Field |
已确认泄漏。 焦点排序可能逃逸出该组 | 隔离完整的已绘制组所有者,并针对相邻组件验证连接边框的焦点排序 |
| SideNav 粘性内容 | 粘性顶部区域使用 z-index: 1;SideNav 根节点未被隔离 |
已确认的泄漏。 粘性导航内部元素可能与同级元素产生竞争 | 为 SideNav 表面添加隔离;折叠菜单继续使用 Popover/Layer |
| Outline 活动指示器 | 定位指示器在未隔离的根节点下方使用 z-index: 1 |
已确认的泄漏。 视觉指示器可能在 Outline 之外产生竞争 | 隔离 Outline 根节点,并保持指示器关系的局部性 |
| Table 粘性列和调整大小手柄 | 粘性表头/表体单元格使用 3 和 1,行覆盖层使用 -1,调整大小手柄使用 1;TableScrollWrapper 未被隔离 |
已确认的泄漏。 表格内部元素可能与无关的外壳内容相遇 | 隔离 TableScrollWrapper;在其下方保留表头/表体/覆盖层/调整大小的层级顺序,并验证外壳界面下的粘性状态 |
| 可调整大小的手柄和局部覆盖层 | 覆盖层根节点、命中区域和药丸使用 1 和 2;没有任何已调整大小的表面所有者被隔离 |
已确认的泄漏。 调整大小的操作提示可能逸出它们所在的区域 | 隔离每个已调整大小的面板或区域所有者,而不仅仅是手柄的后代元素;对照相邻内容验证拖拽和焦点状态 |
| Lab Schedule 和 ChartZoom 覆盖层 | Schedule 使用 1、动态事件层级和 20;ChartZoom 使用 1;两个绘制根节点均未被隔离 |
已确认的泄漏。 可视化内部元素创建了页面级的层级排名 | 隔离 Schedule 和 Chart 的绘制根节点;Chart 还需建立其绝对定位工具栏所需的包含块 |
| ChartTooltip | 已发布的 Charts 包使用 position: fixed 和 z-index: 9999 渲染工具提示,而不是使用 Layer |
已确认的 Layer 绕过和页面级泄漏。 它使用的正是 FR7–FR8 所禁止的替代方案 | 让 ChartTooltip 通过 Layer 的固定模式和浏览器顶层渲染;将工具提示内部的层级顺序保持在它自己的表面内 |
| Lab ListInput 和 TransferList 重新排序指示器 | 共享的重新排序样式使用 z-index: 2;ListInput 的分离 Field 路径未被隔离,而 TransferList 偶然依赖 container-type |
已确认 ListInput 存在缺口;TransferList 的隐式包含并非显式约定 | 为两个绘制所有者添加显式隔离,并在 Chromium 中验证重新排序的命中测试 |
| CLI 生成的页面模板 | 仪表盘警报栏和设置对话框使用局部 1;表格筛选使用 reorder 2;Kanban 在 1000 渲染固定拖拽克隆体 |
已产生的泄漏。 新的使用方应用会继承隐式局部边界,并且 Kanban 会继承一个页面级浮动条带 | 为局部模板关系添加显式 surface 隔离;将 Kanban 拖拽克隆体路由到仅用于视觉的 Layer/top-layer 宿主 |
| Popover、Lightbox 和模态面板内部 | 小数值在原生 Popover 或 dialog 宿主内部排列箭头、控件、手柄、面板和色调 | 正确的跨页机制;局部所有权仍需证明。 将这个 surface 置于页面内容之上的是浏览器宿主,而不是该数值 | 保留 top-layer 宿主,并为每个内部关系添加或指认一个显式隔离所有者 |
| ToastViewport | 该 viewport 进入 popover="manual",但同时带有 z-index: 500 |
多余的页面带数值,加上 AST-003 宿主缺口。 控制页面内容顺序的是原生提升,而不是 500;当前 Toast 仍可能位于后续 modal 之后 |
先完成 AST-003 的全局宿主,或与本次变更一同完成;然后移除 500,并将任何内部排序保持在隔离的 viewport surface 之下 |
| BottomSheet 和 BottomSheetSwitcher 的非模态路径 | 非模态 dialog.show() 路径使用从 1000 开始的静态或动态数值 |
已确认的全局泄漏。 页面带无法提供 dialog 层语义 | 将非模态宿主路由到 Layer/原生 top-layer 基础设施;将面板、手柄、色调、操作和堆叠排序在宿主内部进行局部隔离 |
当前源码已经将 Tooltip、HoverCard、Popover、DropdownMenu 及其子菜单、ContextMenu、CommandPalette、模态 Dialog、Drawer、Lightbox、MobileNav、Tour、Date-input layers 和 RadialTooltip 路由到 Layer、原生 Popover 或 showModal()。它们的跨页机制在方向上符合要求。已确认的例外是 ChartTooltip,以及 BottomSheet 和 BottomSheetSwitcher 的非模态路径。Toast 已被提升,但仍存在 AST-003 已拥有的全局宿主限制。
此表是影响清单,而非实现批准。每一行在迁移落地之前仍需要其具名的浏览器证据。全面的 IR1 审计可能增加行;只有具备具名所有权和证据时,一行才可被清除。
验证¶
| Contract | 验证 | 代表性状态 | 变更或失败预期 |
|---|---|---|---|
| FR1–FR6 | 源码分类加上真实 Chromium paint/hit-test 矩阵 | 正、零、负、sticky、focused、dragged、selected 和 animated 局部层 | 移除隔离所有者会让后代覆盖无关兄弟节点;更改局部数值永远不会改变页面级顺序 |
| FR2, FR3 | DOM 所有权和 computed-style 断言 | painted surface root、嵌套局部 surface、透明 surface、使用方 wrapper | 隔离出现在较远的页面祖先上,或隔离所有者本身通过页面级 z-index 参与竞争 |
| FR5 | 前后回归 fixtures | docsite Field 位于 sticky AppShell header 之下;Table 位于 shell chrome 之下 | 必须提高一个邻居节点才能让 fixture 通过,否则泄漏的 surface 仍会在 hit-testing 中胜出 |
| FR7–FR10 | Layer 单元测试与真实浏览器顶层矩阵 | 菜单、子菜单、对话框、弹出框、工具提示、悬停卡片、面板、CommandPalette、Toast | 已定位的 DOM 或 body portal 取代 Layer,或数值带决定跨表面顺序 |
| FR11 | 组件与浏览器测试 | 标签/状态重叠、粘性区域、焦点环、横幅 | 流内 UI 被不必要地提升,或其局部绘制状态逃逸出其表面 |
| IR1 | 生成的已发布 z-index 清单在 CI 中检查 | 每个已发布包与生成的模板声明 | 声明缺失、重复,或没有所有者/分类 |
| IR2, IR3 | 带有效与无效示例的静态规则夹具 | 隔离的局部组件、泄漏的 Field、手工构建的菜单、原生 Layer 表面 | 泄漏或 Layer 绕过通过,或有效的隔离关系被拒绝 |
| IR4 | 变更文件与源码扫描 | 已迁移的 Field、AppShell、Table、Toast、BottomSheet、Drawer | 迁移后仍残留过时的数值带、注释、测试或补偿值 |
完成标准¶
本规范仅在满足以下所有条件时才转为 shipped:
- 已发布包源码与 CLI 生成的模板源码中的每个 z-index 都有所有者与分类;
- 每个普通局部关系都被其组件拥有的绘制表面所包含;
- 真实文档站 Field/AppShell 失败在修复前可复现,并在修复后通过局部包含;
- 菜单、对话框、弹出框、工具提示、悬停卡片、面板、命令表面及等效覆盖层使用 Layer/原生顶层路径;
- 数值带不再决定跨组件、页面外壳或覆盖层顺序;
- 机械检查拒绝具有代表性的局部泄漏与 Layer 绕过;
- 局部包含与 Layer 托管的浏览器矩阵通过;以及
architecture:layer-runtime以及受影响的家族/组件记录描述已发布的所有权,而不依赖此影响清单。
决策日志¶
DEC-1 — z-index 仅表达局部关系¶
参考: spec:AST-027/DEC-1
决策者: cixzhang, 2026-09-04
一个 z-index 值属于某一个组件所有的层叠关系。在其他地方复用同一个数字不会在组件之间建立任何关系。
已否决方案:一个将输入框、粘性导航、页面界面元素和覆盖层相互排名的全局刻度。这种刻度会把每个局部变更变成页面级的兼容性问题。
DEC-2 — 隔离位于组件表面¶
参考: spec:AST-027/DEC-2
决策者: cixzhang, 2026-09-04
拥有绘制表面的元素同时也建立 isolation: isolate。此后,后代 z-index 值可以对该表面的各个部分排序,而不会逃逸到无关内容。
已否决方案:将隔离放在任意页面包装器上,或抬升表面根元素本身。二者都会保留组件与其调用方之间的隐藏耦合。
DEC-3 — 浮动交互通过 Layer 使用浏览器顶层¶
参考: spec:AST-027/DEC-3
决策者: cixzhang, 2026-09-04
菜单、对话框及等效浮动交互通过 Astryx 的 Layer 系统和适用的原生顶层宿主进行路由。它们的跨表面顺序来自浏览器宿主与 Layer 契约,而非数字。
已否决方案:以固定定位、body portal 或大 z-index 作为 Layer 的替代品。这些机制无法提供原生顶层、模态、关联、定位或关闭行为。
DEC-4 — 泄漏在其所有者处修复¶
参考: spec:AST-027/DEC-4
决策者: cixzhang, 2026-09-04
当 Field 或其他组件覆盖无关的外壳界面元素时,应在组件自身的表面上将其包含。不要抬升 AppShell,也不要添加另一个全局带。
已否决方案:将 AppShell 头部抬升为更大的页面级值。它只能通过压过当前值来通过已知比较,并留下下一个更大的值重现同样的缺陷。
未决问题¶
无。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx