跳转至

Carousel 组件契约

契约概览

领域 契约
公开契约 hasSnap 接受 boolean \| SnapPaging(FR5)。hasSnap 或 hasSnap={true} 会开启原生 CSS 滚动吸附,行为与已发布版本完全一致(FR6)。hasSnap={useSnapPaging()} 会开启吸附分页:在原生吸附的停靠点之上,加入 UIKit 在手指或触控板滑动下的分页手感(FR7)。useSnapPaging 默认没有非 React 等价实现(FR9)。边缘滚动按钮在到达边缘时会隐藏,并将焦点移交给滚动区域(FR1–FR4)。
行为 原生吸附会将每个项目停靠在其起始边缘,并将惯性动量交给平台处理。吸附分页使用相同的停靠点:在手指操作下,以及在每个指针下的触控板滑动中,一次轻扫默认移动一个视图,或在使用 {pages: 'item'} 时移动一个项目,依据 spec:AST-094 FR3 的分页规则。某个方向已用完的边缘按钮会隐藏,并且不占据 Tab 停靠位;当获得焦点的按钮用完方向时,焦点会移动到滚动区域。
最终用户影响 在手机上轻扫分页式轮播图的人会感受到 iOS 的分页效果;使用不带分页的轮播图的人不会下载任何分页代码。键盘用户滚动到第一个或最后一个项目时会停留在轮播图内部。
构建方影响 hasSnap 和 hasSnap={true} 保持不变。分页是同一个 prop,传入 useSnapPaging() 即可启用。未配置分页的 Carousel 不会打包分页器代码。
兼容性/就绪度 增量变更:hasSnap 的类型从 boolean 拓宽为 boolean \| SnapPaging,无需重命名、弃用或 codemod;true 保持现有的原生吸附,且不获得分页。实现差距:已发布的 Carousel 在边缘按钮上仍使用原生 disabled。证据差距:{pages: 'item'} 尚未针对 UIKit 的组分页进行测量(FR7)。
审查检查 拒绝从 Carousel 的默认导入中可达的分页器代码;拒绝分页器的懒加载 import();拒绝在 hasSnap 不是 useSnapPaging 值的情况下启用吸附分页;拒绝 hasSnap={true} 产生分页行为;拒绝吸附分页停靠点与原生吸附不同;拒绝在测量之前声称 {pages: 'item'} 与 UIKit 匹配;拒绝依赖仅 Chromium 支持的轮播图特性;拒绝焦点停留在隐藏的边缘按钮上。
治理规则 spec:AST-094 FR3、FR6、FR43、DEC-25;architecture:public-component-api INV3(已知偏差,DEC-2)、INV22;architecture:react-component-runtime INV13;spec:AST-085 FR1、FR4;spec:AST-025 FR12;architecture:interaction-modality INV1。

此表是审查投影;以下正文具有权威性。

意图

Carousel 在带标签的区域内显示一行可水平滚动的项目,并可在每个边缘提供可选的滚动按钮。本记录涵盖该行的吸附方式、可选加入的吸附分页,以及边缘滚动按钮在方向用完时的行为。在本记录扩充之前,Carousel 的其他行为不在契约范围内。

兼容性与迁移

  • 保留已发布的默认行为:是。hasSnap 和 hasSnap={true} 保留其已发布的原生吸附行为,且不获得分页。hasSnap 被省略或为 false 的轮播图不会吸附。
  • 兼容性类别:增量式 API。hasSnap 的类型从 boolean 拓宽为 boolean | SnapPaging,并且 useSnapPaging 是新增内容;无需重命名、弃用或 codemod。边缘焦点是行为修正,不涉及 API 变更。
  • 受控/非受控行为:不变。
  • 迁移决策:DEC-1(边缘焦点)、DEC-2(吸附与吸附分页)。

消费者迁移说明应放在消费者文档和发布说明中。

所有权边界

拥有

  • hasSnap prop、其原生吸附及其吸附分页值,以及 useSnapPaging API。
  • 吸附分页在轮播图上使用哪些停靠点,以及一页是什么(FR7)。
  • 边缘滚动按钮的可见性、Tab 顺序,以及方向用完时的焦点目的地。

不拥有 / 非目标

  • 分页规则、稳定行为及其测量值 — spec:AST-094 FR3、FR6、DEC-25。
  • 吸附分页与 Lightbox 画廊共享的内部分页器 — spec:AST-094;它保持内部实现。
  • 滚动区域的键盘访问与命名 — spec:AST-025。
  • 通用禁用控件语义 — spec:AST-085。
  • 按钮的命名、尺寸和激活 — family:buttons。
  • 循环、鼠标拖拽分页、自动播放、圆点指示器和幻灯片语义 — 未纳入契约。
  • 边缘渐隐 — 渐隐的外观未纳入契约;其状态遵循 FR8。

公共概念

概念 封闭值或状态 含义 按变体/方向/状态的可用性 默认值 所有者 稳定性 无效值行为
hasSnap false、true 或 SnapPaging 值 省略或 false:无吸附。true:原生 CSS 滚动吸附(FR6)。SnapPaging 值:在原生吸附停止点上进行吸附分页(FR7) 所有 Carousel false component:Carousel 稳定 TypeScript 拒绝其他值
useSnapPaging(options?) 返回 SnapPaging 其值开启吸附分页的 Hook。从 @astryxdesign/core/SnapPaging 和包根目录导出 React 调用方 — component:Carousel 稳定 —
SnapPaging 不透明 配置好的吸附分页。调用方只能通过 useSnapPaging 创建,且只能将其传给 hasSnap — — component:Carousel 稳定 —
SnapPagingOptions {pages?: 'view' \| 'item'} Hook 的选项。pages 设置一次轻扫移动的量(FR7)。字段仅由当前记录添加 — {pages: 'view'} component:Carousel 稳定 TypeScript 拒绝未知字段和值
边缘滚动按钮 可用、已耗尽 该按钮方向上是否仍有内容 轮播溢出时的两侧边缘 — component:Carousel 稳定 不适用

行为与布局契约

ID 候选不变量 依据 草稿审查状态
FR1 方向已耗尽的边缘滚动按钮会被隐藏。隐藏时它不占据 Tab 焦点位置,也不会暴露给辅助技术。它保持挂载状态,因此布局不会移位。这是在 spec:AST-085 FR4 下的移除,而非禁用控件。 DEC-1 已定稿
FR2 当聚焦的边缘滚动按钮耗尽时,焦点移动到滚动区域而不滚动它。当内容不再溢出且滚动区域不在 Tab 键顺序中时(spec:AST-025 FR12),该行为依然成立:它仍会以编程方式获得焦点。焦点绝不会落在页面主体或隐藏按钮上。 DEC-1; spec:AST-085 FR4 已确定
FR3 每次边缘转换仅发生一次交接,且仅在边缘按钮持有焦点时发生。当焦点在其他位置时,通过滑动、调整大小或滚轮到达的边缘不会移动任何内容。 architecture:interaction-modality INV8 已确定
FR4 可用的边缘滚动按钮行为与普通按钮相同。 family:buttons 已确定
FR5 hasSnap 接受 boolean \| SnapPaging。省略或为 false:滚动区域不吸附。true(写作 hasSnap):原生吸附,FR6,与发布时完全一致,且不含手势代码。SnapPaging 值(仅由 useSnapPaging 产生):吸附分页,FR7;轮播按原生吸附的逐项停靠点吸附,并带有 FR7 的末页例外,分页器也会停定在这些相同的停靠点上。true 从不分页。在后续渲染中出现的新的 SnapPaging 值不会重新开始一次停定,也不会重新附加手势。第三种状态是对 architecture:public-component-api INV3 的已知偏离;后者将 has… 布尔值保持为真正的开关(DEC-2)。SnapPaging 值通过注册的键被识别,其类型携带一个类型为 never 的可选幻影成员,因此包中的值与 swizzled 副本的值匹配(spec:AST-110 FR3);该成员在运行时从未出现,且该值保持不透明。 DEC-2 已定稿
FR6 原生吸附仅使用 CSS scroll snap:沿滚动区域的行采用强制吸附,每个直接子元素在其起始边缘处吸附,滚动内边距与轮播的内边距一致。每个项目都是停靠点,即使同时显示多个项目时也是如此;平台自身的动量决定滑动在何处停下。报告的当前页是滚动停定后吸附到视图中的页面,边缘按钮的可用性会跟随每次滚动(包括动量和编程式滚动)以及每次尺寸调整。原生吸附不添加手势代码。它不依赖 ::scroll-button()、::scroll-marker、:target-current、scroll-state 容器查询、snap 事件或 interactivity: inert;其中一项可以仅在 @supports 下添加,且仅在不改变任何行为、名称、角色或焦点顺序的情况下。 DEC-2 已定稿
FR7 吸附分页使用原生吸附的停靠点(FR6):每个直接子元素的起始边缘,从内联起始方向测量并在从右到左布局中镜像;最后的停靠点被限制在行结束处,因此不会显示空白;但若某停靠点距结束处小于其前一步步距的一半,则并入结束页。停靠点之间有间隙,且间隙永远不是停靠点。在手指操作下,以及在任何指针下的触控板滑动中(spec:AST-094 FR43),松开时按 spec:AST-094 FR3 的分页规则选择停留页:最多从拖动开始所在的页面移动一页。停定按 spec:AST-094 FR6 中分页段落所述开始。使用分页配置时,一次轻拂默认移动一个视图:松开后停定在轻拂方向上约一个视口以外的项目起始边缘处,最后一页停在行结束处;{pages: 'item'} 则改为每次轻拂移动一个项目。在从右到左布局下,页面从内联起始方向开始。每视图一个项目时,两者给出相同的停靠点。鼠标滚轮保持原生吸附,而 hasSnap={true} 在任何指针下都保持原生 CSS 吸附。边缘按钮步进约一个视图:视口宽度减去半个项目,落在最近的停靠点并至少移动一个停靠点。证据缺口:每次轻拂一个项目的感觉尚未与 UIKit 的分组分页进行对比测量;在声称等效之前先进行测量。 DEC-2;spec:AST-094 FR3、FR6、DEC-25 已定稿
FR8 Carousel 的模块不导入任何分页器代码:既不是内部分页器,也不是其分页移动或手势代码。useSnapPaging 模块静态导入这些代码,而 Carousel 仅在一个 effect 中调用 SnapPaging 值的 attach 和 detach,并且行的移动来自 Carousel 自身的滚动调用。该分页器通过模块边界被 tree-shaken,且没有使用惰性 import()(architecture:react-component-runtime INV13),因此没有 hasSnap={useSnapPaging()} 的 Carousel 不会打包任何分页器代码。导入该模块不会进行任何 DOM 操作。在 snap paging 下,边缘按钮、边缘渐隐以及句柄的 canScrollPrev()/canScrollNext() 都跟随被持有的行,保持同一状态。 DEC-2; architecture:react-component-runtime INV13 已定稿
FR9 默认情况下,useSnapPaging(options?) 没有非 React 等价物:其值只提供给 Carousel 的 hasSnap(architecture:public-component-api INV22)。Carousel 通过该值将 FR7 附加到其滚动区域,而 detach 该值会移除它添加的所有监听器。 architecture:public-component-api INV22 已定稿

代表性状态

状态 必需不变量 允许的变化
滚动中 两个边缘按钮都可用 循环保持两者都启用
聚焦的“向右滚动”到达末尾 按钮隐藏;焦点在滚动区域;没有额外滚动 减少动态效果
通过滑动到达边缘,焦点在其他位置 按钮隐藏;焦点不移动 —
内容缩小以适配 两个按钮都隐藏;聚焦的按钮将焦点移交给滚动区域 —
每视图一个项目,吸附分页 一次轻扫移动一个项目,如同 UIKit 分页滚动视图移动一页;{pages: 'item'} 提供相同效果 —
每视图三个项目,吸附分页 一次轻扫移动一个视图,停在最靠近一个视口的项目起始边缘;使用 {pages: 'item'} 时移动一个项目;边缘按钮移动约一个视图 —
不完整的最后一页 最后一页停在行尾;不留空白 —
拆分末尾 末尾的页面是末尾舍入后的页面:在距末尾不足其前一步长一半处的一个停止点停在行尾 (FR7);原生吸附会跳过它 —
从右到左 页面从行内起点开始;停止点和轻扫方向镜像 —
hasSnap={true} 原生吸附;不加载或运行分页器代码 平台惯性

可访问性契约

  • AR1 — 没有不可见的 Tab 停留点。 隐藏的边缘按钮不可聚焦,也不会暴露给辅助技术 (FR1)。
  • AR2 — 焦点保持在区域内。 边缘交接将焦点保持在带标签的轮播区域内 (FR2),并且键盘焦点指示器遵循 architecture:interaction-modality INV1。
  • AR3 — 吸附保留所有路径。 在原生吸附和吸附分页下,滚动区域仍然是真正的滚动容器:键盘滚动、边缘按钮和区域名称的工作方式与不吸附时相同。在“减少动态效果”下,吸附分页的运动遵循 spec:AST-094。
  • AR4 — 按钮不破坏焦点环。 边缘按钮位于滚动器的焦点环内,并且从不覆盖它 (architecture:interaction-modality INV1)。

设计关系

目前尚无设计记录约束 Carousel。边缘按钮的视觉呈现仍由代码和视觉证据来体现。

家族与系统关系

  • spec:AST-085 FR4 让组件为其移除的控件指定一个焦点目标;FR2 指定滚动区域。
  • spec:AST-025 FR12 负责滚动区域的 Tab 停留点和命名。
  • family:buttons 负责边缘按钮在可用时的行为。
  • spec:AST-094 FR3、FR6 和 DEC-25 负责分页规则,并确定吸附分页运行 (FR7)。内部分页器仍为内部实现。
  • component:Lightbox FR7 使用相同的内部分页器和规则对其图库分页。其页面是它自行驱动的一行中的全宽项目,因此它不接受 SnapPaging 值;它共享规则,而非配置。
  • architecture:public-component-api INV22 默认不赋予 useSnapPaging 任何非 React 等价物,因为它的值仅供给 Carousel 的 hasSnap。

验证映射

契约 验证 代表性状态 变更或失败预期 审计章节
FR1, AR1 单元测试与无障碍树测试;在 Chromium 和 WebKit 中对所持行进行真实浏览器测试 在每个边缘静止;无溢出;在吸附分页下,从每个边缘轻扫一次并按下末端按钮 可聚焦或暴露在无障碍树中的隐藏按钮失败;所持行离开其边缘后,边缘按钮在超过两帧后恢复也同样失败 audit:Carousel/accessibility
FR2, AR2 真实浏览器键盘测试 在“Scroll right”上按 Enter 直至末尾;在起始处同样操作 焦点位于页面主体、隐藏按钮或相反按钮上时失败 audit:Carousel/accessibility
FR3 真实浏览器测试,包含轻扫与调整大小 焦点在轮播外部时到达边缘 焦点在未按下边缘按钮的情况下移动,或对同一边缘移动两次,则失败 audit:Carousel/accessibility
FR5, FR6 滚动区域样式与监听器的单元测试 hasSnap 缺失、为 false、为 true,以及一个 SnapPaging 值;每视图一项和三项 在 hasSnap 省略或为 false 时进行吸附、停止位置不是每个子项的起始边缘、在 hasSnap={true} 下存在手势监听器、hasSnap={true} 时翻页、或分页停止位置与原生吸附不一致,均失败 —
FR7, AR3 在 Chromium 和 WebKit 中进行真实浏览器触摸与触控板测试:在粗主指针和细主指针下,分别使用手指和触控板轻扫,每种情况都针对默认配置和 {pages: 'item'} 配置 每视图一项;每视图三项;最后一页不完整;从右到左;超过 300 pt/s 的短促轻扫;在半个页面前后缓慢释放;每视图三项时使用边缘按钮步进;鼠标滚轮;hasSnap={true} 下的触控板轻扫 静止停止位置不符合 FR7、每次轻扫移动超过一页、在每视图三项的默认轻扫中移动一项、{pages: 'item'} 轻扫移动超过一项、最后一项之后出现空白、从右到左轻扫未镜像、细指针触控板轻扫未翻页、鼠标滚轮触发分页器、或 hasSnap={true} 时翻页,均失败 —
AR4 CarouselFocusRing.a11y.chromium.spec.ts:在 Chromium 中,聚焦滚动器焦点环的真实浏览器像素 静止;滚动中,对同时显示两个滚动按钮的层级进行采样 任一按钮位置处的焦点环像素若不是焦点环的颜色,则失败 audit:Carousel/accessibility
FR7 在桌面宽度和手机宽度下预览 stories,覆盖手指、粗指针和细指针下的触控板,以及鼠标滚轮的使用 每视图一项;每视图三项;部分最后一页;从右到左;分别使用 hasSnap、hasSnap={useSnapPaging()} 和 hasSnap={useSnapPaging({pages: 'item'})} 缺少 story,或 story 的分页停止点与其原生 snap 停止点不同,则失败 —
FR7 停止点的单元测试;在 Chromium 和 WebKit 中的真实浏览器测试,分别使用手指和鼠标滚轮 距离末端不到其前一步长一半的停止点;一次将其进一步移离末端的调整大小 如果轻弹或滚轮停留在该停止点、从末端后退的距离短于一个完整步长、或者该停止点在进一步远离末端后仍被原生 snap 跳过,则失败 —
FR8 针对 Core 源码的打包测试,使用 size report 的 esbuild 选项,其 eager 输出按模块归因,并包含阳性对照;对被保持的行进行真实浏览器测试 仅 Carousel;带 useSnapPaging 的 Carousel;模块的服务端导入;静止时按下边缘按钮,以及在 snap 分页下轻弹 一个没有 hasSnap={useSnapPaging()} 却打包了 pager 代码的 Carousel、import() 该 pager、或在 import 时执行 DOM 操作,均失败;同样,按下边缘按钮后脱离分页状态,以及边缘滞后于被保持的行,也会失败 —
FR9 Carousel 中 hook 的单元测试 Carousel 中的 hook;Carousel 在稳定过程中卸载或丢弃该值 Carousel 卸载或丢弃该值后仍残留监听器,或提供该 hook 的公共 create… 等价物,则失败 —

