ScrollableArea 组件契约¶
意图¶
ScrollableArea 为构建者提供了一个完整的原生滚动视口和可观测的内容盒,无需他们协调键盘访问、链接、边缘状态和原生滚动条呈现。它是共享行为 hook 之上的参考组合,而不是该行为的唯一拥有者。
兼容性与迁移¶
- 保留的发布默认值:尚未发布
- 兼容性类别:附加组件和包导出
- 受控/非受控行为:不适用
- 迁移决策:
spec:AST-025/DEC-1
所有权边界¶
拥有
- 一个根原生视口和一个真实被观测的内部内容盒。
- 由共享 hook 提供的条件性视口键盘访问、可访问命名、逻辑轴意图、过滚动策略和原生滚动条默认值。
- 可选逻辑内容内边距,发布匹配的容器内缩,以及针对继承容器内边的可选视口出血。
不拥有 / 非目标
- 由 JavaScript 驱动的滚动或自定义滚动条 DOM。
- 通用 Sticky 公共 API 或回退定位算法。
- 现有的组件自有视口迁移,例如 Layout 和 Table。
公共概念¶
| 概念 | 封闭值或状态 | 含义 | 按变体/方向/状态的可用性 | 默认值 | 所有者 | 稳定性 | 无效值行为 |
|---|---|---|---|---|---|---|---|
| 逻辑轴 | inline、block、both |
允许原生滚动的轴 | 全部 | block |
spec:AST-025 |
稳定 | 类型错误 |
| 过滚动 | allow、contain |
有效轴是否在边缘处传播 | 全部 | allow |
spec:AST-025 |
稳定 | 类型错误 |
| 视口尺寸 | width、height、maxWidth、minHeight |
视口上的标准容器几何 | 全部 | 自动 | component:ScrollableArea |
稳定 | 类型错误 |
| 内容内边距 | 共享的逻辑间距步进阶梯 | 内容盒内缩与已发布的几何 | 全部 | 0 |
architecture:container-padding |
稳定 | 类型错误 |
| 全出血 | false、true |
视口是否脱离继承的内缩 | 全部 | false |
architecture:container-padding |
稳定 | 类型错误 |
| Sticky 包含 | whenScrollable、always |
适配内容是否捕获 Sticky | 全部 | whenScrollable |
spec:AST-025 |
稳定 | 类型错误 |
| 视口语义 | group、region 以及必需标签 |
为有条件的键盘滚动目标命名 | 全部 | group |
component:ScrollableArea |
稳定 | 类型错误 |
行为与布局契约¶
| ID | 不变量 | 依据 | 验收和实现状态 |
|---|---|---|---|
| FR1 | 根 MUST 保持为唯一原生视口,并通过 StyleX 接收公共 ref、标准容器尺寸属性和样式输入。 | spec:AST-025 IR3–IR4 |
已实现 |
| FR2 | 内部内容包装器 MUST 是一个与视口一起被观测的真实常规流块级盒子,使用 100% 的最小尺寸,并且仅在请求内联滚动时使用 max-content 内联尺寸。子元素参与该盒子,而非视口的 flex/grid 格式化上下文;最小块尺寸不会创建确定的百分比高度基准;必须保留这些语义的结构直接采用该 hook。 | spec:AST-025 FR5–FR6 |
已实现 |
| FR3 | 原生滚动条行为 MUST 保持权威;当使用精细指针时,默认滑块使用 --color-neutral 且轨道透明,而粗粒度主指针和强制颜色会恢复平台呈现。 |
spec:AST-025 FR15 |
已实现 |
| FR4 | 滚动状态容器查询可以增强后代元素的粘滞/边缘呈现,但 hook 状态 MUST 保持为跨浏览器的唯一事实来源。 | spec:AST-025 平台支持 |
已渐进式实现 |
| FR5 | 内容盒 MUST 以 edge-over-axis-over-uniform(边优先于轴,轴优先于统一)的优先级应用并发布逻辑内边距,且每个已发布边的默认值为零。isFullBleed MUST 只允许视口消费继承的 inset;嵌套内容继续读取内容盒已发布的值。 |
architecture:container-padding |
已实现 |
| FR6 | 适配中的视口 MUST 在两个物理轴上使用 clip,以防止绘制溢出且不捕获原生 Sticky。超出请求轴范围的几何量 MUST 激活由书写模式解析出的 auto/hidden 组合。stickyContainment="always" 在适配时 MUST 显式保留该组合。 |
spec:AST-025 FR21 |
已实现 |
允许的变化¶
- AV1 — 尺寸与呈现。 使用方的
xstyle、className和style可以调整视口大小,并修改基于标准的原生滚动条属性。 - AV2 — 内容。 任何流式内容都可在被观察的盒子中渲染;构建者仍负责内容语义。
代表性状态¶
| 状态 | 必需不变量 | 允许的变化 |
|---|---|---|
| 适配中 | 两个轴均使用 clip;无 Tab 停留点;除非 containment 为 always,否则 Sticky 向外传递;两个边缘均为 true |
视口大小与内容 |
| 溢出中 | 具名 Tab 停留点;逐轴的逻辑边缘状态 | 一个或两个请求轴 |
| 聚焦时溢出已移除 | 移除未来的 Tab 停留点,但不移动焦点 | 保持当前焦点 |
| 强制颜色模式 | 原生平台滚动条呈现 | 平台渲染 |
| 粗粒度主指针 | 原生平台滚动指示器 | 平台渲染 |
转换与优先级顺序¶
- ORD1 — Props。 使用方的 DOM 与样式 props 优先组合;行为自身拥有的 ref、无障碍属性和活动轴链接在文档记录的冲突中优先。
性能与资源¶
- PR1 — 共享且合并的观察。 视口与内容的尺寸变化信号使用共享观察器,重复的失效每帧至多发布一次。
无障碍契约¶
- AR1 — 条件访问。 视口仅在至少一个请求轴生效时进入顺序导航,并带有提供的标签和 role。
- AR2 — 焦点连续性。 失去溢出状态 MUST NOT 导致失焦或移动焦点。
设计关系¶
| 结构或状态 | 设计要求 | 呈现权威 | 层级角色 | 组件契约 |
|---|---|---|---|---|
| 视口 | 平台滚动条;在精细指针下,使用 token 颜色的滑块和透明轨道 | spec:AST-025 |
支持性 | FR1, FR3 |
| 内容盒 | 默认无独立绘制 | 调用方内容 | 结构性 | FR2 |
主题化结构¶
{
"Viewport": {"target": "scrollable-area"},
"Content box": {
"none": {
"reason": "intentional: The content box is structural and paints no component-owned appearance."
}
}
}
家族与系统关系¶
module:ScrollableArea/useScrollableArea拥有可复用的测量、溢出边界、Sticky 包含、无障碍和注册行为。architecture:container-padding拥有可选的内容 inset 发布以及选择采用的视口延展行为。spec:AST-025拥有共享的有效轴、观察、无障碍、overscroll、所有权、边缘和原生呈现规则。
验证映射¶
| 契约 | 验证 | 代表性状态 | 变更或失败预期 | 审计章节 |
|---|---|---|---|---|
| FR1–FR6, AR1–AR2 | 组件/hook 测试与 Storybook 浏览器探测 | 适应、溢出、焦点丢失、LTR/RTL/垂直、嵌套允许/包含、适应内容时的 Sticky 直通/包含、原生滚动条、内边距、全出血 | 重复的 viewport、过期状态、失效的嵌套滚动区域、隐式 Sticky 包含、无条件 Tab 停靠点,或过期的 inset 失败 | audit:ScrollableArea/behavior |
决策日志¶
DEC-1 — 便捷组件拥有一个显式内容框¶
参考: component:ScrollableArea/DEC-1
决策者: cixzhang, 2026-09-11
稳定的 viewport/content 结构为参考组件提供可靠的实时测量,同时让拥有结构的组件可以自由地直接采用该 hook。
DEC-2 — ScrollableArea 参与容器内边距系统¶
参考: component:ScrollableArea/DEC-2
决策者: cixzhang, 2026-09-11
内容框发布其实际逻辑内边距(默认为 0),因此嵌套的全出血消费者绝不会继承过期的 inset。viewport 仅在 isFullBleed 为显式时才消费祖先 inset;单独滚动不会静默逃出其父容器。
DEC-3 — 适应内容默认将 Sticky 所有权向外传递¶
参考: component:ScrollableArea/DEC-3
决策者: cixzhang, 2026-09-12
适应内容的 viewport 在两个轴上都使用 clip,以避免测量前的绘制闪烁,同时不会成为 CSS 滚动容器。超出请求轴的几何量会激活按书写模式解析的滚动边界。stickyContainment="always" 是在适应内容时保留该边界的显式选择。
未决问题¶
无。
内容边界¶
本文件不会重复消费者示例、共享 hook 算法、Sticky 未来的公共 API,或现有组件自有 viewport 的迁移计划。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx