跳转至

ChatMessage 组件契约

契约速览

领域 契约
公开契约 sender、children、avatar、name、metadata、density,外加消息 article 上的 BaseProps<HTMLElement> 和 ref。
行为 sender 控制逻辑对齐和系统消息抑制;density 按显式 prop → 消息列表上下文 → balanced 的顺序解析;后代组件接收已解析的上下文。
终端用户影响 阅读对话的用户可以区分用户、助手和系统消息,同时名称和本地化回退标签保留每条 article 的发送者身份。
构建者影响 无。
兼容性与就绪度 记录已发布行为;无公开变更。无实现缺口;有一个负责人问题仍未解决。
审查检查 拒绝任何会改变 sender 或 density 含义、将调用方内容视为组件所有、或将未解决的主题问题变成新 API 的变更。
治理规则 architecture:public-component-api/INV1, INV3, INV5–INV6, INV8–INV9;architecture:component-theming-surface/INV3–INV6;spec:AST-029/FR3–FR6。

此表是审查投影;以下正文为权威内容。

意图

ChatMessage 是对话中单条消息的、能感知 sender 的 article 包装器。它负责逻辑对齐、可选的发送者身份插槽、提供给消息后代组件的已解析 density 上下文,以及 article 的可访问名称。消息内容及其自身交互仍归调用方所有。

消费方语法和示例属于 ChatMessage.doc.mjs 和 Chat 家族文档。

兼容性与迁移

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

消费方迁移说明属于消费方文档和发布说明。

所有权边界

拥有

  • 一个语义化 <article> 根元素及其 public ref、DOM、data、ARIA、class 和 style 透传。
  • 由 sender 选择的逻辑起始、结束或居中对齐。
  • 为非系统消息提供可选的 avatar、name 和 metadata 放置,包括折叠渲染内容为空的插槽(DEC-1)。
  • density 解析以及提供给后代组件的 ChatMessageContext 值。
  • 带有 sender 和已解析 density 轴的 chat-message 目标。
  • article 的可视名称或本地化回退可访问标签。

不拥有 / 非目标

  • 气泡呈现、分组、宽度、名称或 metadata —— 当气泡提供这些时,由 component:ChatMessageBubble 拥有。
  • Avatar 外观 —— 由调用方提供的节点拥有,通常是 component:Avatar。
  • Metadata 内容、时间戳格式、状态或页脚操作 —— 由提供的节点及其组件拥有。
  • 消息列表排序、消息间距、流式通知或滚动行为 —— 由 component:ChatMessageList 和 component:ChatLayout 拥有。
  • children 内部的交互;后代组件保留其自身的语义和无障碍契约。

公共概念

概念 封闭值或状态 含义 按变体/方向/状态的可用性 默认值 所有者 稳定性 无效值行为
sender assistant;user;system 选择逻辑对齐、article 身份,以及辅助身份插槽是否显示。 每条消息中必填 必填 组件 稳定 封闭联合;被类型系统拒绝
children 任意 ReactNode 消息主体在内容对齐列内透传。 所有 sender 必填 调用方 稳定 不适用 — 必填
avatar 渲染内容;渲染为空;跳过标量;省略 非系统消息旁的可选身份节点。 assistant 和 user;对 system 抑制 省略 调用方 稳定 渲染为空:插槽折叠
name 渲染文本;渲染为空;跳过标量;省略 可选的可视发送者名称和 article 标签源。 assistant 和 user;对 system 抑制 省略 调用方/组件 稳定 不渲染文本:使用回退标签
metadata 渲染内容;渲染为空;跳过标量;省略 消息主体下方的可选内容。 assistant 和 user;对 system 抑制 省略 调用方 稳定 渲染为空:插槽折叠
density compact;balanced;spacious;省略 选择间距并成为后代消息上下文。 每个发送者 继承 组件/列表上下文 稳定 封闭联合;被类型拒绝
root surface ref;DOM/data/ARIA props;className/style/xstyle 扩展消息文章。 每个发送者 省略 公共组件 API 稳定 不适用

行为与布局契约

ID 不变量 依据
FR1 assistant MUST 对齐到行内起始位置,user 对齐到行内结束位置,system 居中;根元素 MUST 在 chat-message 目标上体现发送者。 已发布的实现;消费者文档;聚焦测试
FR2 system MUST 抑制所提供的头像、姓名和元数据,同时继续渲染 children。 已发布的实现;Chat 家族结构;聚焦测试
FR3 非 system 消息 MUST 按该视觉顺序渲染所提供的头像、姓名、children 和元数据。null、布尔值和空字符串辅助值 MUST NOT 创建包装器;内容渲染为空的包装器 MUST 折叠(DEC-1)。 负责人指示;聚焦测试
FR4 密度 MUST 按显式 density → 最近的 ChatMessageList 密度 → balanced 的顺序解析,解析后的值 MUST 反映在根目标上。 已发布的实现;消费者文档;聚焦测试;主题元数据
FR5 后代 MUST 通过 ChatMessageContext 接收解析后的 {sender, density} 值。 已发布的实现;后代组合
FR6 article 元素 MUST 将翻译后的发送者回退文本作为 aria-label 携带;非 system 且不是被跳过的标量的 name MUST 也通过 aria-labelledby 为其提供标签。渲染文本的 name 为 article 命名;渲染为空的 name 则保留回退文本(accessible name computation 1.2,步骤 2B)。 负责人指示;accessible name computation 1.2;聚焦测试
FR7 被接受的 ref、DOM/data/ARIA props、className、style 和 xstyle MUST 到达并组合在承载 chat-message 目标的同一 article 元素上,但 aria-label 和 aria-labelledby 除外,组件拥有这两个属性用于命名(FR6、AR1)。 architecture:public-component-api/INV5–INV6, INV8;聚焦测试

允许的变体

  • AV1 — 消息内容。 children 可以是气泡、富内容、工具输出、媒体或任何其他调用方拥有的 React 节点。
  • AV2 — 身份内容。 头像、姓名和元数据是调用方拥有的节点,原样传递给 React;包装器控制放置位置、system 抑制,以及内容渲染为空的插槽的折叠。
  • AV3 — 密度几何。 解析后的间距遵循当前主题的间距刻度;compact → balanced → spacious 的顺序是固定的。

代表性状态

状态 必需不变量 允许的变体
带有头像、姓名和元数据的 assistant 行内起始布局;可见的姓名标注 article 元素 任何调用方拥有的节点都可以填充这些插槽
被跳过的标量辅助值 不创建任何插槽或命名引用 null、布尔值、空字符串
渲染为空的辅助内容 插槽折叠;此类姓名保留回退标签 空数组或 Fragment、返回 null 的组件
数字辅助值 0 保持可见,并且数字名称标记 article 元素 任何非系统 sender
没有名称的用户 inline-end 布局;翻译后的 sender 后备文本标记 article 元素 头像和元数据可以存在或省略
提供了辅助属性的系统消息 居中布局;头像、名称和元数据保持隐藏 任何子元素继续渲染
独立消息 解析后的密度为 balanced 任何 sender 和内容
位于提供密度的列表中的消息 继承列表密度 任何 sender 和内容
列表中带有显式密度的消息 显式密度优先 任何受支持的密度
窄容器中的长内容 根元素保持在容器内,内容保持可用 后代内容自行选择换行策略
RTL 容器 用户/助手的逻辑对齐方式随文档方向镜像 系统消息保持居中

转换与优先级顺序

  • ORD1 — 密度。 首先解析显式消息属性,然后是最近的消息列表上下文,最后是 balanced;将这一唯一结果用于布局、目标反射和后代上下文。
  • ORD2 — 无障碍名称。 系统 name 或跳过的标量不会创建名称包装器。否则,article 元素引用名称包装器生成的 id;其中渲染的文本为 article 命名,空文本则回退到以 aria-label 携带的翻译后备文本。调用方的 aria-label 或 aria-labelledby 不会覆盖此命名。

性能与资源

  • PR1 — 无外部资源。 ChatMessage 不安装任何监听器、定时器、观察器、请求或 Effect。
  • PR2 — 稳定广播。 后代上下文的值仅在解析后的 sender 或 density 发生变化时改变。

无障碍契约

  • AR1 — article 命名机制。 每个 article 元素将翻译后的 sender 后备文本作为 aria-label 携带。当存在名称包装器时,通过 aria-labelledby 引用;其渲染的文本为 article 命名,当它不渲染任何文本时,无障碍名称回退到 aria-label。
  • AR2 — 不进行检测。 插槽内容永远不会被检测、克隆或执行来决定是否渲染;折叠和命名后备行为遵循渲染后的 DOM。
  • AR3 — 后代所有权。 ChatMessage 是非交互式的,不引入键盘模型。交互式后代继续负责自身的角色、名称、状态、焦点和激活。

设计关系

解剖结构或状态 设计要求 表征权威 层级角色 组件契约
助手 将消息列对齐到逻辑起始位置 当前来源 内容 FR1
用户 将消息列对齐到逻辑结束位置 当前来源 内容 FR1
系统 将内容列居中并隐藏身份插槽 当前来源 辅助 FR1–FR2
名称 none — 未解决:内置名称会在未定向的后代上绘制显式的辅助类型和次要颜色;参见 OQ1。 当前来源 辅助 FR3
密度 在三步轴线上增大根元素和子元素的间距 当前来源 结构 FR4

未记录任何组件级设计决策。

主题可达性

解剖结构部分 处理方式
消息根元素 target — chat-message 目标位于 article 元素上,并反映 sender 和解析后的 density;Chat 系列文档拥有其消费者元数据。
头像 delegatesTo 提供的节点,通常是 component:Avatar 拥有的 avatar 目标。
名称 none — 可达性缺口:内置名称会在未定向的后代上绘制显式的辅助类型和次要颜色;参见 OQ1。
内容 delegatesTo 调用方拥有的子元素及其目标;自定义内容没有组件拥有的目标。
元数据 none — 当前有意的边界:调用方提供完整的渲染节点,而包装器仅贡献放置位置。

系列与系统关系

  • 当前没有 family:chat 记录。Chat.doc.mjs 是面向消费者的 系列文档,并拥有共享目标清单;它并非产品权威来源。
  • component:ChatMessageList 提供可选的密度上下文,并负责列表 间距、日志语义、流式状态和消息排序。
  • component:ChatMessageBubble 在存在时消费发送者和密度上下文, 并负责气泡呈现。
  • 目前没有 ChatMessage 的 compact | balanced | spacious 密度词汇表或排序的直接所有者。FR4–FR5 记录了 已交付的轴和优先级;被路由的全局布局声明并未解决 该组件特有的词汇表。
  • spec:AST-029 拥有本记录的验证映射所遵循的审计证据清单。

验证映射

契约 验证 代表性状态 变更或失败预期 审计章节
FR1–FR3 ChatMessage.test.tsx; ChatMessage.stories.tsx 所有发送者;跳过的标量、渲染为空、数字、内容以及被抑制的插槽状态 移除标量跳过逻辑或 CSS 折叠会导致空插槽或间隙 audit:ChatMessage/§4
FR4–FR5 ChatMessage.test.tsx; ChatMessageBubble.test.tsx; themingTargets.test.ts 独立;继承的密度;显式覆盖 更改优先级或反射会使后代和主题获得不同的密度 audit:ChatMessage/§2
FR6, AR1–AR2 ChatMessage.test.tsx 可见、省略、跳过的标量、渲染为空以及系统名称 移除后备 aria-label 或名称引用会使 article 未命名 audit:ChatMessage/§1
FR7 ChatMessage.test.tsx;公开导出和主题化目标检查 ref;data 属性;class;style 将透传或 ref 移出目标 article 会破坏公开的根契约 audit:ChatMessage/§3
RTL ChatMessage.stories.tsx 所有发送者;窄宽度长内容 物理方向在两种方向下都将用户或助手保持在同一侧 audit:ChatMessage/§9

从源代码读取,目前尚无针对性测试:

  • FR1:按发送者进行起始、结束和居中对齐。
  • FR2:系统消息仍然渲染其子内容。
  • FR3:视觉插槽顺序。
  • FR7:调用方的 aria-label 或 aria-labelledby 不会覆盖命名, 且 xstyle 在 article 上组合。
  • ORD1:根和子内容的间距遵循已解析的密度。
  • FR6:渲染无文本的名称时保留后备名称。
  • PR1–PR2:没有监听器或 Effect,且上下文值仅随 发送者或密度变化。
  • AR3:组件自身没有键盘模型。

决策日志

  • DEC-1 — 插槽空性取决于渲染后的 DOM。 (cixzhang, 2026-10-31) ChatMessage 仅跳过 null、布尔值和空字符串 插槽值。任何其他内容都会原样传递给 React;当其渲染为空时,其包装器 通过 :empty 折叠,并且当引用的名称渲染无文本时,article 的命名 回退到 aria-label。 已拒绝:检查数组、Fragment 或可迭代对象,这些方式无法看到 组件输出,并且会消耗一次性迭代器。

开放问题

  • OQ1 — 内置名称是否应成为一个可单独主题化的解剖部分? (human-api) 已发布的系列清单仅暴露聚合的 chat-message 目标,而名称的显式类型和颜色阻止根覆盖 通过继承到达它。添加或拆分目标会更改公开的主题化 API, 因此本记录陈述了可达性缺口,但未选择补救措施。

内容边界

本文件不重复消费者属性表或示例、当前审计分数、截图矩阵 或共享系统规则。审计 PR 拥有 spec:AST-029/FR5 所需的闭环运行证据。

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