跳转至

ChatMessageList 组件契约

契约一览

领域 契约
公共契约 children、emptyState、scrollToTopAction、density、gap、align、根元素的 BaseProps<HTMLDivElement> 以及 ref。
行为 一个有礼貌的日志保存调用方的消息。density 选择行间距并传递上下文。顶部哨兵可以请求更早的消息。短列表默认停留在块末尾。
对最终用户的影响 读者获得一个可聚焦的、有礼貌的对话日志,该日志会在响应流式输出时进行报告;当滚动到顶部时,会加载更早的消息。
对构建者的影响 无。
兼容性/就绪状态 记录已发布行为;无公开变更。一个实现差距列于“当前状态影响”下;两个所有者问题仍然开放。
审查检查 拒绝以下说法:列表拥有 ChatLayout 自动滚动、此记录解决了加载重叠策略,或 DOM aria-busy 证明了语音输出。
治理规则 architecture:public-component-api/INV1, INV5–INV8; architecture:react-component-runtime/INV3, INV5–INV6; spec:AST-029/FR2–FR5.

此表是审查摘要;以下正文才具有权威性。

意图

ChatMessageList 是 Chat 组合中的展示性消息容器。它拥有一个 flex-column 会话记录、间距/密度上下文、可选的空状态和更早消息哨兵,以及该日志渲染出的 ARIA 属性。ChatLayout 拥有自动跟随滚动和停靠区;消息和气泡组件拥有发送者呈现和内容。

使用方的 prop 语法和示例保留在 ChatMessageList.doc.mjs 中。

兼容性与迁移

  • 已发布默认值保留:yes
  • 兼容性类别:记录已发布行为;无公开变更
  • 受控/非受控行为:不适用;此组件上没有受控值。
  • 迁移决策:无。

当前状态影响

  • 底部对齐使用了一个额外的元素。 align="bottom" 会在消息之前渲染一个 flex 间隔元素,以将短列表向下推。当列表溢出时,折叠后的间隔元素仍会在第一条消息上方留下一个行高的间隙。 在没有消息时,间隔元素占据可用空间的上半部分,因此空状态大约位于自上而下四分之三处,而不是居中。 architecture:component-style-authoring INV7 要求通过组件已经拥有的元素上的样式来表达布局,而不是添加额外的元素。

所有权边界

拥有

  • 外层日志元素、其公开的 DOM/ref/style 透传,以及带有 density 选择器的 chat-message-list 目标。
  • 内部 flex-column 消息框,以及基于 density 的内边距和间距。
  • 短列表停留的位置:bottom 对应块末尾,top 对应块开始。
  • 可选的 emptyState 替换,以及更早消息哨兵/加载指示器。
  • 在存在布局时,将内部内容元素传递给 ChatLayoutContext.contentRef。

不拥有 / 非目标

  • 自动滚动、滚动到底部、停靠区以及滚动持有者选择,这些属于 component:ChatLayout 及其滚动 hooks。
  • 发送者身份、消息对齐、气泡、元数据和文本语义,这些属于它们的子组件。
  • 调用方的 region 地标或任意会话记录上下文的无障碍名称;本记录不制定命名策略。

公共概念

概念 封闭值或状态 含义 可用性 默认值 持有者 稳定性 无效值行为
children ReactNode 顶层会话内容 每次渲染 必填 调用方 稳定 null、false 或 [] 在顶层视为空
emptyState ReactNode;省略 在顶层子内容为空时进行替换 空状态 省略 调用方 稳定 省略时不渲染任何替代内容
scrollToTopAction 异步函数;省略 当顶部哨兵相交时调用 提供时 省略 调用方 稳定 省略时不创建哨兵或观察器
density compact;balanced;spacious 选择消息间距和子级 density 上下文 每次渲染 balanced 组件 稳定 封闭类型联合
gap 已发布的 SpacingStep;省略 独立于 density 覆盖列表的顶层行间距 每次渲染 省略 调用方 稳定 封闭类型联合
align top;bottom 将短内容定位在起始处或块末尾 每次渲染 bottom 组件 稳定 封闭类型联合
isStreaming true; false 流式输出期间,在 polite 日志上暴露 aria-busy 每次渲染 false 调用方 稳定 boolean
根元素透传 ref、受支持的 DOM/数据/ARIA 与样式属性 扩展最外层的日志元素 每次渲染 省略 调用方 稳定 组件自有的 role/live/busy 属性保持优先级

