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-authoringINV7 要求通过组件已经拥有的元素上的样式来表达布局,而不是添加额外的元素。
所有权边界¶
拥有
- 外层日志元素、其公开的 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