ChatVirtualizer 组件契约¶
契约概览¶
| 领域 | 契约 |
|---|---|
| 公共契约 | @astryxdesign/lab 导出 ChatVirtualizer、其 props 和其 handle。此记录仅保存列表在其所窗口化的聊天记录之外所拥有的内容;使用方用法见其 .doc.mjs。 |
| 行为 | 该列表保持视口附近的行处于挂载状态,跟随最新消息,并在上方行测量进入时保持读者所在行静止不动。 |
| 最终用户影响 | 阅读长聊天记录的人获得与未窗口化记录相同的滚动体验、键盘访问和屏幕阅读器播报。 |
| 构建者影响 | 调用者在 ChatMessageList 内渲染它,或将其附加到他们自己拥有的滚动容器上。 |
| 兼容性/就绪度 | 附加型实验性 Lab 组件;在负责人评审和真实设备验证定案之前保持草稿状态。 |
| 评审检查 | 拒绝在 Core 之外存在第二套锚定规则或触摸监听器,拒绝键盘焦点下的聚焦行被卸载,以及拒绝将历史行播报为新消息。 |
| 治理规则 | architecture:public-component-api INV23、architecture:react-component-runtime、spec:AST-025 FR12、spec:AST-086 FR1 和 spec:AST-094。 |
此表为评审投影;以下正文具有权威性。
意图¶
ChatVirtualizer 让包含数千条消息的聊天记录只消耗大约一个视口的 DOM。它负责窗口化及其位置。向辅助技术传递新消息、浏览器的滚动锚定规则,以及手指滚动的监听,仍归各自的所有者负责。
兼容性与迁移¶
- 保留已发布默认值:
yes(新的 Lab 组件) - 兼容性类别:附加型实验性
- 受控/非受控行为:不适用
- 迁移决策:无
所有权边界¶
拥有
- 哪些行已挂载、代表其余内容的占位符(spacer),以及它恢复的滚动位置(follow-at-end 或某行标识)。
- 在窗口移离某行时,保持持有焦点的行仍处于挂载状态。
- 通过 Core 的
useScrollableArea提供其自身滚动容器的键盘访问。
不拥有 / 非目标
- 浏览器的滚动锚定规则:列表只能通过 Core 的滚动锚定写入器关闭锚定,该写入器是该规则的唯一所有者。
- 区分手指滚动与程序滚动以及何时结束:Core 的
useFingerScroll决定这两者;在该滚动持续期间,列表会暂停其scrollTop写入。 - 向辅助技术传递新消息:
ChatMessageList的role="log"负责传递(spec:AST-086FR1)。
公共概念¶
| 概念 | 封闭值或状态 | 含义 | 按变体/方向/状态的可用性 | 默认值 |
|---|---|---|---|---|
| 容器模式 | 自有容器、附加 | 列表是渲染自己的滚动容器,还是使用调用者的 | scrollElement 不存在,或为一个元素 |
自有容器 |
| 滚动容器名称 | 调用者的 label,或默认值 |
列表自有滚动容器的无障碍名称(AR1) | 仅限自有容器模式 | "Messages" |
行为与布局契约¶
| ID | 需求 | 依据 |
|---|---|---|
该列表保持视口附近的行处于挂载状态,跟随最新消息,并在上方行测量进入时保持读者所在行静止不动。它通过一个滚动容器、一组触摸监听器和一条锚定规则来实现,这些都归当前生效的运行时架构所有。它不得形成第二套。它只为其拥有的滚动写入 scrollTop:follow-at-end 或 stable-row。它绝不会为手指滚动写入。它在自身重绘期间保持某行聚焦。它将聊天记录的 log 语义和新消息播报留给 ChatMessageList。它将滚动锚定规则留给 Core 的唯一写入器。它不会在 Core 自身的分类之外再区分焦点、鼠标或触摸滚动:运行时自身的滚动机制是列表 scrollTop 写入的唯一输入。声明式与命令式用法都遵循同一契约。 |
||
| FR1 | 当列表的滚动容器挂载时,列表通过 Core 的滚动锚定写入器关闭浏览器在其上的滚动锚定,并在卸载时恢复;调用方自身的 overflow-anchor 永远不会被读取或写入。 |
当前源代码和测试 |
| FR2 | 当手指滚动列表时(从首次滚动到滚动结束,包括惯性滚动,正如 useFingerScroll 所报告的那样),列表不会写入 scrollTop;位置修正作用于顶部占位元素,并在该次滚动结束时稳定下来。 |
当前源代码和测试 |
| FR3 | 当窗口移离某行时,持有焦点的该行保持挂载,并在该行与窗口之间放置一个占位元素,从而使滚动几何形状保持不变。 | 当前源代码和测试 |
| FR4 | 当列表的读者滚动时,列表会在每个滚动事件中,以一次批量处理的方式、在任何写入之前,读取滚动器的滚动位置和尺寸,因为它所挂载的行依赖于这些值;滚动处理函数不向 DOM 写入任何内容,因此不会强制产生布局。只有当内容发生变化(追加、某行测量尺寸、或窗口挂载其他行)、滚动器尺寸发生变化、某个尺寸相关属性发生变化(overscan、估算行尺寸、行类型读取器)、调用方声明位置、手指滚动结束,或者在页面滚动器上浏览器因视口变化而滚动时(在该变化对应的处理之前至多一次、之后一次),才会运行一次纠正处理;一次滚动写入被浏览器钳制的处理会在下一帧再运行一次,而历史加载的处理则会在下一帧释放其占用。它绝不会仅因滚动事件而运行,也不会为未改变上述任何内容的提交而运行,例如父组件以相同行重新渲染。每次处理都会写入其占位元素,进行一次批量读取,写入其占位元素和滚动位置,并再次读取滚动位置以认领浏览器自行做出的任何移动,因此它最多强制两次布局(architecture:react-component-runtime INV18)。旋转设备时,原本位于视口顶部的行会在两个方向上均保持原位:浏览器在视口尺寸变化时自行设置的滚动位置并非列表自身的滚动,下一次处理会恢复该行。 |
architecture:react-component-runtime INV18 |
无障碍契约¶
- AR1 — 键盘访问。 在自有容器模式下,滚动容器是一个由列表的
label命名的group,否则使用翻译后的“消息”;键盘用户可聚焦并滚动它(spec:AST-025FR12)。在附加模式下,调用方的滚动器拥有此职责。 - AR2 — 历史不是新消息。 如果某次提交挂载的不是新消息行(窗口在历史记录上移动,或在历史记录上方加载),则会将内容块标记为
aria-busy="true",直到其后一帧为止,以便日志不会将这些行作为新消息读出。在尾部追加的消息以未标记方式挂载,日志会将其送达。
设计关系¶
除 Chat 家族自身的记录外,没有其他关系。
家族与系统关系¶
component:ChatMessageList拥有会话记录的日志及其投递。component:ChatLayout在其滚动器上运行自己的跟随逻辑,因此列表不会附加到它。
验证映射¶
| 契约 | 验证 | 代表性状态 | 变更或失败预期 | 审计章节 |
|---|---|---|---|---|
| AR1 | 无需键盘:这些操作不需要键盘,因此键盘透传不适用;所以无需验证。 | N/A | N/A | 无障碍审计章节 1 |
| -------- | ---------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
| FR1 | ChatVirtualizer.test.tsx 锚定测试 |
附着模式,调用方内联 overflow-anchor |
锚定保持开启、调用方的内联值改变,或卸载后属性仍被保留,均会导致失败。 | audit:ChatVirtualizer/behavior |
| FR2 | ChatVirtualizer.test.tsx 手指滚动测试 |
手指按下、抬起后的惯性滚动、滚动结束、无手指触控 | 在手指滚动期间写入 scrollTop,或滚动结束后闸门仍处于保持状态,均会导致失败。 | audit:ChatVirtualizer/interaction |
| FR3, AR1 | ChatVirtualizer.test.tsx 键盘测试 |
默认状态和调用方标签;一个聚焦行被滚动移出视图 | 缺少组名,或聚焦行卸载,测试失败。 | audit:ChatVirtualizer/a11y |
| AR2 | ChatVirtualizer.test.tsx 的 busy 测试、线程加载 busy 测试、首条消息测试、历史到达测试和线程切换测试 |
窗口在历史记录上移动;跟随状态下尾部追加;阅读者处于历史记录中时尾部追加,随后流式到达;阅读者处于历史记录中时另一个线程替换行;在跟随状态下和处于历史记录中时各追加一个 2,000 行批次;一个线程加载到空列表中,以及一个线程替换行;空对话记录的第一条消息 | 历史记录在没有 aria-busy 的情况下挂载(包括已加载或替换行的线程)、在阅读者处于历史记录中时尾部追加(包括空对话记录的第一条消息)被标记为 busy 或保持未挂载、或被替换的线程或追加的批次挂载了超过一个窗口的行,都会失败。证据缺口:aria-busy 是否能防止历史记录被朗读因屏幕阅读器而异;在完成 VoiceOver 和 NVDA 检查前,朗读行为未经验证。 |
audit:ChatVirtualizer/a11y |
| FR4 | ChatVirtualizer.test.tsx 布局跟踪:读取滚动几何、矩形和行大小,并写入间隔占位元素和 scrollTop |
跟随状态下追加;向上滚动到历史记录;在历史记录中追加;一次快速滑动产生的滚动事件序列;父组件以相同行重新渲染 | 超过两个写后读回合(即两次强制布局)的修正扫描、写入 DOM 或多次读取滚动器大小的滚动事件,或者针对不改变任何所读取内容的提交所进行的扫描,都会失败。 | audit:ChatVirtualizer/behavior |
| FR4 | ChatVirtualizerPageScroller.interaction.browser.spec.ts |
attach 模式下的 document.scrollingElement,上方有一个表头,其后是超过 10,000 行高度各异的行,锚定到第一行;向下滚动页面再滚回 |
页面离开第一行,或十次检查中的任一次或滚动后视图中没有行,则失败。 | audit:ChatVirtualizer/behavior |
| FR4 | ChatVirtualizerViewportResize.test.tsx |
attach 模式下的页面滚动器:一次宽度拖拽、一次仅高度变化、在宽度变化后下一帧中的仅高度变化,以及同一帧内三次 resize 事件 | 一次视口变化对应多于一次修正轮、缺少修正轮,或读取窗口大小失败,则失败。 | audit:ChatVirtualizer/behavior |
| FR4 | ChatVirtualizerRotation.test.tsx |
attach 模式下的页面滚动器,读取历史中段:旋转为竖屏且行更高,分别在有和没有浏览器缩放滚动位置的情况下;旋回横屏;在修正轮稳定后、列表自身写入的 scroll 事件之后,发生一次迟到的浏览器滚动写入;在 resize 事件之前发生一次浏览器滚动;旋转后紧接着一次滚轮或按键,也包括其处理函数停止传播的按键;旋转后运行一系列脚本化 scroll 事件;在列表自身滚动器高度变化时在其上滚动;在旋转过程中保持 follow-at-end;手指滚动期间发生旋转 | 被保持行的顶部边缘离开视口顶部、读者的滚轮/按键/自身滚动器滚动被回退、一系列 scroll 事件对应列表写入超过一次、follow-at-end 丢失,或手指滚动期间发生滚动写入,则失败。 | audit:ChatVirtualizer/behavior |
决策日志¶
无记录。
未决问题¶
无。
内容边界¶
本文件不重复消费者属性表/示例、当前审计结果、实施步骤或家族/系统规则。它链接到其所有者。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx