跳转至

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