ChatSystemMessage 组件契约¶
契约概览¶
| 领域 | 契约 |
|---|---|
| 公共契约 | ChatSystemMessage 需要 children、variant(default、divider;默认 default),可选的 icon、ref、xstyle、className、style,以及根 DOM props。 |
| 行为 | default 渲染一个居中的行,包含可选的图标内容和 children,并对长文本进行换行。divider 将 children 渲染为带标签的水平 Divider,并忽略 icon。 |
| 终端用户影响 | 阅读者可以将系统通知与发送者消息区分开来,并看到带标签的日期或分区分隔;添加到聊天日志中的通知会由该日志宣告一次。 |
| 构建者影响 | 无。 |
| 兼容性/就绪状态 | 记录已发布行为;无公共变更。无实现缺口;有一个所有者问题保持开放。 |
| 审查检查 | 拒绝在行上设置 live role、丢失分隔符或其名称、丢弃根输入,或在没有所有者的情况下解决 divider-icon 问题。 |
| 治理规则 | spec:AST-086 FR4;component:Divider;architecture:public-component-api;architecture:component-theming-surface;architecture:theme-tokens。 |
此表为审查视图;以下正文具有权威性。
意图¶
ChatSystemMessage 在聊天记录中呈现简短的非发送者内容,例如“对话已开始”或日期分隔。它将系统通知与发送者消息区分开来,并将带标签的分隔符交给 Divider。消费者用法见 ChatSystemMessage.doc.mjs。
兼容性与迁移¶
- 已发布默认值保留:
yes - 兼容性类别:记录已发布行为;无公共变更
- 受控/非受控行为:不适用;该组件不拥有状态
- 迁移决策:无
消费者迁移说明应放在消费者文档和发布说明中。
所有权边界¶
拥有
- 根行、其
chat-system-message目标,以及在居中行与 Divider 组合之间进行选择(FR1、FR2、FR5)。 - 对长默认变体内容进行换行,并防止图标内容缩小(FR1)。
- 根 ref、DOM props 和样式(FR4)。
不拥有 / 非目标 {#does-not-own-non-goals}
- 宣告通知——聊天日志会宣告添加在其内部的内容(
spec:AST-086FR4)。 - 分隔符的线条、标签位置、role、名称和标签分区——由
component:Divider拥有。 - 发送者身份、聊天记录顺序和滚动。
- 调用者内容的含义和图标图形。
公共概念¶
| 概念 | 封闭值或状态 | 含义 | 按变体/方向/状态可用性 | 默认值 | 所有者 | 稳定性 | 无效值行为 |
|---|---|---|---|---|---|---|---|
| 呈现方式 | default、divider |
一个居中的通知行,或一个带标签的水平分隔符。 | 每次渲染。 | default |
component:ChatSystemMessage |
稳定 | TypeScript 拒绝其他值。 |
| 图标 | 省略;一个 React 节点 | 通知之前的可选图形。 | 由 default 渲染;被 divider 忽略(OQ1)。 |
省略 | component:ChatSystemMessage |
稳定 | 不适用。 |
行为与布局契约¶
| ID | 不变量 | 依据 |
|---|---|---|
| FR1 | default 渲染一个居中行,在 children 之前放置 icon(若提供);children 在可用内联空间内换行,图标不缩小,且不绘制分隔线。 |
当前源码和测试 |
| FR2 | divider 将 children 作为根内部水平 component:Divider 的标签渲染,因此分隔符由其标签命名;icon 不渲染(OQ1)。 |
当前源码和测试 |
| FR3 | 在两种变体中,根本身都不携带 live role;聊天日志会宣告添加在其内部的通知(spec:AST-086 FR4)。 |
spec:AST-086;测试 |
| FR4 | 在两种变体中,ref、DOM、data 和 ARIA props(包括调用者的 role、className、style 和 xstyle)都会到达根元素。 |
当前源码和测试 |
| FR5 | 根元素携带 chat-system-message 目标并反映 variant。 |
当前源码和测试 |
允许的变化¶
- AV1 — 内容。 文本和其他 React 内容可变;Divider 负责在
divider变体中空标签和数字标签的渲染方式。 - AV2 — 主题。 语义颜色、间距和排版 tokens 按主题解析。
代表性状态¶
| 状态 | 必需不变量 | 允许的变化 |
|---|---|---|
| 默认 | 内容居中;无分隔线;无 live 角色。 | 内容。 |
| 默认带图标 | 图标位于内容之前。 | 美术资源。 |
| 默认,长内容 | 内容换行且无水平溢出。 | 区域设置。 |
| 分隔线 | 以其标签命名的分隔符;无 live 角色。 | 标签。 |
| 分隔线带图标 | 不渲染图标(OQ1)。 | — |
变换与优先级顺序¶
- ORD1 — 变体。
divider选择分隔线(Divider)组合;否则渲染居中行。
性能与资源¶
- PR1 — 仅渲染。 该组件不添加状态、Effect、观察器、监听器或计时器。
无障碍契约¶
- AR1 — 无 live 角色。 该通知是普通的转录内容;其所在的 live 容器负责对外播报(FR3)。
- AR2 — 分隔符。
divider变体通过 Divider 暴露一个由其标签命名的分隔符(FR2)。 - AR3 — 非交互。 该组件不添加焦点目标、键盘命令或指针操作。
设计关系¶
| 解剖结构或状态 | 设计要求 | 表象权威 | 层级角色 | 组件契约 |
|---|---|---|---|---|
| 系统消息 | 一个居中的、简洁的非发送者行。 | 当前源码与文档 | 辅助性 | FR1, FR5 |
| 图标 | 通知之前的可选美术资源。 | 当前源码与文档 | 辅助性 | FR1 |
| 分隔线 | 用于日期或章节分隔的带标签分隔符。 | component:Divider |
辅助性 | FR2 |
目前尚未记录解剖结构-主题映射;该区块在迁移期间为可选项,因此映射被推迟。
家族与系统关系¶
component:Divider拥有分隔符的结构、角色、名称、绘制与标签分区。spec:AST-086FR4 将 live 容器内新增内容的播报职责分配给该容器。architecture:public-component-api拥有根节点直通与样式组合;architecture:theme-tokens拥有代币词汇表。spec:AST-029拥有本记录的验证映射所遵循的审计证据清单。
验证映射¶
| 契约 | 验证 | 代表性状态 | 变更或失败预期 | 审计章节 |
|---|---|---|---|---|
| FR1 | ChatSystemMessage.test.tsx 的 children 与图标测试 |
默认;默认带图标 | 缺少内容或图标则失败。 | audit:ChatSystemMessage/behavior |
| FR2, AR2 | ChatSystemMessage.test.tsx 的分隔线、分隔符名称、分隔线图标与数字零标签测试;ChatSystemMessage.a11y.chromium.spec.ts 状态矩阵(水平方向) |
分隔线;分隔线带图标 | 缺少分隔符、名称错误或渲染出图标则失败。 | audit:ChatSystemMessage/accessibility |
| FR3, AR1 | ChatSystemMessage.test.tsx 的无 live 角色测试 |
两种变体 | 根节点出现 live 角色则失败。 | audit:ChatSystemMessage/accessibility |
| FR4 | ChatSystemMessage.test.tsx 针对每种变体的“保留完整根节点直通接缝”测试 |
ref、data、ARIA、role、class、style、xstyle | 输入属性被丢弃则失败。 | audit:ChatSystemMessage/public-api |
| FR5 | ChatSystemMessage.test.tsx 针对每种变体的“保留完整根节点直通接缝”测试 |
两种变体 | 缺少映射后的变体属性则失败。 | audit:ChatSystemMessage/theming |
| FR1 | ChatSystemMessage.a11y.chromium.spec.ts 320px 粗指针回流测试 |
320 CSS px 下的长内容 | 出现水平溢出则失败。 | audit:ChatSystemMessage/responsive |
根据源码读取,暂无针对性测试:
- FR1:居中、默认行无分隔线、图标渲染于内容之前、图标不收缩。
- FR5:根节点上的
chat-system-message目标。 - PR1、AR3:组件自身无状态、Effect 或交互。
决策日志¶
未记录组件局部的决策。
开放问题¶
- OQ1 —
icon在variant="divider"下应当做什么?(human-api) 目前该属性会被接受但不渲染。将其与标签一起渲染、在architecture:public-component-apiINV9 下添加破坏性类型限制,或者保留附带文档说明与开发警告的无效操作,都会改变公共契约。
内容边界¶
本文档不重复消费者 prop 表格或示例,也不重复 Divider 的规则。它仅提供指向这些内容所有者的链接。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx