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(吸附与吸附分页)。
消费者迁移说明应放在消费者文档和发布说明中。
所有权边界¶
拥有
hasSnapprop、其原生吸附及其吸附分页值,以及useSnapPagingAPI。- 吸附分页在轮播图上使用哪些停靠点,以及一页是什么(FR7)。
- 边缘滚动按钮的可见性、Tab 顺序,以及方向用完时的焦点目的地。
不拥有 / 非目标
- 分页规则、稳定行为及其测量值 —
spec:AST-094FR3、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-modalityINV1。 - AR3 — 吸附保留所有路径。 在原生吸附和吸附分页下,滚动区域仍然是真正的滚动容器:键盘滚动、边缘按钮和区域名称的工作方式与不吸附时相同。在“减少动态效果”下,吸附分页的运动遵循
spec:AST-094。 - AR4 — 按钮不破坏焦点环。 边缘按钮位于滚动器的焦点环内,并且从不覆盖它 (
architecture:interaction-modalityINV1)。
设计关系¶
目前尚无设计记录约束 Carousel。边缘按钮的视觉呈现仍由代码和视觉证据来体现。
家族与系统关系¶
spec:AST-085FR4 让组件为其移除的控件指定一个焦点目标;FR2 指定滚动区域。spec:AST-025FR12 负责滚动区域的 Tab 停留点和命名。family:buttons负责边缘按钮在可用时的行为。spec:AST-094FR3、FR6 和 DEC-25 负责分页规则,并确定吸附分页运行 (FR7)。内部分页器仍为内部实现。component:LightboxFR7 使用相同的内部分页器和规则对其图库分页。其页面是它自行驱动的一行中的全宽项目,因此它不接受SnapPaging值;它共享规则,而非配置。architecture:public-component-apiINV22 默认不赋予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