决策日志

DEC-1 — 滚动区域在边缘按钮用完时获得焦点

Reference: component:Carousel/DEC-1 Decider: cixzhang, 2026-10-22

Carousel 会隐藏方向已用完的边缘按钮,因此继续将焦点保持在其上会让键盘用户停留在不可见控件上。滚动区域始终挂载在带标签的区域内,无论是否在 Tab 顺序中都可以获得焦点,因此焦点移到那里可让用户仍停留在 Carousel 内部。

已否决:另一侧的边缘按钮——它同样可能被隐藏,而且焦点会跳过整个 Carousel。

DEC-2 — hasSnap 接受原生 snap 或来自 useSnapPaging 的分页配置

Reference: component:Carousel/DEC-2 Decider: cixzhang, 2026-11-02

分页来自一个返回分页配置的 hook,即 useSnapPaging。像 usePaging 这样的普通名称会显得过于通用,并与 Pagination 冲突。

配置放在 hasSnap 上,即已发布的 snap 属性:hasSnap={useSnapPaging()}。 一个属性决定轮播图如何吸附。省略或设为 false 时不吸附,true 是原生 CSS 滚动吸附(与已发布行为一致),而该配置则是在相同的逐项停靠点上进行吸附分页。hasSnap 的类型从 boolean 扩展为 boolean | SnapPaging:这是一个纯增量补丁,没有重命名、弃用或 codemod。只有分页配置会打包分页器(FR8)。

这第三种状态偏离了 architecture:public-component-api 的 INV3,后者要求 is… 或 has… 布尔值仅表示真/假开关。该偏离为构建者保留了一个 snap 属性,且该记录将其列为已知偏差。

一页即一视图:默认情况下,一次轻扫移动一个视图,停靠在距一个视口最近的条目起始边缘,而最后一页则停留在行的末端。{pages: 'item'} 每次轻扫移动一个条目。视图分页与 UIKit 分页滚动视图一致,后者每次轻扫移动一个视口宽度。

已否决:在 hasSnap 旁边再设一个独立的分页属性——两个属性描述同一个选择,构建者还得弄清楚哪个优先。

命名家族 useSnap<Variant> 代表未来的吸附行为。每个变体都是独立的 hook,因此应用只打包其导入的变体,且每个变体只保持一种行为。它们的值只提供给 hasSnap,因此默认情况下没有非 React 等效实现(architecture:public-component-api INV22)。

原生 CSS 滚动吸附是默认方案,因为它在所有浏览器中都能工作,并且使用平台自身的动量。CSS 轮播特性(::scroll-button()、::scroll-marker、:target-current、scroll-state 查询、snap 事件、interactivity: inert)仅在 Chromium 中提供,另一个引擎存在未解决的可访问性和国际化问题,因此 Carousel 保留自己的按钮。吸附分页只做原生吸附做不到的事:UIKit 的分页规则,以及在手指和触控板轻扫下的稳定停靠。滚动驱动动画在所有引擎中均可用,适合进度或幻灯片效果。

未决问题

无。

内容边界

本文件不重复消费者属性表/示例、当前审计结果、实现步骤或家族/系统规则,而是链接到它们的所属文档。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx