跳转至

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-086 FR4)。
  • 分隔符的线条、标签位置、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-086 FR4 将 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-api INV9 下添加破坏性类型限制,或者保留附带文档说明与开发警告的无效操作,都会改变公共契约。

内容边界

本文档不重复消费者 prop 表格或示例,也不重复 Divider 的规则。它仅提供指向这些内容所有者的链接。

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