图层视口内嵌系统规范¶
{
"scope": "global",
"triggers": {
"layering": [
"FR1",
"FR2",
"FR4",
"FR5",
"FR7",
"FR8",
"FR9",
"DEC-1",
"DEC-3",
"DEC-7"
],
"layout": [
"FR1",
"FR2",
"FR3",
"FR4",
"FR5",
"FR6",
"FR8",
"FR9",
"DEC-2",
"DEC-6",
"DEC-7"
],
"behavior": ["FR2", "FR4", "FR5", "FR7", "FR8", "FR9", "FR10"],
"public-api": ["FR6", "DEC-4", "DEC-5"]
}
}
契约速览¶
| 领域 | 契约 |
|---|---|
| 公共契约 | 图层运行时全权负责视口内嵌:一个边距定义(FR1)、一个尺寸上限——即视口本身,而非触发元素旁边的空间(FR2、FR3)——一个标准回退顺序,以及一个供需要保持锚点清晰可见的图层使用的锚点避让顺序(FR4、FR5),并且应用声明持久悬浮于视口边缘的条栏时只有一处:LayerProvider 的 inset,锚定图层和 toast 视口都会读取它(FR6、DEC-4、DEC-5)。Popover 是图层的一种应用,在图层之上添加样式(DEC-1)。 |
| 行为 | 图层以自身尺寸渲染——调用方显式指定的尺寸,或内容自身的尺寸——最大不超过视口减去其边距,且绝不超出;无法适配视口的内容在图层内部溢出,由组合该图层的组件滚动或裁剪(FR2、FR3)。可换行的内容会通过换行排到触发元素旁边;无法收缩的尺寸会翻转,若两侧都无法容纳,则保持自身尺寸并沿对齐轴滑入可见区域(FR4、DEC-2);tooltip 则先翻转到对侧,再放到触发元素旁边,然后放到更宽敞的一侧(FR4)。锚点已离开视口的图层会保持其位置和尺寸(FR5、DEC-3)。图层绘制的第一帧就是它最终定位后的帧;除了 FR8 所述的键盘上限变化之外,它绝不会先绘制再移动。滚动过程中,CSS 负责定位每个锚定图层,运行时不会为每个滚动帧做布局工作(FR4、FR8、DEC-7)。 |
| 对最终用户的影响 | 用户从面板边缘附近的控件打开一个 352px 的菜单时,得到的是 352px 的菜单,而不是 274px 的菜单。手机上的长菜单会保持标签可读,而不是被压缩到触发元素旁边。图层绝不会落到应用已声明的手机导航栏下方(FR6)。未声明任何条栏的应用,一切都不会移动。在手机上,原本会进入软件键盘下方的图层,最终会停在键盘上方 10 px 处,其内容可滚动(FR9)。 |
| 对构建者的影响 | Popover.width 和 DropdownMenu.menuWidth 成为普通尺寸。带浮动条栏的应用只需在已经挂载的 LayerProvider 上声明一次 inset,放在 toast 旁边;toast 和锚定图层都会避让它。组合了 useLayer 或 usePopover 的组件会继承边距、上限和回退顺序,而无需更改记录(FR7)。 |
| 兼容性/就绪状态 | 行为变更,一个新增的 prop。靠近边缘的显式尺寸会按其尺寸渲染,而不是收缩;靠近边缘的无法换行内容会翻转或滑动,而不是溢出其盒子;正文仍然在触发器旁换行(DEC-2)。每个锚点模式层都获得边距和上限(FR7)。LayerProvider.inset 在每条边默认为零,因此未声明它的应用无论有无 provider 都渲染如旧;现有的 toast.inset 保持其含义(DEC-5)。权威:current,由所有者于 2026-10-03 批准。 |
| 审查检查项 | 拒绝在层运行时之外对视口边距的第二个定义;针对锚点跨度解析的 max-inline-size;在任一轴上可能超出视口的层盒子;由组件为锚点模式层编写的回退列表;对尺寸是否为显式的分支判断;锚点离开视口后仍然继续的滑动;充当应用栏的 layer 主题目标或主题值;在 LayerProvider.inset 之外声明栏的第二个位置;未被运行时上限钳制的使用方最小值;默认提供者下的层与无提供者时的层渲染不同;在绘制后读取并应用的几何输入(除非 FR8 允许);滚动路径中的布局读取、强制布局或强制重新选择选项;锚点避让列表中可能与锚点重叠的选项;只断言最终几何的 story。 |
| 治理规则 | architecture:layer-runtime 的 INV3、INV5 约束锚点模式放置、回退和方向,INV10 约束 LayerProvider 是什么;spec:AST-003 的 FR21–FR23 约束在缺少 CSS Anchor Positioning 时的简化行为;component:Popover 的 FR4、ORD4 约束 Popover 的条件滚动,本记录将其原样保留。 |
此表是审查投影;以下正文具有权威性。
意图¶
锚点层必须停留在屏幕上,与视口边缘及设备自身的 insets 之间留出呼吸间距;必须选择一个合适的位置;并且当应用在视口上悬浮一个栏时,必须知道视口真正结束在哪里。从面板边缘附近的控件打开菜单的人,需要菜单保持其给定的尺寸;使用手机的人需要长菜单的标签可读,而不是被挤压在触发器旁边;使用带有浮动导航栏的应用的人,需要没有任何层结束在它下方。
本记录只负责一个答案:层运行时拥有视口 inset——边距、尺寸上限、回退顺序、应用声明的 inset,以及展示它们的 stories。Popover 是层的一个应用,它在层之上添加样式。 在一处定义的边距不会在组件之间漂移;由视口而非触发器旁边的跨度设定上限的尺寸,不会在靠近边缘处收缩显式宽度;由应用一次性声明的 inset 会到达每个层,而不是那些碰巧读取它的组件。
所有权边界¶
拥有
- 视口边距:它的唯一定义、它应用于哪些边缘、设备安全区和应用声明的 inset 如何馈入其中。
- 锚点模式层在两个轴上的尺寸上限,以及触发器旁边的任何跨度都不能成为层的尺寸上限。
- 锚点模式层的回退顺序,包括滑动及其适用条件。
- 应用在何处声明悬浮在视口边缘上的持久栏——一次性声明,同时面向锚点层和 toast——以及主题不能声明它。
- 每个锚点模式层都无需组件记录变更即可继承这些行为,以及组合组件在层之上还可以添加什么。
- 展示这些视口行为的 Layer stories。
Popover 保留了什么
- 它的 props 及其含义,包括显式的
width优先于触发器匹配,以及在没有显式宽度时,表面优先采用触发器的最小宽度——层无法知道的唯一事实是此实例是否被指定了尺寸,而层也不需要知道它(DEC-2)。 - 它的视觉处理、绘制出的表面及其
popover主题目标、表面内边距,以及在层限制了表面尺寸后的条件式内部滚动(component:PopoverFR4、ORD4)。
为什么现有记录无法承载它
architecture:layer-runtime是current,描述的是已发布的层运行时;它只在变更发布时纳入已接受的层变更(spec:AST-003是其先例)。一条current记录只携带一个authority值,因此未发布的行为写入其中会同时被解读为已批准和已发布(architecture:knowledge-contractsINV1、INV14)。该记录所需的架构记录增量列在「当前状态影响」下。component:Popover是current,记录 Popover 已发布的行为,包括视口适配(其 FR3、ORD2、ORD3)。同样的authority规则适用;其增量列在下方。component:DropdownMenu、component:BaseTypeahead以及其他组合组件是这个行为的消费者,而非拥有者。一条通过同一个 hook 约束五个以上组件的规则是一个系统事实。
非目标¶
- 在放置轴上,将标准层按触发器一侧的空间来调整尺寸。 一个在触发器上方和下方都比可用空间更高的层会被限制到视口并移入其中。标准层是否更喜欢空间更宽的一侧,此处不定;保持锚点不被遮挡的层是 FR4 唯一处理的情况,而软件键盘会限制会延伸到其下方的层(FR9)。
- 全屏 Dialog。 它按惯例保持相同的 gutter 值,但不是锚点模式层;应用声明的 inset(FR6)是否会作用到它,是后续的决定。toast 视口确实会读取它(FR6,DEC-5)。
- 针对缺少 CSS Anchor Positioning 时降级行为的公开文档。
spec:AST-003FR21–FR23 负责该边界。 - 组件滚动、测量、焦点、关闭、视觉处理,以及主题结构。 它们仍归属其所有者。
- 满足此契约的等效内部实现仍然有效。模块名称、观察锚点可见性的机制、承载尺寸上限的 CSS 属性,以及 provider 的 inset 借此到达层的自定义属性,都属于实现;
LayerProvider.inset是公开表面,手动编写属性是不受支持的逃生通道。
需求¶
- FR1 — 统一的 gutter。 每个锚点模式层在每条视口边缘都保持一个与
max(--spacing-4, env(safe-area-inset-<edge>))相等、再加上该边缘应用声明的 inset(FR6)的 gutter。行内 gutter 取两个物理安全区 inset 中较大的一个,因此层即使沿行内轴翻转,也仍会避开任一侧的缺口。该定义存在于层运行时中;任何组件或组件族都不定义自己的 gutter。 - FR2 — 上限是视口,绝不是跨度。 在对齐轴上,层盒子的尺寸被限制为视口减去两个 gutter,并且盒子从不超出该上限。触发器旁边的那段视口绝不会限制层。调用方给出的显式尺寸在该尺寸下渲染,直到达到上限。内容尺寸的层在内容可换行时会将其内容包裹到触发器旁边的可用空间中;内容不可换行时则保持内容的尺寸直到上限(然后由 FR4 移动它)。无法适应上限的内容——比视口更宽的显式尺寸、不可断行的文本——在层盒子内部溢出,由组合组件决定是滚动还是裁剪;盒子本身始终留在屏幕内。层不知道也不需要知道是否被指定了尺寸;没有任何组件基于它做分支。组合组件可以设置更低的上限(Tooltip 的 300px);但不能设置更高的上限。
- FR3 — 放置轴上限。 在放置轴上,层盒子的尺寸被限制为视口减去两个 gutter,并且盒子从不超出该上限。组合组件可以设置更低的上限(DropdownMenu 的 300px),并且当其内容超过上限时可以成为滚动容器;但不能设置更高的上限。
- FR4 — 运行时的回退顺序。 锚点模式层按顺序尝试:首选位置;跨放置轴的翻转;跨对齐轴的翻转;两个翻转都做;然后,当其锚点在视口内时,沿对齐轴滑动,保持层的尺寸不变,并以最小距离将层移入 gutter 内——先尝试触发器首选侧,再尝试对侧。滑动是独立的定位选项,不是翻转失败的副作用:一个在触发器两侧都比旁边空间更宽的层,仍然会到达触发器在放置轴上有空间的那一侧。侧边放置沿块轴滑动。gutter 在两个轴上都同时约束位置和尺寸:本应落入 gutter 内或已声明栏下方的层,在那里不合适,于是尝试下一个选项;滑动后的层在两个边缘都保持 gutter。在放置轴上,该位置约束取该轴两个 gutter 中较大的一个,并应用于两个边缘,因此声明在一个块边缘的栏会让层与相对边缘保持相同的距离(尺寸上限仍然各自减去每个边缘自己的 gutter)。内容比任一侧可容纳的都高时,会被限制到视口并移入其中,保持它与所遇边缘之间的锚点间距。保持锚点不被遮挡的层——Tooltip,它的触发器上的 hover 使其保持打开——绝不会落到其锚点之上,也没有任何绘制帧显示出它在那里。这种保持锚点不被遮挡的上方或下方层使用一个合并列表代替上述顺序:首先是首选位置,然后是在自身尺寸下的相对块侧(翻转),然后是行内结束端锚点旁边,再是行内开始端,每一个都采用其内容的行内尺寸并限制到视口;只有在这之后,才使用首选的块侧和另一侧,且每一侧仅在它是空间更多的一侧时、并按照该侧空间来设定尺寸。一个合适的层如果在自己的侧面失去空间,会在移动到触发器旁边之前先翻转到对侧;只有首选侧和翻转侧都不合适时,它才会到触发器旁边。列表中的任何选项都绝不允许盒子在任何滚动位置与其锚点重叠:一个空间耗尽的选项会远离锚点溢出,永远不会被移到锚点上,因为在滚动面板内 Chrome 在面板滚动时不会重新选择层的选项,所以一个可能被推到触发器上的层会停留在那里。Chromium 在层自身位置之后最多尝试五个回退方案,因此合并列表取代标准顺序,而非扩展它。内容在某个侧面合适的层会在那里保持自己的尺寸;只有内容比两侧空间都高的层才会按空间设定尺寸。没有任何选项会按剩余空间来设定尺寸,因为浏览器只要某个选项仍然合适,就会让一个打开的层保留在它最后使用的那个选项上:当锚点移动时,层会移动到现在更宽敞的一侧,而不是缩小成一条细缝。在滚动过程中,仅由 CSS 锚点定位来放置层:运行时不做任何布局读取、不强制任何布局,也不会让引擎重新选择选项。当滚动停止时,运行时会重新选择一次层的位置,因此被滚动带到边缘的层不会停留在屏幕外。当
scrollend事件在锚点的任何滚动祖先(包括页面)上触发时,滚动即停止;每次此类事件后的第一个绘制帧中执行那一次重新选择。在 Chromium 中,scrollend随每个滚轮步进触发;读取在每次scrollend之后等待一个绘制帧,因此长时间滚轮滚动会多次重新检查;滚动本身期间不进行任何读取。如果浏览器最低版本不支持scrollend(Safari 26.2 之前),则在那些祖先上 150 ms 内没有scroll事件时,执行相同的单次重新选择;滚动监听器只启动计时器,不读取任何内容。任何滚动处理程序中都不进行布局读取(DEC-8)。「不遮挡」检查——读取层已定格的盒子(不含其入场动画应用的变换),判断盒子是否覆盖其锚点,或者当锚点在视口内时,是否在块轴上离开了视口——仅在层显示或重新挂载时、在 ResizeObserver 报告时(层的尺寸、内容的尺寸、锚点的尺寸,以及当调用方在层保持打开状态下替换锚点元素时替换锚点的尺寸)以及窗口大小改变时运行。滚动过程中的任何帧都不会重新检查它,也没有观察者会监视一个未改变大小却移动的触发器。一次失败的检查会在同一个任务中根据合并列表重新放置层,不进行绘制,也不关闭它。层及其内容的每个 CSS 动画和过渡都会保留引擎在其自身及其 effect、其 timing、关键帧、播放与替换状态及其时间上暴露的每个可写成员。有三样东西不被保留:Animation 和 effect 对象(浏览器会替换它们,连同它们的监听器和 promise,并触发 cancel 与 start 事件)、已结束动画的 start time(其持有的 end time 被保留)、以及过渡自身的对象(脚本动画会接管它,因此它不会触发transitionend)。层通过 CSSoverflow-y: auto滚动它无法显示的内容,且不进行 overscroll 包含,运行时不会读取任何内容来决定这一点:一个完全合适的层上方滚轮仍然会滚动页面,而一个很高的层在其末尾的滚动会像原生滚动一样链接到页面(FR3)。component:Tooltip记录了这对层内内容意味着什么:它总是一个滚动容器。运行时同时编写这两个顺序;组件不会向锚点模式层传递自己的任何回退方案。 - FR5 — 屏幕外的锚点保持原位。 锚点已离开视口的层不会滑动。它保持翻转给出的位置和自身的尺寸,直到锚点返回(DEC-3)。
- FR6 — 应用在
LayerProvider上声明一次浮动栏。 应用若让一个持久栏浮在视口边缘上方,则通过LayerProvider的inset——blockStart、blockEnd、inlineStart、inlineEnd,每个都是像素数字或 CSS 长度——按逻辑边缘声明其范围,与 provider 的toast配置并列。每个边缘都默认为零。每个声明的边缘都会为该 provider 下每个锚定层的该边缘 gutter 加上相应值(FR1),并让 toast 视口移动相同的量,因此一个栏只需声明一次,二者都会避开它(DEC-5)。toast.inset的某个边缘在设置时,会替换 provider 在该边缘上对 toast 视口的值。没有 provider 的层或 toast,其渲染效果与位于带默认 inset 的 provider 下的层或 toast 完全相同。声明会到达层所在的任何位置——从 JSX 位置 portal 出去的层与就地托管的层收到的方式相同。嵌套在另一个 provider 下的 provider 在其他方面是惰性的,但如果某个嵌套 provider 声明了一个 inset,它会为其子树中的锚定层收窄可用空间;toast 视口属于根 provider,并读取根的声明。inset 是应用状态,不是主题值(DEC-4)。 - FR7 — 消费者继承;消费者自身的尺寸规则无法击败上限。 每个通过
useLayer(锚点模式)或通过usePopover渲染的组件都会获得 FR1–FR6 和 FR8–FR10,无需更改记录,也没有可传递的选项。设置自身最小尺寸的组件——触发器匹配、作为最小值应用的menuWidth——会将该最小值与
runtime 的上限表达式,因为否则一个 CSS 最小值会压过最大值。
- FR8 — 第一帧就是已确定的帧。 图层 MUST NOT 在它即将纠正的几何位置上绘制。在本记录下,图层几何的每个输入——gutter、上限、声明的 inset、fallback 顺序——都在产生该渲染的同一帧内由浏览器的样式和布局解析;runtime 在绘制之后不会测量任何东西来应用这些输入。滚动期间,CSS 锚点定位会放置每个 anchor-mode 图层:没有滚动帧会读取布局或为某个图层强制布局,runtime 也不会在滚动途中对选项做出新选择(FR4)。滚动一旦停止,它会在停止后的第一个已绘制帧中重新选择一次图层的位置(FR4、DEC-8)。锚点是否在视图中(FR5)会在图层首次绘制之前读取,此后只在锚点可见性变化时读取;因此,在锚点已经位于视图之外时打开的图层,会从它的第一帧起就保持原状。runtime 自己维持这一保持状态,而不是将它交给 CSS:position-visibility: anchors-visible 会隐藏图层,而不是保持它;在页面滚动时,它不会隐藏一个锚点离开页面的 top-layer 图层。对于保持锚点清晰(FR4)的图层,不遮挡检查只在图层显示或重新挂载时、在 ResizeObserver 报告时以及窗口调整大小时运行,绝不在每个滚动帧运行;这些读取中的每一次都会在下一帧绘制之前完成,而窗口调整大小的读取会保留,因为调整大小不是滚动路径。runtime 不轮询任何内容。当图层打开时声明的 inset 发生变化,图层和声明会在同一帧内变化。应用测量自身栏并声明结果之间的延迟属于应用自身;runtime 渲染所声明的内容,并在声明之时渲染。除了 FR10 的键盘封顶变更(该变更等待键盘到达或一次按压完成)之外,先绘制再移动都是对本契约的破坏,而不是质量问题。软件键盘的封顶(FR9)是第三次观察。它仍然是 runtime 的职责,因为 iOS Safari 没有对应的 CSS:env(keyboard-inset-*) 仅 Chrome 支持,且 iOS Safari 不支持 interactive-widget viewport 键。它从图层自身的盒子(不含其入场变换)读取,正如 FR4 读取它那样,因此进行中的入场永远不需要第二次读取:在图层随键盘弹出而打开时的首次绘制之前、在键盘移动时(FR10),以及在将 runtime 在图层打开期间换入的图层元素提交进来的提交中。
- FR9 — 软件键盘会对会延伸到其下方的图层进行封顶。 当软件键盘覆盖视口底部时,一个 block-end 边缘会延伸到键盘下方的 anchor-mode 图层会保持其 block-start 边缘,并对其 block 尺寸进行封顶,使该边缘位于键盘上方 10 px,即 UIKit 在 popover 下方保持的间隙。其内容在图层盒子内部溢出,由组合组件滚动,正在键入的字段保持在视图中。当有人在封顶生效后在图层内部按压、触摸或滚动滚轮时,内容会停留在他们放置的位置。后续键盘变化会再次将字段带入视图。键盘不会到达的图层,以及 fallback 顺序将其 block-end 边缘保持在触发器上方的图层,保持原样。键盘的高度是键盘模块的单一高度(architecture:react-component-runtime INV11);没有图层自行测量键盘。封顶合并到 block 轴封顶(FR2 或 FR3,以哪个封顶 block 轴为准)中,因此图层盒子以及其中被该定义封顶的每个表面会一起收缩。每个图层在自己的元素上携带自己的封顶:在已封顶图层内部打开的图层只针对自己的盒子被封顶,绝不会被宿主的封顶约束。一旦软件键盘弹出,runtime 还会在每个打开的 anchor-mode 图层上写入其 block-end inset,与封顶并列:键盘高度加上 10 px 间隙。该 inset 保持其最大值直到图层关闭。该 inset 是一个私有的自定义属性,只有 runtime 写入,绝不是 public API,fallback 顺序也从不读取它。一个在 block 轴上自行定位的图层(例如 Selector 的 selected-item overlay)会结束于 inset 标记的线之上。它会在发布 inset 的提交中移动,在封顶读取其盒子之前。键盘落下后会将其留在原地。
- FR10 — 键盘封顶在键盘隐藏变化之处改变。 盒子的高度无法在合成器上改变,因此封顶在每次键盘移动时改变一次:当上升的键盘到达时、当下降的键盘开始下落时立即改变,并且对于不移动而变化的键盘也立即改变。在图层内部进行中的按压下,会使图层移动的变化会等待该按压的 click 事件。
平台支持¶
- 支持的特性/引擎下限:CSS Anchor Positioning(
position-area、position-try-fallbacks、anchor-size())和 Popover API,正如architecture:layer-runtime对 anchor mode 已经要求的那样。FR5 需要 runtime 知道锚点是否在视图中;首次绘制前的同步读取加上打开期间的观察,是图层自己拥有的机制。 - 不支持的行为:没有锚点定位时,FR1–FR3 仍将图层的尺寸约束到视口;FR4 和 FR5 没有可供排序的 fallback,也不适用。这是
spec:AST-003FR22 所描述的降级行为,而不是等价替代。 - 浏览器证据:在真实 Chromium 中,针对下方每个 Layer story,在桌面视口和手机视口下渲染的几何——图层相对于视口的边界矩形、其 gutter、以及 flip 或 slide 前后的尺寸;以及针对 FR8,在打开提交后同步读取并与已确定帧比较的首次绘制帧矩形。生成的 style 字符串证明该定义是共享的;它们不能证明图层落到了屏幕上,也不能证明它没有移动。
当前状态影响¶
architecture:layer-runtime (current)¶
当此功能发布时:
- 定位:将“Popover 在此几何之上添加组件特定的视口尺寸和溢出行为。这些约束并非通用的 Layer 行为。”替换为 FR1–FR6 作为发布后行为中的 gutter、上限、回退顺序和应用声明的 inset;说明当锚点在视口内时,滑动适用于所有对齐方式,而屏幕外的锚点保持不动。
- INV3 变为“锚点模式拥有逻辑放置、回退和视口 inset;自定义模式拥有其几何;固定模式拥有显式坐标。”
- 为 FR1 和 FR7 添加一条不变式:gutter 只有一种定义,每个锚点模式的 layer 都继承它,消费者的最小值受其钳制。
- INV10 仍然成立,并如实说明:
LayerProvider是配置——Toast 和视口 inset——而不是 layer 宿主;layer 从 provider 的上下文中读取 inset,并将其携带在自身之上;因此,宿主永远不会决定它是否到达,也没有任何 layer 通过它解析放置。 - 为 FR8 添加一条不变式:任何几何输入都不会在绘制之后被测量再应用;第一帧绘制出的帧就是最终确定的帧;没有滚动帧会为 layer 读取或强制布局(DEC-7、DEC-8)。
- 定位和 INV12 遵循 FR4、FR8、DEC-7 和 DEC-8:从第一帧起就有一份合并列表,使用 CSS overflow 决定 layer 是否滚动,不观察移动但不改变大小的锚点,并在滚动停止后的第一帧绘制中只检查一次。
- INV11 和 INV12 增加软件键盘的上限(FR9)和 FR10 的时序:当键盘移动时,从 layer 自身的盒子中读取上限,且不包含其进入变换;每次键盘移动只改变一次,这是唯一被允许的“先绘制再移位”情形。
- 拥有代码:添加持有 gutter 和上限表达式的模块,将
LayerProvider作为已声明 inset 的拥有者,以及拥有打开中的锚点模式 layer 上软件键盘上限的模块。 - 变更耦合:键盘上限的变更会验证上限的时序、在键盘弹起时打开的 layer,以及它不去影响的那些 layer。
- 变更耦合:定位行已经列出了视口边缘回退;添加显式尺寸、内容尺寸、两侧均不适合、屏幕外锚点等状态,以及应用声明的 inset。
- 验证:将 Layer stories 作为新不变式和 INV3 的渲染证据;明确指出显式宽度 story 的失败信号(layer 比其给定尺寸更窄)。
deciding_specs:添加spec:AST-059。
component:Popover (current)¶
当此功能发布时:
- 所有权边界,Owns(拥有):从第三个要点中移除“视口适配、安全区域 gutter”;它保留焦点目标、匹配触发器尺寸、条件式内部滚动和测量生命周期。
- 所有权边界,Does not own(不拥有):添加视口 inset——gutter、尺寸上限、回退顺序、应用声明的 inset——由
architecture:layer-runtime拥有。 - 公共概念,“Placement and fit(放置与适配)”:变为“Placement and preferred size(放置与首选尺寸)”——Popover 拥有该偏好(显式宽度,否则为触发器最小宽度);上限和适配归属于 layer。
- FR3 已退役;其声明移至本记录的 FR2 和 FR3。
- ORD2 变为:“显式宽度优先于触发器匹配。在没有显式宽度时,Popover 偏好触发器最小宽度,并由 layer 的上限(
spec:AST-059FR7)钳制。”关于视口和安全区域上限的句子被移除。 - ORD3 已退役;视口适配归属于 layer。ORD4 的溢出评估遵循 layer 的上限。
- AV4 从 Popover 的变量中移除“可用视口尺寸”。
- 设计关系:Popover surface“承载滚动、焦点和对话框行为”;适配被移除。
- 验证映射:FR3/FR4 行变为仅 FR4;其 Storybook 引用指向 Layer stories 以获取几何信息,并保留 Popover 的溢出 story 用于滚动。
width是普通的 CSS 宽度,由 layer 的上限钳制。Popover 唯一的分支是它自己的——显式宽度,否则为触发器匹配的最小宽度——其中没有任何内容依赖于该宽度是否适合放在触发器旁边。
其他消费者无需记录变更即可继承的内容¶
DropdownMenu和DropdownMenuSubMenu读取运行时的 gutter。显式的menuWidth是一个由视口上限(FR7)钳制的最小值,绝不会由触发器旁边的空间钳制;菜单的 300px 块级上限是 FR3 允许的更低上限。BaseTypeahead读取运行时的 gutter;menuWidth及其触发器匹配最小值都由视口上限(FR2、FR7)钳制。PowerSearch使用视口上限(FR7)钳制其 400px 编辑器下限。ComplexSelector保留 480px,TopNavMegaMenu保留其触发器下方的空间,作为放置轴上的更低上限(FR3)。Tooltip、HoverCard、ContextMenu、Selector 系列、TabMenu、TopNav 菜单和日期输入通过锚点模式或usePopover渲染,并在自身不做任何更改的情况下获得 FR1–FR5。适合的 layer 保持不变;会溢出视口的 layer 会被上限约束、翻转或滑动。Tooltip 还保持其锚点不被遮挡(FR4),并滚动高于所给空间的内容(FR3)。ToastViewport在每条边上按 provider 的 inset 定位自身;它自己的inset保持其作为逐边覆盖(per-edge override)的含义(FR6、DEC-5)。
验证¶
Stories 位于 Core/Layer 下,命名为“Viewport inset: …”,并在 story play guard 下于真实 Chromium 中以两个视口运行:1280×900 和 390×844 手机视口;每一条都是一个人可以打开并查看的声明。这些 stories 中的每一个都会在打开提交(opening commit)后同步读取 layer 的矩形——即第一帧绘制的几何——并在两个动画帧后再次读取,只要有任何差异就失败(FR8)。Popover 的 stories 只保留属于 Popover 的内容:其触发器匹配偏好、滚动、焦点、关闭行为以及 surface 样式。一个带有可拖动触发器以及实时宽度、放置和对齐控件的 playground story 用于探索;它不作为任何一行的证据。
| 契约 | 验证 | 代表性状态 | 变异或失败预期 |
|---|---|---|---|
| FR1, FR7 | 一个间距模块;通过源码扫描检查锚点模式图层中是否存在第二个间距或 100% 的跨幅上限;两个视口下均有 “the gutter” 故事 |
每个边缘都有默认间距;触发器旁边紧贴边缘的换行图层 | 锚点模式图层中存在第二个间距常量,或图层位于 16px 间距内 |
| FR2 | 两个视口下均有 “explicit size near an edge (352px)”、“content-sized, fits beside the trigger”、“content-sized, does not fit beside the trigger”、“neither side fits” 等故事;Popover 和 DropdownMenu 套件中的 clamp 字符串 | 352px 端对齐,触发器距边缘 45px;一个较短的内容自适应图层;一段比手机更宽的不可换行文本;手机上一个宽度为 1000px 的图层,其上限为 358px | 图层窄于 min(asked, cap),任何视口下图层框宽于上限,或上限中使用锚点跨幅的 100% |
| FR3 | 在两种视口下,Story "taller than the viewport";运行时在每个锚点模式层上的 viewport-fit 样式 | 内容高度 2000px | 层盒的块尺寸超过视口减去间距 |
| FR4 | 在两种视口下,Story "content-sized, does not fit beside the trigger"、"trigger near an edge flips"、"neither side fits"、"trigger near the bottom flips above"、"wide layer, trigger near the bottom" | 在内容尺寸和显式尺寸下翻转为末端对齐;一个 1000px 的层滑动到适合它的间距内;仅在顶部有空间时发生块向翻转;在内联轴也被限制时发生块向翻转 | 层被压缩进跨度内,翻转边缘偏离触发器边缘,层在任一轴上超出间距范围,或层被留在没有空间的一侧 |
| FR4、Tooltip | TooltipTallContent 和 TooltipTallContentTracking 真实引擎套件(Chromium、WebKit),分辨率 1280×720 和 390×700;运行时的 anchor-clear 单元测试套件;在 Chromium 中对一个贴合型(fitting) tooltip 和一个高型(tall) tooltip 各执行一次滚轮操作和一次键盘操作,前后各一次 |
页面中部的 60 行 tooltip(在其旁边);一个贴合型 tooltip,其侧方空间在滚动过程中变小(它会翻转到对侧,而不是留在旁边);在手机上,触发器位于上半部或下半部(空间更充足的一侧);一个贴合型 tooltip;内容增长、宿主移动、触发器因布局而移动、页面滚动以及滚动面板内部滚动使触发器越过边缘、窗口缩放、触发器被替换;在贴合型 tooltip 上滚动滚轮、在到达高型 tooltip 底部时滚动滚轮;用 Tab 键遍历一个包含贴合型 tooltip 和可滚动 tooltip 的页面 | 在翻转对侧能够容纳的情况下,仍移动到触发器旁边;在任意帧中都覆盖触发器,包括面板内部滚动的每一帧;在指针静止时关闭、离开视口、无法滚动,或贴合型 tooltip 发生移动;滚轮在贴合型 tooltip 上滚动时页面不滚动,或高型 tooltip 滚动到底时未将滚动链式传递给页面;CSS overflow-y: auto 在 Chromium 中增加了 Tab 焦点位 |
| FR5 | 故事“锚离开视口”和“锚在层打开时已处于屏幕外”;运行时的锚可见性单元测试套件 | 水平滚动将触发器带出视野且层保持打开,随后再滚回;层打开时其锚已在屏幕外 | 锚消失后层向视口边缘滑动、改变大小、未随锚一起返回,或固定在边缘处打开 |
| FR6 | 用例“app-declared inset (floating bar)”和“layer portaled out of its JSX position”;LayerProvider 和 ToastViewport 单元测试套件 |
一个声明为 inset={{blockEnd: 80}} 的 80px 栏;同一 provider 下的一个 toast;一个 toast.inset 覆盖;无 provider;一个被托管到其渲染段落之外的 layer |
如果 layer 或 toast 最终位于栏下方、未设置的边缘移动了任何内容、toast.inset 边缘停止覆盖、无 provider 时的几何形状与默认 provider 的不同,或者被 portal 出去的 layer 丢失了 inset,则失败。 |
| FR8 | 上述所有用例(首帧与稳定后比较);以及用例“inset changes while the layer is open”、“layer opens in the frame the inset arrives”、“inset measured by the app”、“anchor already off-screen when the layer opens” | 在 layer 打开时,provider 的 inset 由 80 变为 160;一个在 provider 首次提交时以打开状态挂载的 layer;一个由应用在绘制前测量并声明的栏;一个在打开时位于屏幕外的锚点 | 首帧的矩形与稳定后的矩形不同,或者声明变更后的首帧尚未处于新的几何位置。 |
| FR4、FR8 滚动(DEC-7、DEC-8) | 针对 DEC-7 的七行中的每一行,在真实 Chromium 中提供前后对比证据;一个页面滚动和滚动面板内滚动的性能跟踪(该滚动会将工具提示的触发器带过滚动边缘),并统计前后每个滚动帧的强制布局次数;运行时的 anchor-clear 单元测试套件,用于 don't-cover 检查运行时的场景;工具提示套件的滚动边缘用例;对于每次滚动,统计在 scrollend 之后重新拾取(re-pick)时的强制布局次数,以及在不支持 scrollend 时使用 150 ms 回退方案的强制布局次数 |
一个已打开的工具提示,其触发器被页面滚动带出页面并带回;同一情况发生在滚动面板内;图层的显示(show)、重新挂载、ResizeObserver 报告和窗口大小调整;一个 top-layer 图层的锚点离开页面;一次滚轮滚动,结束时触发器位于滚动边缘 | 对于某个图层,在与锚点可见性变化不同的滚动帧中发生强制布局或布局读取;在滚动期间进行 don't-cover 检查、scroll 或 scrollend 读取,或强制重新拾取;观察者检测到触发器移动但未调整大小;当锚点离开页面时,图层滑动或消失而不是保持原位;滚动边缘用例失败、布局读取在滚动期间或滚动处理程序中出现,或重新拾取在停止后的第一个绘制帧之前运行 |
| FR9 | useLayerKeyboardClearance.test.tsx;在 Chromium 和 WebKit 中使用替代键盘对 Popover 进行键盘行为浏览器验证;iOS 模拟器;对 Selector 的键盘内缩(keyboard inset)进行浏览器验证 |
一个位于触发器下方、带有输入框的较高的 Popover;打开时键盘已弹出;一个较短的图层;一个位于触发器上方的图层;一个滑动到键盘上方的 Selector 浮层 | 一个设置了高度上限的图层,其底部结束于键盘下方或高出键盘超过 10 px;一个未被触达却发生变化的图层;一个底部固定却发生移动的图层;或一个将键盘本身纳入测量的图层 |
| FR10 | useLayerKeyboardClearance.test.tsx;Popover 的键盘浏览器验证 |
键盘升起时(到达前和到达后);键盘落下;键盘立即变化;键盘落下时点击“保存” | 在键盘升起时写入的 cap,在键盘落下时保留,或在点击发生前的按压中被移除 |
| FR1 安全区 | 设备运行:env(safe-area-inset-*) 仅由真实设备设置,Chromium 模拟不会填充它,因此没有 Storybook 故事可以展示它。 |
一侧有刘海的横屏手机 | 位于刘海下方的一层 |
验证缺口 — VG1. 一个不得不滑动的层(它在触发器的两侧都放不下),当它的锚点离开并返回后,可能会回到与锚点起始对齐且超出屏幕的状态,直到下一次布局:Chromium 在离屏固定被撤除时不会重新运行滑动逻辑。“锚点离开视口”的场景只在层能放在触发器旁边时断言了返回行为。FR5 的保持行为得到了验证;滑动后的返回行为没有。
第一帧断言在提交之后、任何动画帧之前观察样式和布局;它无法观察到仅合成器(compositor)产生的效果,而且由该记录之外的输入(应用在绘制后重新布局自己的栏)产生的位移会被报告为应用自身产生的。
决策日志¶
DEC-1 — 层拥有视口 inset;Popover 是它的一个应用¶
Reference: spec:AST-059/DEC-1
Decider: Cindy Zhang, 2026-10-03
层运行时拥有视口 inset 行为、其规范及其场景。Popover 是层的一个应用,在上层添加了样式考虑。一次定义的边距不会漂移;一次编写的回退列表不会被某个组件为了自身场景而扩展;一个人从菜单、popover、typeahead 和 tooltip 中看到相同的边缘行为,除了 FR4 赋予 tooltip 的锚点清除顺序——该顺序也由运行时编写。
否决项:每个组件导入一个共享常量,同时保留自己的适配样式——这消除了漂移,但保留了所有权问题。
DEC-2 — 内容大小的层能换行就换行,不能换行就移动¶
Reference: spec:AST-059/DEC-2
Decider: Cindy Zhang, 2026-10-03
内容大小的层通过将其内容包裹进触发器旁的空间来适配触发器旁边,就像自动宽度的定位框自行表现的那样。一个无法收缩的尺寸——显式宽度、menuWidth、不换行的标签——会保持其尺寸并移动:它翻转到另一侧,当两侧都放不下时,它会沿着对齐轴滑入视图(FR4)。任何尺寸都不会被限制到触发器旁的空间范围,因此运行时无需知道尺寸是否被给定,Popover.width 和 DropdownMenu.menuWidth 是普通 CSS 尺寸,仅受视口约束。
否决项:强制每个内容大小的层取其 max-content 宽度,从而总是移动而不是换行——触发器旁的文字会打开得和视口一样宽。
DEC-3 — 对齐的层不会朝着屏幕外的锚点滑动¶
Reference: spec:AST-059/DEC-3
Decider: Cindy Zhang, 2026-10-03
滑动(FR4)服务于一个可见的触发器,其层在两侧都放不下。一旦锚点离开视口,层保持翻转所给它的位置,并保持其尺寸(FR5)。如果层继续滑动,它会把自己固定到边缘最窄的条带中,为一个没人能看到的锚点放弃片刻之前还拥有的空间。该条件应属于排序规则,而不是留给回退列表自然产生。
已拒绝:当锚点离开时关闭图层——这是关于陈旧性的产品决策,而非几何规则,并且它会从正在阅读的人那里夺走图层。
DEC-4 — 应用的浮动条是应用状态,而非主题值¶
引用: spec:AST-059/DEC-4
决策者: Cindy Zhang,2026-10-03
浮动在视口边缘上方的持续可见条,是应用外壳的一个事实——它是否存在以及高度是多少——而共享同一个主题的两个应用可能在这方面不同。因此,应用将其声明为 provider 配置(LayerProvider.inset,FR6),而不是通过 defineTheme。不存在 layer 主题目标:主题目标是组件的解剖学词汇,而图层本身没有可绘制的解剖结构;沟槽是几何问题,而非视觉处理。
已拒绝:通过 popover 主题目标传递这个 inset——一个组件的主题会支配所有其他使用者。已拒绝:使用按图层的 prop——该条会在每个界面上被重复声明,且两处可能不一致。已拒绝:将手写的 CSS 自定义属性作为公共表面——无类型、在 toast 旁边无法被发现,也无法携带默认值。
DEC-5 — 一个声明同时服务 toast 与锚定图层;默认值为零¶
引用: spec:AST-059/DEC-5
决策者: Cindy Zhang,2026-10-03
LayerProvider.inset 是 provider 级别的声明。toast 视口以及 provider 下的每个锚定图层都会读取它,因为视口边缘的一条遮挡物是同一个物理障碍,而 provider 本来就已是应用声明边缘存在某物的位置。toast.inset 仍是 toast 专属的覆盖项:在它所设置的边缘上,它会替换 provider 为 toast 视口设置的值;因此当应用有这种需求时,toast 可以比图层避让得更多或更少。并且,在此记录之前设置了 toast.inset 的应用,其 toast 仍会精确出现在原来的位置。两者绝不会相加:相加在常见情况下会重复避让同一条遮挡条。
每个边缘的默认值都是零,这是一个有意的决定:系统已经知道设备自身的边缘,并将其承载在沟槽中(FR1、env());只有应用知道自己绘制的遮挡条,而非零默认值会以任何人都无法在该应用中找到的理由,移动每个应用中的每个图层。没有 provider 的表面就是处于默认 provider 之下的表面。
已拒绝:一种 toast 无法覆盖的共享 inset——如果 toast 必须避让某个锚定图层可能覆盖的控件,它将无路可走。
DEC-6 — 运行时将图层封顶在软键盘上方,并保持其起始边缘¶
引用: spec:AST-059/DEC-6
决策者: cixzhang,2026-10-26
会跑到软键盘下方的图层,会被图层运行时一次性对所有锚定模式图层封顶,使用来自键盘模块的单一高度:键盘会像沟槽一样收窄视口,而若由某个组件单独应用规则,则会让其他所有图层都留在键盘下方。被封顶的图层保持其 block-start 边缘,并在键盘上方 10 px 处结束,与 UIKit popover 的做法一致。
已拒绝:将键盘作为声明的 block-end inset(FR6),因为回退顺序会将 block inset 应用到两个 block 边缘(FR4)。
DEC-7 — 滚动期间,CSS 放置锚定图层;运行时保留事件驱动的读取¶
引用: spec:AST-059/DEC-7
决策者: cixzhang,2026-11-06
滚动期间的放置属于浏览器的锚点定位。靠近该路径的每个运行时机制都有一种处理方式:
- CSS 承担它:一个移动但不改变大小的触发器无需观察者,因为锚点避让选项从一开始就在图层的列表中;滚动期间对选项的选择来自一个合并的列表,位于 Chromium 的五个回退之内,这些选项从不与触发器重叠,并按首选侧、翻转、触发器旁侧,然后是空间足够的一侧依次尝试;因此一个在其一侧失去空间的合适图层,会在移动到触发器旁侧之前翻转到相反一侧,且无需强制做出新选择;而图层是否滚动属于 CSS overflow,而不是一次读取(FR4)。
- 滚动路径之外:don't-cover 检查在显示时和尺寸变化时运行,绝不会每滚动帧运行(FR4、FR8)。
- 运行时保留的事项:视口外保持(FR5)、窗口调整大小时的读取、键盘避让(FR9),以及滚动停止后的单次重新选择(DEC-8)。
仅靠 CSS 的两个实测缺口决定了保留项和列表的形状。在滚动面板内部,Chrome 不会在滚动期间重新选择 CSS 锚定图层的选项,因此图层可能被推到触发器上并停留在那里:所以每个选项都通过构造保证与触发器保持距离,而 don't-cover 检查仍只在显示时和尺寸变化时运行。在页面滚动时,position-visibility: anchors-visible 不会隐藏其锚点离开页面的 top-layer 图层;而在它适用的地方,它是隐藏而非保持:因此保持仍是运行时的事件驱动行为,每帧没有额外工作。窗口大小调整不属于滚动路径。iOS Safari 没有针对软键盘的 CSS(env(keyboard-inset-*) 是 Chrome 独有的,且 interactive-widget 视口键在那里不受支持),因此键盘避让仍然保留。因此,一次滚动只会在锚点可见性发生变化的帧以及滚动停止后的帧中,给运行时带来布局工作(DEC-8)。
已拒绝:仅靠 CSS 处理每一项(即上述两个缺口),以及在滚动期间逐帧检查(每次都会在每个滚动帧中强制布局)。
DEC-8 — 锚定图层重新选择一次,在滚动停止后的第一个绘制帧中¶
引用: spec:AST-059/DEC-8
决策者: cixzhang,2026-11-06
锚定图层会在滚动停止后的第一个绘制帧中重新选择一次位置;滚动期间不读取任何布局(FR4)。Chromium 在滚动期间不会再选择 CSS 锚定图层的选项,否则一个被滚动带到边缘的 tooltip 原本会停留在屏幕外。根据在 Chromium 中的测量,使用这种重新选择方式,一次滚动会产生 5 到 20 次强制布局;而如果每一帧都重新选择,则为 12 到 27 次;并且 tooltip 套件的边缘情况可以通过。
已拒绝:仅靠 CSS(提示框会留在屏幕边缘之外),以及在每一滚动帧中重新挑选(图层会在滚动中途弹跳)。
DEC-9 — 脚本绝不移动图层以跟随其锚点¶
参考: spec:AST-059/DEC-9
决策人: cixzhang,2026-11-10
锚定图层仅通过 CSS 锚点定位(position-anchor、position-area、anchor() 和 @position-try)跟随其锚点。没有脚本会移动图层以使其保持在锚点上:任何滚动、调整大小、观察器或动画帧处理器都不会根据测量得到的锚点或图层矩形,写入图层的 top、left、inset、translate 或 transform。DEC-7 保留的出屏保持与重新挑选,是在图层的 CSS 选项之间进行选择,或将其保持在原位,不写入任何坐标。四种使用场景不受此规则约束,因为它们都不跟随锚点:固定模式的坐标——调用方从事件(如上下文菜单按下)中一次性设置;一次性播放后即结束的进入或退出变换;软件键盘的抬升(FR9、DEC-6)——它写入 inset 以保持图层避开键盘,而非跟随其锚点;以及针对不支持锚点定位的浏览器的简化回退方案(spec:AST-003 FR22),该方案没有锚定几何。
负责人就弹出层滚动卡顿问题表示:“我们应该避免在 js 中手动重新定位图层以贴合锚点,并在 speed 中禁止此类策略,因为我们一直看到这种情况发生。”
已拒绝:在受支持的浏览器中将脚本定位用作 CSS 锚点定位的回退方案(它会滞后滚动一帧并强制布局)。
DEC-10 — 图层绝不继承其触发器的按下变换¶
参考: spec:AST-059/DEC-10
决策人: cixzhang,2026-11-10
触发器的按下反馈仅缩放触发器自身的视觉。触发器打开的图层渲染在该缩放子树之外,因此按下绝不会缩放、移动或扭曲图层或其进入动画,并且图层锚定到触发器未变换的盒子上。
负责人:“由于我们在按下时缩放按钮,弹出层也随之被缩放,这让动画看起来很奇怪。我们可能需要让弹出菜单位于 scale css 之外。”
已拒绝:对图层进行反向缩放以抵消按下效果(它会滞后按下操作,并且仍会扭曲进入动画)。
开放问题¶
无。以上每项决策均为负责人所作。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx