useScrollableArea 模块契约¶
意图¶
useScrollableArea 是组件可复用的规范行为核心,适用于已经拥有视口(viewport)和内容根节点(content root)的组件。它提供安全的 prop/ref 组合、逻辑轴测量、实时所有者注册、边缘状态、键盘访问以及滚动链接,且无需插入任何结构。
兼容性与迁移¶
- 发布默认状态:尚未发布
- 兼容性类别:附加的公共 hook 和类型
- 迁移决策:
spec:AST-025/DEC-1
所有权边界¶
拥有
- 有效轴测量和稳定的逻辑边缘状态。
- 观察、失效处理、DOM 所有者注册、条件性视口访问以及有效轴链接。
- 调用方视口/内容 props 和 refs 的安全组合。
不拥有 / 非目标
- 视口布局、绘制、溢出声明、滚动条呈现或内容包装器的插入。
- 粘性定位和公共所有者查找。
公共 API 与概念¶
| 概念 | 封闭值或状态 | 含义 | 默认值 | 所有者 | 稳定性 |
|---|---|---|---|---|---|
| 轴 | inline, block, both |
请求的逻辑滚动意图 | 必需 | spec:AST-025 |
稳定 |
| 键盘所有者 | content、命名 viewport、命名 contentOrViewport |
固定或自动的键盘滚动路径 | 必需 | spec:AST-025 |
稳定 |
| overscroll | allow, contain |
有效轴上的边缘传播 | allow |
spec:AST-025 |
稳定 |
| 轴状态 | isScrollable, atStart, atEnd |
有效所有权和逻辑边缘 | 非活动,两边均为 true | module:ScrollableArea/useScrollableArea |
稳定 |
行为契约¶
| ID | 不变量 | 依据 | 验收与实现状态 |
|---|---|---|---|
| FR1 | 仅当轴被请求、计算出的溢出具备滚动能力,且几何尺寸超过 1px 时,轴才必须(MUST)生效。 | spec:AST-025 FR1–FR4 |
已实现 |
| FR2 | 必须(MUST)观察视口和内容的几何尺寸;在无法测量时,失效处理必须(MUST)合并,并保留最后有效状态。 | spec:AST-025 FR5–FR9 |
已实现 |
| FR3 | 逻辑边缘和行为所拥有的物理溢出必须(MUST)通过方向以及水平、垂直或侧向书写模式进行映射,而无需采用者重新创建该映射。 | spec:AST-025 FR1, FR3–FR4 |
已实现 |
| FR4 | 最近注册的有效所有者必须(MUST)按轴独立胜出。 | spec:AST-025 FR10, FR18 |
已实现(私有,供未来 Sticky 使用) |
| FR5 | 仅当适用的请求轴生效时,视口键盘 props 和 overscroll 包含才必须(MUST)出现。 | spec:AST-025 FR12–FR14 |
已实现 |
| FR6 | Prop getter 必须(MUST)组合 refs 并保留调用方的 handlers/classes/styles/ARIA;同时,行为自有的可访问性和不可取消行为在冲突时优先。 | spec:AST-025 IR4 |
已实现 |
| FR7 | viewport prop getter 必须(MUST)消费调用方的 xstyle,并在内部组合由几何驱动的 clip/auto/hidden 溢出,以及显式的适配性 Sticky 包含。 |
spec:AST-025 FR21 |
已实现 |
| FR8 | contentOrViewport 必须(MUST)保留已命名的溢出视口,在向前 Tab 进入时检查第一个顺序后代,并仅将委托交给导航键属主表面之外的原生链接/按钮。从被委托的第一个子元素反向遍历会跳过视口。指针/编程式焦点从不委托;资格在下一次进入时重新检查。 |
spec:AST-025 FR12–FR13 |
已实现 |
Transformation and precedence order¶
- ORD1 — 有效状态。 请求的逻辑轴 → 计算出的物理轴 → 可滚动溢出 → 几何容差 → 归一化的逻辑边缘。
- ORD2 — Prop 组合。 调用方 props 和
xstyle→ 行为持有的 适配/活动溢出样式 → 稳定的组合 ref → 行为持有的键盘、 状态和链式输出。
Performance and resources¶
- PR1 — 稳定发布。 相同的有效/边缘状态复用先前对象。
- PR2 — 共享观察。 两个元素盒均使用共享的 ResizeObserver; 所有次级失效信号通过一个动画帧合并。
Accessibility contract¶
- AR1 — 已命名视口属主。 固定视口和自动访问需要标签,并在有效可滚动时保留
tabIndex=0。自动访问仅在向前键盘进入时委托;后代在已命名视口组/区域内保留自己的名称。 - AR2 — 焦点连续性。 内容、资格和几何变化从不移动或模糊焦点。失去溢出且在聚焦中的视口仍可通过编程方式聚焦。从被委托的第一个子元素反向遍历会跳过视口,包括在访问了后续后代之后。
- AR3 — 保守资格。 检查第一个顺序目标;不要越过被排除的元素搜索链接/按钮。复合角色、可编辑表面、原生或已注册的嵌套滚动属主、正向 Tab 顺序、弹出触发器,以及未经验证的交互角色保留视口路径。
- AR4 — 原生滚动。 委托必须(MUST)保留对两个滚动边缘的 Arrow/Page 访问,而不实现 JavaScript 滚动。
Design relationships¶
此 hook 不拥有任何视觉表现。
Parent and system relationships¶
component:ScrollableArea拥有参考视口/内容组合。spec:AST-025拥有共享行为和采用边界。
Verification map¶
| Contract | Verification | Representative states | Mutation or failure expectation |
|---|---|---|---|
| FR1–FR8, AR1–AR4 | useScrollableArea.test.tsx, scrollKeyboardDelegation.test.ts, and BottomSheetKeyboard.a11y.browser.spec.ts |
水平/垂直/侧向,LTR/RTL,适配/溢出/边缘,固定/自动键盘属主,动态后代资格,嵌套属主,焦点丢失 | 仅样式或仅几何的属主、物理边缘泄漏、重复/缺失的键盘路径、过期状态、ref 丢失或死包含失败 |
Decision log¶
DEC-1 — Prop getters 是公共组合接缝¶
Reference: module:ScrollableArea/useScrollableArea/DEC-1
Decider: cixzhang,2026-09-11
每个被属主元素返回一个 prop 对象,将 refs、无障碍、处理程序和行为保持在一起,而不会使消费者的展开顺序成为正确性的一部分。
DEC-2 — 自动属主是共享行为¶
Reference: module:ScrollableArea/useScrollableArea/DEC-2
Decider: cixzhang,2026-09-13
contentOrViewport 保留已命名的溢出视口,并且仅在向前 Tab 进入时将委托交给安全的第一个顺序原生链接/按钮。这取代了持续的键盘资格观察。几何观察不变;键盘资格不添加子树或祖先观察器,并在每次进入时重新检查。BottomSheet 是此共享行为的验证组合。
Open questions¶
无。
Content boundary¶
此文件不重复消费者的签名/示例、ScrollableArea 的结构/呈现,或 Sticky 的未来 API 和定位机制。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx