ChatMessageMetadata 组件契约¶
契约一览¶
| 区域 | 契约 |
|---|---|
| 公共契约 | 可选 timestamp 和 footer ReactNode 插槽,可选封闭 status 联合类型,根级 BaseProps<HTMLDivElement> 和 ref,通过 ./Chat 导出。 |
| 行为 | 该行按照 timestamp、footer、status 的顺序渲染出现的插槽,且仅在出现的插槽之间显示分隔符;用户发送者会反转 flex 行方向。五种投递状态具有本地化的图标与文本展示。 |
| 最终用户影响 | 读者按阅读顺序看到由时间、额外详情和投递状态组成的紧凑行,仅在显示内容的项目之间有点号,并且每个状态图标旁有说明文字。 |
| 构建者影响 | 无。 |
| 兼容性/就绪状态 | 记录已发布行为;无公开变更。有一个实现缺口,列于“当前状态影响”之下;两个拥有者问题仍未解决。 |
| 审查检查项 | 拒绝以下情况:丢失可见的 0、孤立分隔符、遗漏的状态翻译说明文字或标题、丢失根级透传,或声称静态 DOM 属性即可证明 AT 公告生效。 |
| 规范规则 | architecture:public-component-api/INV1, INV3, INV5–INV9;architecture:component-test-sufficiency/INV1–INV7;spec:AST-029/FR2–FR5。 |
此表是审查投影;以下正文为准。消费者语法属于 ChatMessageMetadata.doc.mjs。
意图¶
ChatMessageMetadata 是聊天消息下方可选显示的紧凑行。它在感知发送者的 Chat 组合中呈现调用方拥有的 timestamp/footer 内容以及可选的投递状态。它不是消息正文、气泡表面、会话记录或 footer 控件的拥有者。
兼容性与迁移¶
- 已发布的默认值保留:
yes - 兼容性类别:记录已发布行为;无公开变更
- 受控/非受控行为:不适用;该组件不存储投递状态。
- 迁移决定:无
消费者迁移说明属于消费者文档和发布说明。
当前状态影响¶
- 状态标签可能不会被读取。 状态 span 带有翻译后的
aria-label但没有 role。WAI-ARIA 1.2 禁止为具有通用 role 的元素命名,因此辅助技术可能忽略该标签而只读取可见的说明文字(FR6)。
所有权边界¶
拥有
- 可选的元数据根节点、其
chat-message-metadata绘制目标、ref、中性 DOM 透传,以及组合的样式输入。 - timestamp、footer 和 status 之间的存在性检查与分隔符。
- 由最近的 Chat 消息上下文决定的、相对于发送者的行顺序,在该上下文之外回退为 assistant。
- 状态到图标(glyph)的映射与翻译说明文字的选择,以及本地的 sending/error 绘制路径。
不拥有 / 非目标
- 发送者身份、文章语义、头像、姓名和正文对齐:
ChatMessage拥有这些。 - 气泡内边距与放置:
ChatMessageBubble拥有这些。 - Footer 操作语义、按钮焦点和回调行为:调用方提供的内容拥有这些。
- 会话记录滚动、加载或投递状态转换:周围的组合拥有这些。
- 为检查复合、惰性或异步 ReactNode 值而新增的公共规则,或屏幕阅读器公告时机的保证。
公共概念¶
| 概念 | 封闭值或状态 | 含义 | 可用性 | 默认 | 拥有者 | 稳定性 | 无效值行为 |
|---|---|---|---|---|---|---|---|
timestamp |
省略或调用方 ReactNode | 可选的第一个项目,通常是时间 | 任何组合 | 省略 | 调用方 | 稳定 | Null、布尔值和空字符串不渲染标量插槽;0 会渲染;非标量保持不透明 |
footer |
省略或调用方 ReactNode | 可选的中间项目,例如模型信息或调用方控件 | 任何组合 | 省略 | 调用方 | 稳定 | 与 timestamp 相同的标量处理 |
status |
sending、sent、delivered、read、error、省略 |
可选的投递说明文字和图标 | 任何组合 | 省略 | 组件/调用方输入 | 稳定 | 封闭类型联合;省略时不产生任何项目 |
| 发送方上下文 | user、assistant、system、absent |
选择用户反转或其他正向行顺序 | 在 ChatMessage 内或独立使用 |
缺省时为 assistant | ChatMessage / 本地回退 |
稳定 | 非 user 值共享正向路径 |
| 根表面 | BaseProps<HTMLDivElement>、ref、xstyle、className、style |
在元数据行存在时扩展该行 | 槽位通过标量存在性检查或存在 status | 空标量槽位且无 status 时缺省 | architecture:public-component-api |
稳定 | 非标量值保持不透明;目标样式与消费者样式合并 |
行为与布局契约¶
| ID | 不变量 | 依据 |
|---|---|---|
| FR1 | 当至少一个槽位通过共享的标量存在性谓词,或存在 status 时,根元素出现。非标量值被视为存在,且不检查其内部内容。 |
当前源码和测试 |
| FR2 | 被接受的槽位值按 timestamp、footer、status 的顺序渲染,并在被视为存在的值之间放置点;数字 0 在任一槽位中都可见,非标量节点保持不透明。 |
当前源码和测试 |
| FR3 | user 消息反转行方向;assistant、system 以及 absent 上下文使用正向路径。 |
当前源码 |
| FR4 | 状态从四个注册图标中选择一个(delivered 和 read 共用 checkDouble)以及本地化标签;failure 使用错误文本 token,sending 在 reduced motion 下具有被抑制的 CSS 脉冲。 |
当前源码和本地化目录 |
| FR5 | 根元素合并目标、默认 StyleX 输出以及消费者的 xstyle、className 和 style;被接受的中性 DOM/ARIA 输入和 ref 到达该根元素。 |
当前源码和测试 |
| FR6 | status 项具有翻译后的 title、图标和可见的本地化文本。该行不声明 live-region 角色,也不进行命令式播报。实现差距:status span 还带有翻译后的 aria-label,但没有 role(当前状态影响)。 |
当前源码和测试 |
允许的变体¶
- AV1 - 槽位内容。 调用方决定 timestamp 和 footer 槽位内部的结构与语义。此组件不检查非标量节点。
- AV2 - 主题。 语义颜色、字体排印和间距通过当前激活的 Theme 解析;根元素仍然是公开的元数据绘制目标。
- AV3 - 上下文。 独立使用时采用 assistant 排序回退。
代表性状态¶
| 状态 | 必需不变量 | 允许的变体 |
|---|---|---|
| 独立 timestamp | 一个根元素和一个可见项 | 调用方内容 |
| user 或 assistant 消息 | 相对于发送方的行顺序 | 从页面继承的文本方向 |
| timestamp + footer + status | 项根据标量存在性进行分隔;复合节点保持不透明 | 调用方 footer 内容 |
| 每个送达状态 | 不同的本地化标题和映射图标 | 当前翻译和主题 token |
| 不渲染的标量槽位 | 不存在孤立点;当所有项为空时没有行 | 复合节点保持不透明 |
数字 0 |
可见内容,而不是空标记 | 任一槽位 |
| 窄宽度下的长 footer | 内容在其容器内回流 | 调用方文本可能换行 |
转换与优先级顺序¶
- ORD1 - 先判断存在性,再放置分隔符。 使用共享谓词判断标量存在性,同时将非标量调用方节点视为不透明;然后在被视为存在的值之间放置标点。status 检查仍独立于各槽位检查。
- ORD2 - 组合。 解析发送方上下文,选择 flex 顺序,并在一个根元素上组合组件 StyleX、主题目标以及消费者的样式输入。
性能与资源¶
- PR1 - 渲染推导。 组件不创建本地 React 状态、Effect、计时器、观察器或事件监听器。其本地动画使用 CSS 实现,并在减少动态效果模式下被抑制。
无障碍契约¶
- AR1 - 显示语义。 元数据行不添加自身的按钮、焦点目标、列表角色或活动区域。可交互的底部内容保留其自身的语义和键盘行为。
- AR2 - 可见的投递状态。 状态说明文字伴随图标,因此状态识别不单独依赖颜色或图标。
- AR3 - 证据边界。 浏览器暴露的标记和 axe 覆盖范围不能确立语音输出或播报时机;任何此类未来声明需遵循
spec:AST-009及其指定的辅助技术证据规则。
设计关系¶
| 解剖部位或状态 | 设计要求 | 表现权威 | 层级角色 | 组件契约 |
|---|---|---|---|---|
| 元数据行 | 语义化辅助排版和相对发送者的阅读顺序 | 本地表示尚未确定 | 辅助 | FR2–FR3 |
| 投递状态 | 注册表图标、说明文字和语义错误标记 | 本地突出程度和动效选择尚未确定 | 辅助 | FR4, AR2 |
未记录组件本地设计决策。
家族与系统关系¶
- 目前没有
family:chat产品权威记录。Chat.doc.mjs是消费者组合指南,而非家族契约。 architecture:public-component-api负责根导出与透传;architecture:component-theming-surface负责公开绘制目标;architecture:component-test-sufficiency负责有界证据覆盖。spec:AST-029负责本记录验证映射所遵循的审计证据清单。
验证映射¶
| 契约 | 验证 | 代表性状态 | 变更或失败预期 | 审计章节 |
|---|---|---|---|---|
| FR1–FR2 | ChatMessageMetadata.test.tsx 分隔符、空行和数值零测试;ChatMessageMetadata.a11y.chromium.spec.ts narrow-overflow 和 status-* 用例 |
空标量;零;时间戳、底部、状态 | 多余的分隔符、空行或隐藏的零均判定失败。 | audit:ChatMessageMetadata/behavior |
| FR5 | ChatMessageMetadata.test.tsx forwards rest props (data-*, aria-*, id) to the root element |
data 和 id props | 丢失任一 prop 即判定失败。 | audit:ChatMessageMetadata/public-api |
| FR3, FR4, FR6 | ChatMessageMetadata.a11y.chromium.spec.ts 状态和 RTL 发送者排序测试;ChatMessageBubble.test.tsx "renders status" 和 "renders timestamp and status on one row" |
每种状态;LTR 和 RTL 下的用户与助手 | 发送者顺序错误,或缺少说明文字或标题即判定失败;气泡测试还在 FR6 缺口处固定了状态 aria-label。 |
audit:ChatMessageMetadata/behavior |
从源码读取,目前尚无专项测试:
- FR2:空标量槽位之后、
status之前的分隔符。 - FR3、AV3:
system及独立使用时的转发行。 - FR4:每种状态的图标、错误颜色、发送脉冲及其减少动态效果抑制。
- FR5:ARIA 透传、
ref、className、style和xstyle的组合,以及目标。 - FR6、AR1:该行自身没有活动区域。
- PR1:没有状态、Effect、计时器、观察器或监听器。
决策日志¶
未记录组件本地决策。
开放问题¶
- OQ1 - 非标量 ReactNode 槽位是否应进行空值归一化?(
human-api)在现有的标量谓词下,数组、Fragment、懒加载内容和 Promise 仍为不透明;组件不会消费或检查它们。 - OQ2 - 独立的投递状态变化是否应被播报?如果应播报,由哪个所有者负责?(
human-api)当前行仅用于显示。在没有当前所有者和适用的辅助技术证据的情况下,不作出任何语音时机声明。
内容边界¶
本文件不重复消费者 prop 表格或示例,也不重复共享视觉策略。它链接到其所有者。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx