跳转至

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