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