该表记录的是实现层面的顶层为空检测;它不承诺递归检查子节点,也不解析任意非渲染 React 节点的含义。

行为与布局契约

ID 不变量 依据
FR1 外层根元素渲染 role="log"、aria-live="polite" 和 tabIndex=0;isStreaming=true 时添加 aria-busy="true",否则不包含该属性。 当前源码、测试与文档
FR2 所选密度以 data-density 的形式体现在根元素上,并通过 ChatListContext 传递给子消息;它从三组间距中进行选择。 当前源码、测试与文档
FR3 可选的 gap 仅替换顶层行间距;密度仍负责选择内边距和上下文。 当前源码、测试与文档
FR4 仅当 children 为 nullish、false 或空顶层数组时,emptyState 才会渲染。否则,传入的 children 原样渲染。 当前源码与测试
FR5 使用 align="bottom" 时,短列表位于块末端;使用 align="top" 时,位于块起始端。溢出内容采用相同的渲染路径。实现缺口:底部放置使用额外的间隔元素,当列表溢出时,这也会在第一条消息上方留下一个行间距(当前状态影响)。 当前源码与测试
FR6 提供 scrollToTopAction 会创建一个被观察的顶部哨兵元素。发生交叉时会启动其异步过渡,等待期间渲染位于顶部的加载指示器。 当前源码、测试与文档
FR7 在 ChatLayout 内部,内部内容元素会传递给布局的 contentRef,并在清理时从该注册中移除;独立列表没有布局 ref。 当前源码
FR8 根元素接收 ref、受支持的 DOM/数据/ARIA 属性,以及组合后的 className、style 和 xstyle;组件自有的日志语义在转发属性之后应用。 当前源码;architecture:public-component-api

对于 emptyState 插槽,数字 0 是可见内容。nullish 值、布尔值和空字符串不会创建空的包装元素。这仅描述标量输出;它不决定如何检查嵌套子节点。

允许的变化

  • AV1 - 内容。 任何调用方拥有的 ReactNode 都可以放入列表中;列表不会从 children 推断发送者元数据。
  • AV2 - 间距。 密度选择基于 token 的默认值;可选的 gap 选择已发布的间距档位,而不改变子密度。
  • AV3 - 滚动所有权。 列表可以单独使用,也可以在 ChatLayout 内部使用;自动跟随行为仍不属于此组件的职责范围。

代表性状态

状态 必需的不变量 允许的变化
----------------------------- -------------------------------------------------------------------------------------------------------------------------------------- ------------------------------------------
两条消息和一个系统行 消息按源顺序排列的 polite 日志 调用方控制行内容
顶级子节点为空 可选的空状态在 top 时居中于整个列表;在 bottom 时居中于 spacer 下方(当前状态影响) 省略空状态会留下一个空日志
紧凑/均衡/宽松 不同的、由 token 推导的行间距和子内容 density gap 只能覆盖行间距
较短的 top/bottom 列表 bottom 停靠在块末尾,top 停靠在块起始处 容器高度由调用方控制
流式 日志具有 aria-busy=true 消息内容仍由调用方控制
顶部操作挂起 转换挂起时,内容上方显示 spinner 异步操作结果由调用方控制

性能与资源

  • PR1 — 哨兵观察器。 仅当存在 scrollToTopAction 时才安装 IntersectionObserver,并在清理时断开。其 root 在可用时为 ChatLayout 的滚动容器,否则为文档视口。
  • PR2 — 布局注册。 内部内容元素向 ChatLayout 注册,并在清理时清除注册。

无障碍契约

  • AR1 — 日志语义。 根元素是一个可聚焦的 polite 日志,其 aria-busy 反映 isStreaming (FR1);这里描述的是浏览器暴露的语义,而不是屏幕阅读器的播报文本。
  • AR2 — 无键盘模型。 加载 spinner 是日志的一个独立子元素。列表本身不添加交互按钮或方向性键盘行为。
  • AR3 — 调用方内容。 调用方提供的内容仍负责消息内部的名称和语义。

设计关系

没有记录组件局部的设计决策。间距使用可移植的语义 token 步进。家族消费方文档拥有已发布的 chat-message-list 主题目标及其 density 轴。尚未记录解剖学主题映射;该区块在迁移期间是可选的,因此该映射被推迟。

家族与系统关系

  • 目前不存在 family:chat 权威记录。Chat.doc.mjs 是消费方家族文档,而不是产品权威的家族契约。
  • ChatLayout 拥有滚动容器并提供 contentRef;列表注册其内容元素,而不会接管 ChatLayout 的滚动。
  • spec:AST-029 拥有本记录验证映射所遵循的审计证据清单。

验证映射

契约 验证 代表性状态 变更或失败预期 审计章节
FR1, AR1 ChatMessageList.test.tsx 中的 role 与 aria-busy 测试;ChatMessageList.a11y.chromium.spec.ts 中的 aria-live 断言 静止、流式 日志 role 或 busy 状态丢失则失败。 audit:ChatMessageList/§1
FR2–FR3 ChatMessageList.test.tsx 中的 density 与 gap 测试 各密度;gap 覆盖 density 未被体现,或 gap 改变了 density,则失败。 audit:ChatMessageList/§2
FR2 ChatMessage.test.tsx 中的“继承列表 density,并允许显式 prop 覆盖它”;ChatMessageBubble.test.tsx 中的 list-density 用例 列表中的子消息 density 无法传递到子消息时失败。 audit:ChatMessageList/§2
FR7 ChatLayout.test.tsx 中的“first-fill 滚动定位”用例;useChatNewMessages.test.tsx 中的“与 ChatLayout 条件式 ChatMessageList 端到端协作” ChatLayout 内的列表 如果列表停止注册其内容元素,则失败。 audit:ChatMessageList/§7
FR4 ChatMessageList.test.tsx 中的空状态测试 空;数字空状态 缺少空状态,或丢弃数字空状态,则失败。 audit:ChatMessageList/§4
FR6 ChatMessageList.test.tsx 中的“通过顶部哨兵加载更旧消息并暴露 pending 状态” pending、settled 操作丢失或 spinner 卡住则失败。 audit:ChatMessageList/§6

从源码中读取,尚无针对性测试:

  • FR1:日志上的 tabIndex=0。
  • FR2:每个 density 选择的间距。
  • FR3:gap 替换顶层行间距。
  • FR4:null 和 false 子节点选择空状态。
  • FR5:短列表停靠的位置;spacer 测试会计算位于当前状态影响 gap 背后的新增元素。
  • FR7:在清理时移除注册。
  • FR8:根元素上的 ref、DOM、data 与 ARIA props、className、style、xstyle,并且自有日志语义优先于转发的 props。
  • PR1–PR2:观察器的 root,以及注册清理。

决策日志

未记录任何组件局部决策。

未决问题

  • OQ1 - 当异步加载仍处于挂起状态时,重复的顶部哨兵交叉的预期重叠策略是什么? (human-api) 当前源码在交叉时调用该操作;本记录并未添加 single-flight、初始加载或耗尽保证。
  • OQ2 - 空值判断是否应检查嵌套的不渲染 ReactNode 值? (human-api) 随附测试仅限于顶层 children 值。请勿将该测试重新解释为关于生成器、片段、Promise 子节点或不渲染的值数组的策略。

内容边界

本文件不会重复使用方 props 表或示例、ChatLayout 的滚动行为或跨组件视觉策略,而是提供指向其所属文档的链接。

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