可滚动容器行为系统规范¶
{
"scope": "global",
"triggers": {
"scrolling": ["FR1", "FR12", "FR13", "FR14", "FR15", "FR16", "FR18"]
}
}
意图¶
人们应当能够到达并滚动溢出的内容,当嵌套区域没有可滚动内容时继续滚动包含它的页面,并了解在移动时哪些内容保持固定。构建者不应需要独立协调可访问性、sticky 定位、过滚动遏制、滚动条呈现和浏览器特定的溢出行为。
本规范定义了一种感知轴的滚动容器能力。共享的工具 hooks 构成规范化的可复用行为表面,使已经拥有合适结构的组件可以直接参与。ScrollableArea 将这些 hooks 组合成一个便捷组件和参考实现;它不是获得该行为的唯一途径。
非目标¶
- 在本草案中确定最终导出的 hook 名称、prop 名称或 TypeScript 拼写;以 hooks 为先的所有权模型和
ScrollableArea参考组合已由 DEC-1 确定。 - 用 JavaScript 驱动的移动取代浏览器滚动。
- 要求自定义滚动条 DOM,或要求所有平台滚动条样式完全一致。
- 将任意的 overflow 值或独立的
overflow-x/overflow-y组合纳入公开设计系统词汇表。 - 允许内容从同一视口的非滚动轴可见地绘制出来;CSS 无法可靠提供这种组合。
- 定义 Sticky 的完整公开 API、层叠模型或视觉表现。
- 自动迁移每个当前的
overflow: auto调用点。 - 改变 Layout 的五槽位拓扑或 AppShell 对页面外壳的所有权。
术语¶
- 视口(Viewport): 其滚动偏移量移动内容的元素。
- 内容盒(Content box): 视口内的真实布局盒,无需任意后代参与即可观察其几何信息。
- 请求轴(Requested axis): 所有者打算允许滚动的逻辑轴:
inline、block或both。 - 有效滚动轴(Effective scroll axis): 满足以下条件的请求轴:其解析后的计算 overflow 值可被用户滚动,且其内容范围超出视口范围的程度大于共享容差。
- 有效滚动所有者(Effective scroll owner): 最近的、具有与正在解析的行为相匹配的有效滚动轴的祖先。
- 滚动条呈现器(Scrollbar presenter): 原生 CSS 或可选的自定义 UI,在不创建另一个视口的情况下表示视口现有滚动状态。
要求¶
- FR1 — 滚动意图使用逻辑轴。 系统必须以
inline、block或both表示滚动意图。书写方向和书写模式决定物理轴。左、右、上、下 MUST NOT 定义共享契约。 - FR2 — 滚动所有权是显式且本地的。 参与的容器 MUST 标识一个视口及其内容盒。无论该能力是通过独立组件交付,还是集成到现有组件拥有的元素中,后代 MUST 接收相同的逐轴所有者状态。
- FR3 — 有效滚动需要可滚动样式和可测量的溢出。 在读取物理几何之前,先通过视口的计算书写模式解析请求的逻辑轴。在水平书写模式中,inline 使用
scrollWidth与clientWidth比较,block 使用scrollHeight与clientHeight比较;垂直和侧向书写模式会反转这些物理测量。仅当解析后的计算 overflow 为auto、scroll或旧版overlay值,且其内容范围超出视口范围的程度大于共享容差时,该轴才有效。初始共享容差为 1 CSS 像素。单独的overflow: auto声明或多余几何信息 MUST NOT 使容器成为有效所有者。 - FR4 — 有效状态是逐轴的。 容器可以在一个、两个或零个请求轴上有效。可聚焦性、sticky 所有权、过滚动遏制、滚动条呈现和边缘状态 MUST 使用适用的轴,而不是一个无差别的
hasOverflow布尔值。 - FR5 — 实时测量观察视口和内容几何。 系统 MUST 同时观察视口盒和真实的内容布局盒。仅观察视口的
ResizeObserver是不够的,因为内容可能增长而视口自身盒子保持不变。display: contents不是有效的内容观察目标,因为它没有可靠的盒几何信息。 - FR6 — 现有结构可以提供内容盒。 已经拥有合适内容根的组件可以直接注册它。可复用行为 MUST NOT 在任意子元素周围静默插入包装器。当实现创建内容包装器时,它 MUST 记录并验证该包装器的格式化、尺寸、flex/grid 参与、百分比尺寸和固有尺寸影响。
- FR7 — 失效覆盖的不只是元素尺寸变化。 系统 MUST 在初始连接、视口或内容盒尺寸变化、请求轴或相关样式变化、以及从不可测量/隐藏到已渲染的转换之后进行测量。如果集成场景的溢出可能在两个被观察盒子都没有尺寸变化的情况下改变,则 MUST 提供显式失效路径或等效的有界信号。同一帧内的重复失效 MUST 合并为一次测量。
- FR8 — 不可测量不等于适合。 断开的、
display: none的或零几何的视口 MUST NOT 被当作内容适合的证据。实现可以保留最后有效状态或暴露内部未知状态,但 MUST 在视口变为可测量时重新测量。 - FR9 — 状态更新是稳定的。 共享观察器 MUST 仅在有效轴或请求的边缘信息发生变化时发布新状态。测量 MUST 收敛,不产生溢出/滚动条反馈循环,包括在原生滚动条占用布局空间的平台上。
- FR10 — Sticky 按轴对照有效所有权解析。 block-start 或 block-end 的 Sticky 参与者 MUST 使用最近的有效 block 所有者。inline-start 或 inline-end 的参与者 MUST 使用最近的有效 inline 所有者。非溢出的候选者以及仅在其他轴上有效的候选者 MUST 被跳过。Sticky 在流式内容中的任意放置 MUST 仍然可行;固定的页眉/页脚槽位不是通用替代方案。
- FR11 — 原生 CSS sticky 是有条件的实现细节。 当浏览器的最近 CSS 滚动容器同时也是系统在请求轴上的有效所有者时,可以使用原生
position: sticky。在 CSS overflow 轴耦合导致这些所有者不一致的情况下,实现 MUST NOT 依赖原生祖先选择。本规范不选择回退定位机制。 - FR12 — 键盘访问与有效滚动一致。 有效滚动内容 MUST 保持可通过键盘访问,符合 WCAG 2.1.1 的要求。将键盘滚动分配给视口的交付表面 MUST 仅在至少一个适用轴有效时将其加入 Tab 导航顺序,并且 MUST 提供适当的 role 和可访问名称。role 为
group,除非视口本身是地标。名称是拥有该视口的组件的可访问名称:调用方的标签,否则为该组件的翻译默认值。如果视口是页面中该 role 的唯一地标(例如唯一的main),则可以依赖该 role 且不携带名称;如果视口是该 role 的多个地标之一,则 MUST 被命名。当现有可聚焦后代能够为键盘用户提供对所有溢出内容的访问时,集成方案也可以依赖该后代。在共享的contentOrViewport模式中,被命名的视口在有效可滚动期间 MUST 保留tabIndex=0。在前向键盘 Tab 进入时,hook MUST 检查第一个顺序后代一次,并且只能委托给保留原生滚动按键的原生链接或按钮。它 MUST NOT 跳过一个被排除的第一个目标去到达后面符合条件的元素。复合组件、嵌套滚动所有者、可编辑表面和拥有导航键的 role MUST 保留视口停止点。从被委托的第一个子元素反向遍历 MUST 跳过视口且不形成循环。指针和编程式聚焦 MUST NOT 委托。每次键盘进入时 MUST 重新计算资格,而不对键盘资格进行持久的子树或祖先观察;现有几何观察仍受 FR5–FR9 管辖。两条路径 MUST 都保留清晰的可访问命名,以及对完整滚动范围的原生 Arrow/Page 访问。工具提示是唯一的例外:对于视口来说过高的内容在其中滚动,但没有键盘路径。在 ARIA tooltip 模式下,工具提示从不获得焦点,其触发器在显示期间保持焦点;完整内容通过触发器的可访问描述对辅助技术保持可用;较长或关键的内容应放在 HoverCard 或 Popover 中,这些组件会获得焦点;而另一种选择——将溢出留在视口之外——则无法触达任何人。 - FR13 — 失去溢出不会移动焦点。 如果获得焦点的视口停止溢出,系统可以将其从未来的顺序导航中移除,但 MUST NOT 仅因几何变化而移动或模糊当前焦点。
- FR14 — 滚动链是默认行为。 当当前区域在请求方向上没有可滚动余量时,嵌套的滚轮、触摸和键盘滚动 MUST 继续传递给祖先。遏制策略可以停止滚动链,但其
overscroll-behavior效果 MUST 仅在当前溢出的轴上生效。这避免了那些对非溢出overflow: auto元素也遵守遏制规则的引擎中出现死滚动区域。在手指下的触摸呈现中,拖动手势归属于谁,在开始时一次性决定(spec:AST-094FR14)。 - FR15 — 原生滚动条是默认呈现。 默认呈现器 MUST 保留原生滚动,并在支持的地方使用基于标准的 CSS,例如
scrollbar-width、scrollbar-color和scrollbar-gutter。不支持的声明 MUST 回退到平台滚动条,而不改变滚动所有权或访问方式。 - FR16 — 自定义滚动条是可选的呈现。 自定义轨道或滑块可以表示现有视口,但 MUST NOT 创建第二个滚动容器、替换原生滚动机制或维持独立的事实来源。它 MUST 使用与视口相同的有效轴、范围、偏移、书写方向和强制颜色状态。在没有任何等效可见且可操作的提示的情况下隐藏原生滚动条,不是通用默认做法。
- FR17 — 轴组合是封闭的。 系统 MUST NOT 暴露
visible、clip、hidden、auto和scroll的任意组合。当与另一个轴上的非visible值配对时,CSS 会把visible计算为auto,把clip计算为hidden,因此这些表面组合并不保留独立轴的语义。必须从非滚动轴逸出的内容需要单独的结构或 Layer。 - FR18 — 嵌套所有权是确定性的。 在适用轴上最近的有效所有者胜出。正交的嵌套区域可以共存。同轴嵌套 MUST 默认保留滚动链,并且 MUST 是拥有组件契约中的有意设计,而不是由偶然的溢出样式产生。
- FR19 — Table 可以集成而非包裹。 Table 可以在其现有滚动包装器上采用该能力,从而使列宽、键盘访问、滚动阴影、sticky 列和 sticky 页眉共享同一个视口。Table MUST NOT 仅仅为了参与而要求单独的公开 ScrollableArea 组件。任意的外部包装器无法满足 Table 的内部所有权契约,除非 Table
显式接受并协调该所有者。
- FR20 — 参考组件集成容器几何信息。 ScrollableArea MUST 发布其内容盒的实际逻辑内边距;未请求内边距时使用零。其视口 MAY 仅通过显式的 full-bleed 选项消费继承的内边距;单独的滚动能力 MUST NOT 逃逸父容器。
- FR21 — 适配滚动意图并不蕴含 Sticky 包含。 对于所请求的轴没有多余几何空间的参与视口,MUST 在两个物理轴上使用 clip。这可在不创建 CSS 滚动容器的情况下防止预测量绘制溢出,因此原生 Sticky 后代可解析到外部的有效所有者。当内容超出视口时,视口 MUST 在轴成为有效所有者之前切换到其请求的 auto/hidden 组合。公共的 stickyContainment="always" 选项 MAY 在适配时保留该边界,但包含行为 MUST 是显式的,而非滚动意图的附带结果。
交付要求¶
- IR1 — 共享 Hook 是行为核心。 共享工具 Hook MUST 拥有有效轴测量、观察、失效化和所有者发布。
ScrollableArea及组件集成形式 MUST 消费该核心,而不是创建并行的检测器。 - IR2 — 行为不要求
ScrollableArea。 已经拥有视口和内容根的组件 MUST 能够采用这些 Hook,而无需添加便捷组件或更改其语义外层元素。 - IR3 —
ScrollableArea是参考组合。 该组件拥有并记录其视口/内容结构,应用共享的可访问性、链式传递、sticky 所有者及滚动条呈现规则,并演示另一个拥有结构的组件如何集成这些 Hook。它 MUST NOT 包含直接采用 Hook 者无法获得的行为。 - IR4 — 结构与 prop 组合保持显式。 Hook MUST 通过 prop getter 或等效的组合契约接受由调用方拥有的视口/内容 props 和 refs。它 MUST 组合 refs、事件处理器、class/style 输入和 ARIA,而不让展开顺序决定调用方或行为是否丢失。组件自有的可访问性和不可取消行为在已记录的冲突中获胜;可取消的处理器使用共享事件契约。该 Hook 不会假装结构是不必要的,也不会静默包装任意子元素。
- IR5 — 公共 API 遵循意图。 未来的 Hook 和组件名称暴露语义滚动、链式传递、可访问性或呈现意图。原始 CSS 值、观察器控制项、容差调节项和浏览器兼容性规避方案保持内部,除非单独的准入决策证明调用方所有权。
候选共享 Hook 边界¶
确切的名称和 TypeScript 拼写仍是 API 评审工作。候选边界如下:
type ScrollAxis = 'inline' | 'block' | 'both';
type KeyboardAccess =
| {owner: 'content'}
| {owner: 'viewport'; label: string; role?: 'group' | 'region'}
| {
owner: 'contentOrViewport';
label: string;
role?: 'group' | 'region';
};
interface ScrollAxisState {
isScrollable: boolean;
atStart: boolean;
atEnd: boolean;
}
interface UseScrollableAreaOptions {
axis: ScrollAxis;
keyboardAccess: KeyboardAccess;
overscroll?: 'allow' | 'contain';
stickyContainment?: 'whenScrollable' | 'always';
}
type ElementProps<E extends HTMLElement> = BaseProps<E> &
React.RefAttributes<E>;
interface UseScrollableAreaResult {
getViewportProps<E extends HTMLElement>(
props: ElementProps<E>,
): ElementProps<E>;
getContentProps<E extends HTMLElement>(
props: ElementProps<E>,
): ElementProps<E>;
state: {
inline: ScrollAxisState;
block: ScrollAxisState;
};
}
每个 prop getter 接收采用方已解析的元素 props 和公共 ref,通过共享的 prop/ref 工具将它们与 Hook 的行为组合,并返回一个安全的展开对象。getViewportProps 消费调用方的 xstyle,并添加行为自有的适配 clip、特定轴的有效溢出、显式 Sticky 包含、键盘、ARIA、事件、data-state、overscroll 和注册行为,而不选择视口尺寸或滚动条呈现。getContentProps 将内容观察与现有的内容 ref 和 props 组合。无论是宽松的 prop 集合还是单独的 callback ref,都不会让展开顺序成为契约的一部分。
原生滚动条的宽度、颜色和滚动条槽(gutter)仍是视口上的 CSS,而不是 Hook 选项。可选的自定义呈现器和滚动阴影通过更窄的订阅消费相同的已注册度量,因此普通所有者不会为每个滚动偏移重新渲染。Sticky 在已注册的 DOM 祖先链上使用私有的最近所有者消费者;采用方无需渲染 Provider。
显式的失效化方法保持内部,除非真实采用方能证明存在某种溢出变化,而既有的观察盒和有界的平台信号都无法检测到它。
行为矩阵¶
| 请求的轴 | 内联轴生效 | 块轴生效 | 有效所有者状态 | Sticky 所有权 |
|---|---|---|---|---|
inline |
否 | n/a | 无 | 无内联轴所有者;块轴 Sticky 跳过该候选 |
inline |
是 | n/a | 内联轴 | 内联轴 Sticky 在此解析;块轴 Sticky 跳过它 |
block |
n/a | 否 | 无 | 无块轴所有者;内联轴 Sticky 跳过该候选 |
block |
n/a | 是 | 块轴 | 块轴 Sticky 在此解析;内联轴 Sticky 跳过它 |
both |
是/否 | 是/否 | 每个有效轴向独立 | 每个 Sticky 边缘仅在其匹配的有效轴向上解析 |
浏览器仍可能因为 overflow 计算值耦合,将某个视口在两个物理轴向上都归类为 CSS 滚动容器。这一平台事实并不会改变本表格中的系统所有者状态。
滚动条呈现矩阵¶
| 呈现方式 | 滚动机制 | 渲染规则 | 必需的降级方案 |
|---|---|---|---|
| 原生/默认 | 浏览器在视口上拥有所有权 | 平台滚动条;基于标准的宽度、颜色和 gutter 样式可对其进行细化 | 忽略不支持的样式并保留原生行为 |
| 原生/隐藏 | 浏览器在视口上拥有所有权 | 仅当存在另一个清晰的提示和键盘路径暴露溢出时允许 | 在 forced-colors 模式或替代方案不可用时恢复原生呈现 |
| 自定义 | 浏览器在同一视口上拥有所有权 | 轨道/滑块镜像有效轴和实时偏移 | 原生滚动、触摸、滚轮、键盘和编程式 API 仍然具有最终权威 |
平台支持¶
- 基线实现 MUST 在 Astryx Core 支持的每个浏览器中,使用
ResizeObserver和 DOM 滚动几何信息运行。CSS scroll-state 查询是未来的优化方向,而非唯一实现,因为本提案制定时scroll-state(scrollable: ...)在 Firefox 和 Safari 中仍不可用。 scrollbar-width、scrollbar-color和scrollbar-gutter位于 Astryx 的浏览器兼容窗口范围内,构成受支持的原生呈现表面。forced-colors 和平台滚动条偏好优先于装饰性匹配;不支持或被忽略的值仍会降级为平台滚动条,而不会改变所有权或访问性。- 浏览器证据 MUST 覆盖 Chromium、Firefox 和真实 Safari。它 MUST 包含可用的经典与 overlay 滚动条、LTR 和 RTL、缩放、书写模式变化、隐藏到可见的过渡、异步内容、嵌套的正交与同轴区域,以及聚焦时的有效状态变化。
- Chromium 证据 MUST 覆盖两个对回归敏感的交互:Chrome 144 的 overscroll 行为变更 之后,非溢出候选元素上的 containment;以及围绕 transformed/perspective 祖先以及被裁剪的圆角后代元素的命中测试,后者由 Chromium issue 456164629 代表。
当前状态影响¶
family:layout-regions当前将滚动定义为显式且局部化的:LayoutContent 和 LayoutPanel 拥有isScrollable;Layout 的height="fill"包含区域滚动,而height="auto"让页面增长。新能力保留这些所有者,但将请求的滚动与有效的逐轴滚动区分开来。- LayoutContent 和 LayoutPanel 目前使用同一个根元素作为 landmark、主题化表面、带内边距的内容盒以及始终应用
overflow: auto的视口。它们不暴露内部内容根节点。因此,直接采用 hook 需要 Layout 对内部观察盒及其 padding/full-bleed 语义做出显式决定;通用 hook 不得静默插入该包装层。 family:layout-primitives当前允许 Stack 和 StackItem 暴露组件特定的overflow: auto;Grid 和 Center 不继承该行为。本提案不会自动为每个布局原语添加滚动。- Popover 已将内部滚动设为以测量到的 overflow 为条件,并合并了打开状态观察。DropdownMenu 有一个独立的块轴辅助函数。Carousel 有一个独立的内联轴辅助函数。这些是共享需求的证据,而非三种可接受的长期定义。
- Table、CodeBlock、Carousel 以及一些示例使滚动包装器无条件地可通过键盘聚焦。采用时必须审查每个包装器是否始终预期发生溢出,还是应跟随有效状态。
- Outline 已经通过结合计算后的 overflow 与实时几何信息来识别最近的有效块滚动祖先,但它执行的是时间点查找,而不是发布可复用的实时所有者。
先前方案比较¶
| 系统 | 可取之处 | 本提案的边界 |
|---|---|---|
| 原生 CSS overflow | 浏览器拥有滚动、输入、惯性动量和原生滚动条的无障碍访问性 | 各轴的计算值相互耦合;原生 Sticky 会选择 CSS 滚动祖先,即使这与有效的逐轴所有权冲突 |
axe scrollable-region-focusable |
在测试键盘访问之前,要求同时具备可测量的溢出和可进行滚动的计算 overflow 值 | 是快照式审计,而非实时观察器或所有者注册表 |
| Radix ScrollArea | 拥有 viewport 和真实内容盒,同时观察两者,并分别按轴推导溢出状态 | 主要是一个自定义滚动条组件;未定义共享的 Sticky、过滚动或条件焦点策略 |
| Zag Scroll Area | 拥有 viewport/content 结构,跟踪每个轴、偏移量、边缘以及由 resize 驱动的滑块状态 | 状态机组件机制比 Astryx 可复用的最小能力更庞大 |
| Astryx 当前 helpers | Popover、menu、Carousel、Table 粘性列和 Outline 各自验证了该模型的某些部分 | 轴/容差/失效行为存在重复,且没有共享的有效所有者上下文 |
代表性公开证据:
- axe effective-scroll 检测
- Radix viewport/content 结构
- Radix 按轴溢出观察
- Zag viewport/content 尺寸变化跟踪
- CSS overflow 计算值耦合
- CSS scroll-state 查询
- 原生 scrollbar 宽度、颜色和 gutter
验证¶
| 契约 | 验证 | 代表性状态 | 变更或失败预期 |
|---|---|---|---|
| FR1–FR4 | 单元几何与计算样式测试,外加浏览器矩阵 | inline、block、both;适配、完全适配、>1px 溢出;可滚动与不可滚动的计算值;水平、垂直和侧向书写模式;LTR 和 RTL | 仅凭声明或多余几何就成为一个所有者,遗漏某个有效轴,或物理方向泄漏到契约中 |
| FR5–FR9 | 观察器生命周期与集成测试 | viewport 尺寸变化、内容尺寸变化、异步资源、隐藏/显示、重连、经典滚动条 | 状态仍为过期,在无法测量时报告适配、循环,或发布冗余更新 |
| FR10, FR11, FR18 | 真实浏览器中的嵌套 Sticky 矩阵 | 任意流内位置;每个逻辑边缘;正交与同轴所有者;非活动内部候选 | Sticky 绑定到非有效或跨轴所有者,无法在流中间出现,或堆叠到错误的边界 |
| FR12, FR13 | 键盘与无障碍树测试 | 适配/溢出、命名 viewport、原生链接/按钮委托、被排除角色、嵌套所有者、正/反向进入、指针/编程焦点、动态资格、Chromium/WebKit 中的完整 Arrow/Page 范围 | 内容不可触达,适配区域增加无法解释的停止点,现有路径出现重复停止点,缺少命名,或焦点在变更时移动 |
| FR12 命名 | 无障碍树测试 | 由所有者命名的 group 视口,来自调用方标签以及来自翻译后的默认值;页面中唯一的 main 地标作为视口,依赖其角色;第二个 main 地标作为视口 |
非地标视口不是由所有者命名的 group,或者未命名的第二个 main 视口通过测试 |
| FR14 | 滚轮/触摸/键盘链式浏览器测试 | 适配子元素、活动子元素、每个边缘、包含与链式 | 适配子元素造成滚轮死区,或显式包含泄漏到非活动轴 |
| FR15, FR16 | 原生/自定义呈现与 forced-colors 测试 | overlay/classic、thin/default、stable gutter、hidden/replacement、自定义滑块 | 呈现方式创建第二个属主、掩盖状态、丢失平台回退,或改变滚动机制 |
| FR17 | 类型/API 测试与浏览器测试夹具 | 请求 inline、block、both;尝试可见的对立轴 | 公共 API 接受平台计算为不同语义的 CSS 组合 |
| FR19 | 表格浏览器集成 | 仅 inline、双向受限、sticky 列、sticky 表头、交叉单元格 | 表格插件观察到不同的属主,或外部包装器静默破坏 sticky/无障碍行为 |
| FR20 | ScrollableArea 组件与容器内边距测试 | 零/默认内边距、统一/边缘覆盖、嵌套出血消费者、受控与全出血视口 | 内容发布过时的 inset,嵌套出血子元素错误补偿,或滚动在无明确意图的情况下逃出其父级 |
| FR21 | 真实浏览器中的 fitting/overflowing Sticky 过渡 | fitting 默认、fitting always、内容增长、内容收缩、外部块级 Sticky 属主 |
fitting 默认视口静默捕获 Sticky,显式包含丢失,或溢出增长未能激活滚动 |
决策日志¶
DEC-1 — 共享 hooks 拥有行为;ScrollableArea 是参考组合¶
Reference: spec:AST-025/DEC-1
Decider: cixzhang, 2026-09-11
共享工具 hooks 是有效轴测量、观察、失效和滚动属主发布的权威属主。已有视口/内容结构的组件直接采用这些 hooks。ScrollableArea 将相同的 hooks 组合成一个便捷组件,并展示完整的默认组合;没有任何行为只能通过该组件获得。
这使滚动行为可复用,而无需强制 Layout 区域或 Table 等拥有结构的组件经由一个以行为命名的包装器。当构建者确实希望系统拥有所需结构时,它也提供了完整的默认方案。
已拒绝:将 ScrollableArea 作为唯一入口,因为这会要求额外的包装器,并把行为组件变成组件特定结构的属主。
DEC-2 — ScrollableArea 是显式的容器内边距参与者¶
Reference: spec:AST-025/DEC-2
Decider: cixzhang, 2026-09-11
参考组件发布其内容盒的逻辑内边距,默认值为零,因此嵌套出血消费者会收到实际应用的几何信息。视口出血保持显式,而不是变为可滚动后的副作用。这使 ScrollableArea 与共享容器系统保持一致,而不让行为 hook 拥有内边距或布局。
已拒绝:自动父级内边距逃逸,因为添加滚动不得静默加宽容器的视觉边界。
DEC-3 — Fitting 滚动意图不会静默包含 Sticky¶
Reference: spec:AST-025/DEC-3
Decider: cixzhang, 2026-09-12
共享 hook 在两个物理轴上应用 clip,直到请求的内容超过其几何尺寸。这避免了测量前的绘制溢出,同时不创建 CSS 滚动容器,因此 fitting 区域不会静默拦截来自外部属主的原生 Sticky。仅几何尺寸触发的溢出状态会在测量有效属主之前激活由书写模式解析的 auto/hidden 对。
stickyContainment="always" 是面向刻意希望 fitting 视口保持为 Sticky 边界的消费者的显式选择加入。其 camelCase 枚举遵循公共 API 约定。
已拒绝:为每个请求的视口保留 auto/hidden,因为仅凭滚动意图就会改变 Sticky 行为,即使实际上不会发生滚动。
已拒绝:fitting 期间不声明溢出,因为内容可能在首次几何测量之前闪烁。
DEC-4 — 共享的自动键盘所有权在进入时委托¶
Reference: spec:AST-025/DEC-4
Decider: cixzhang, 2026-09-13
keyboardAccess.owner="contentOrViewport" 在单个共享 hook 中拥有自动键盘路径。组件不维护并行的可聚焦性检测器。初始的持续资格判定方法被替换为聚焦时委托:溢出的视口仍是一个命名停靠点,向前 Tab 进入时会检查第一个顺序后代。保守的委托集合是复合组件之外的原生链接和按钮、可编辑表面,以及嵌套滚动属主。正 tabindex 排序和未经证实的交互角色保留视口。
原生反向遍历在从被委托的第一个子元素返回时会跳过视口。指针/程序化焦点停留在视口上。内容变化从不移动现有焦点;资格会在下一次键盘输入时重新检查。原生滚动仍然负责方向键/翻页键和滚动链。
否决:在子树和祖先节点变更后持续进行键盘可聚焦性扫描,因为共享基础设施不应在空闲时承担该开销。几何观察仍然独立。还否决:越过被排除的第一个后代进行转发,因为这会改变使用方的顺序焦点导航顺序。
未决问题¶
- OQ1 — Layout 的
isScrollable迁移是如何被观察和排序的? (human-api) LayoutContent 和 LayoutPanel 将把其现有的isScrollable路径迁移到共享的受管行为。由于isScrollable默认值为 true,实现 MUST 作为共享 hooks 与ScrollableArea之上的一个独立变更落地。构建原型并对单元素混合观察(视口加上直接子元素的 resize、子树变更、资源/字体、过渡和显式失效信号)与内部被观察的内容框进行比较。在替代当前行为之前,任一方案都需要针对以下方面的兼容性证据:异步及纯 CSS 几何变化、直接子选择器、flex/grid 子元素、百分比尺寸、full bleed、容器内边距和 refs。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx