跳转至

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