跳转至

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-086 FR1)。

公共概念

概念 封闭值或状态 含义 按变体/方向/状态的可用性 默认值
容器模式 自有容器、附加 列表是渲染自己的滚动容器,还是使用调用者的 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-025 FR12)。在附加模式下,调用方的滚动器拥有此职责。
  • 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