跳转至

FieldStatus 组件契约

意图

FieldStatus 为字段或类字段控件呈现一条验证消息。它负责 attached 和 detached 呈现形式的可见消息处理与公告行为;使用方用法仍在 FieldStatus.doc.mjs 中记录。

兼容性与迁移

  • 发布默认保留:yes
  • 兼容性类别:仅追加文档;运行时、DOM、样式和公共 API 保持不变,唯一例外是在已挂载的 live 容器内的投递遵循 spec:AST-086 FR4
  • 受控/非受控行为:不适用
  • 迁移决策:拒绝直接支持 FieldStatus variant="tooltip"。tooltip 仍是字段家族哨兵值,渲染 FieldStatus 前 MUST 处理它。要收窄当前宽松的类型/运行时路径,需要单独进行兼容性感知的实现变更。

使用方迁移说明属于使用方文档和发布说明。

职责边界

负责

  • attached 和 detached 的验证消息呈现形式。
  • 经由持久公告通道路由可见消息。
  • detached 呈现形式中冗余的可见状态字形。

不负责 / 非目标

  • 调用方是否渲染状态消息,或该消息描述哪个控件——由组合字段组件或产品调用点负责。
  • 带边框控件的状态处理及字段上的 tooltip 呈现——由组合字段组件负责。
  • 常规警报和页面级通知——由相应反馈组件负责。

字段家族的 tooltip 状态呈现形式会抑制 FieldStatus,并从控件的字段上图标显示消息。tooltip 不是 FieldStatus 的呈现形式。公共可扩展变体映射当前允许直接的 tooltip 值;这是一个实现缺口,而非受支持的行为。

公共概念

概念 封闭值或状态 含义 按变体/方向/状态的可用性 默认 所有者 稳定性 无效值行为
状态类型 error、warning、success 选择消息语气和公告渠道。 所有已渲染的呈现形式。 必需 component:FieldStatus 稳定 TypeScript 拒绝不支持的值。
呈现形式 attached、detached 选择消息的呈现形式。 所有直接使用 FieldStatus 的场景。字段家族的 tooltip 哨兵值会在 FieldStatus 渲染前被处理。 attached component:FieldStatus 稳定。 TypeScript 拒绝扩展变体映射中不存在的值;其当前接受 tooltip 是一个实现缺口。

行为与布局契约

草案需求会说明其依据,以免观察到的代码被误认为有意决策。

ID 候选不变式 依据 草案评审状态
FR1 FieldStatus MUST 在挂载时在单个可见消息框中渲染所提供的消息。 文档中的承诺和当前测试。 意图已确定。
FR2 attached 呈现 MUST 在消息前不渲染前导字形;detached 呈现 MUST 在消息文本前渲染其状态字形。 文档中的承诺、当前 DOM 和当前测试。 意图已确定。
FR3 状态类型 MUST 选择不同的 error、warning 或 success 处理方式,且 MUST 反映在消息框目标上。 当前行为和主题测试。 意图已确定。
FR4 detached 字形 MUST 在其自身目标上反映状态类型;该目标 MUST 不出现在 attached 呈现中。 当前行为和目标测试。 意图已确定。
FR5 根节点 MUST 继续转发其 ref、ID、受支持的 DOM 属性和使用方样式逃生舱。 当前行为和测试。 当前兼容性行为;更改前需验证。
FR6 消息和状态类型更新 MUST 更新可见输出,且不替换组件契约。 当前行为和测试。 当前兼容性行为;更改前需验证。
FR7 直接使用 FieldStatus MUST 仅支持 attached 和 detached;字段家族 MUST 在渲染 FieldStatus 前消费其 tooltip 哨兵值。 已批准的组件边界。 意图已确定;当前类型接受行为是一个缺口。

允许的变化

  • AV1 — 主题样式。 主题和消费者覆盖可以通过现有目标和样式逃生通道更改视觉 CSS 属性,而无需改变结构、所有权或呈现行为。
  • AV2 — 消息长度。 消息可以换行;分离字形仍与第一行文本对齐。

代表性状态

状态 必需不变量 允许的变化
附加错误 消息框和文本渲染;不渲染分离字形。 由主题控制的 field-status 视觉属性。
分离警告 依次渲染消息框、前导警告字形和消息文本。 由主题控制的两个当前目标的视觉属性。
分离成功 依次渲染消息框、前导成功字形和消息文本。 消息长度和由主题控制的视觉属性。
空消息 根节点保持挂载并渲染提供的空值。 不创建公告通道。

转换与优先级顺序

  • ORD1 — 呈现样式。 解析默认呈现,通过 themeProps 反映状态和呈现,应用组件样式,然后按既定顺序合并 xstyle、className 和内联 style。
  • ORD2 — 分离内容。 使用与字段控件相同的状态到字形映射,在消息文本之前渲染装饰性状态字形。

性能与资源

  • PR1 — 通道更新工作。 消息更改仅安排持久活动区域更新;FieldStatus 不拥有全局事件监听器、观察器或测量。

无障碍契约

  • AR1 — 编程式公告通道。 错误 MUST 更新持久断言区域;警告和成功 MUST 更新持久礼貌区域,包括在首次挂载以及消息或类型变化时,且不移动焦点。在已挂载的活动容器内,适用 spec:AST-086 FR4。
  • AR6 — 重复提交是表单的时机。 字段的状态在其消息或类型变化时进行公告,而不会对相同值再次公告(spec:AST-086 FR6)。提交是表单的时机(spec:AST-086 FR1),因此当重复提交因未变化的错误而失败时,表单通过 useAnnounce 公告一次,例如错误数量和第一个错误,而 FieldStatus 不会再次公告。
  • AR5 — 辅助技术输出。 关于消息是否、何时或以何种方式被朗读或以盲文呈现的声明,建议在 spec:AST-009 下进行真实辅助技术跟进,而非合并或发布要求;DOM 和无障碍树检查可证明编程式暴露和路由。
  • AR2 — 可见描述。 渲染的消息框 MUST 保持可供辅助技术通过 aria-describedby 关联使用,并且 MUST NOT 成为其自身新挂载的活动区域。
  • AR3 — 非颜色提示。 分离状态 MUST 包含前导状态字形,以便状态不仅通过颜色或位置传达。
  • AR4 — 冗余字形。 分离字形 MUST 对辅助技术保持隐藏,因为可见消息已在文本中传达状态;公告输出仍由 AR5 负责。

设计关系

结构或状态 设计需求 呈现权威 层级角色 组件契约
消息框 承载可见的验证处理。 当前行为和已批准的组件意图。 支持 FR1, FR3
分离图标 仅在分离呈现中添加非颜色状态提示。 当前行为和已批准的组件意图。 支持 FR2, FR4, AR3
消息文本 用文字传达验证结果。 当前行为和已批准的组件意图。 重要 FR1, AR1, AR2, AR5

当前行为在消息文本之前渲染分离图标。预期的公开主题所有权就是下面的精确映射;它不添加目标,也不更改任一呈现。

主题结构

{
  "Message box": {"target": "field-status"},
  "Detached icon": {"target": "field-status-icon"},
  "Message text": {"inherits": "field-status"}
}

系列与系统关系

  • architecture:component-theming-surface 拥有两个目标和继承的消息文本的限定与验证规则。
  • 类字段控件组合 FieldStatus,但继续拥有控件渲染、状态放置决策以及与控件的关联。

验证映射

契约 验证 代表性状态 变更或失败预期 审计章节
FR1, FR2, AR3, AR4 FieldStatus.test.tsx 渲染与分离图标测试套件 附加和分离;所有状态类型 移除或重新排列展示部分将导致 DOM 和可访问性断言失败。 audit:FieldStatus/anatomy
FR3, FR4 FieldStatus.test.tsx 主题目标测试套件 附加/分离;错误/警告/成功 移除某个目标或状态映射会导致 class/data-attribute 断言失败。 audit:FieldStatus/theming
FR5, FR6 FieldStatus.test.tsx 转发与更新测试套件 初始渲染和重新渲染 破坏已发布的根元素或更新行为会导致兼容性断言失败。 audit:FieldStatus/behavior
AR1 StatusMessage.a11y.test.tsx 和 StatusMessage.a11y.chromium.spec.ts 错误、警告和成功;挂载后的消息替换 移除持久通道、更改其角色/紧急程度,或丢弃挂载后的更新,都会导致共享状态消息契约失败。 audit:FieldStatus/accessibility
AR1 FieldStatus.test.tsx 通道路由测试套件 首次非空挂载;同一实例的消息和类型更改 破坏 FieldStatus 的首次使用 hook 调用或严重性重新路由,将导致组件特定的断言失败。 audit:FieldStatus/accessibility
AR5 spec:AST-009 中建议的真实 AT 后续验证 首次挂载;消息替换;类型/紧急程度更改 在获得真实 AT 回执之前,语音和盲文输出仍处于未经验证状态;这不阻止合并或发布。 audit:FieldStatus/accessibility
AR2 FieldStatus.test.tsx 附加/分离的可见消息和空消息 可见描述会变成第二个实时区域,或被辅助技术隐藏。 audit:FieldStatus/accessibility
主题结构映射 scripts/check-knowledge.mjs 消费者结构和当前目标 缺失、多余、重复、带前缀或过时的映射会导致仓库验证失败。 audit:FieldStatus/theming

决策日志

DEC-1 — 呈现方式特定的结构保持显式

参考: component:FieldStatus/DEC-1 决策者: cixzhang, 2026-08-30

分离图标是一个独立的结构部分,因为只有分离呈现方式会渲染它,并且它拥有一个与消息框不同的目标。消息文本继承消息框的目标,而不是创建一个冗余的子目标。

已否决:将图标折叠到通用消息行中,这会隐藏其呈现条件和独立的主题属主。

DEC-2 — tooltip 不是 FieldStatus 的呈现方式

参考: component:FieldStatus/DEC-2 决策者: cixzhang, 2026-08-30

FieldStatus 的直接使用仅支持 attached 和 detached。Field 系列可以将 tooltip 用作内部呈现哨兵,但在渲染 FieldStatus 之前 MUST 消费该值,并改为通过控件的字段内状态处理来呈现消息。

已否决:定义直接 FieldStatus variant="tooltip" 渲染语义。那会将字段组合机制暴露为第三种 FieldStatus 呈现方式,并保留当前并非有意的输出。

未决问题

无。

内容边界

本文件不重复消费者 prop 示例、当前审计结果、实现步骤或系列/系统规则。它会链接到这些内容的所有者。

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