FieldStatus 组件契约¶
意图¶
FieldStatus 为字段或类字段控件呈现一条验证消息。它负责 attached 和 detached 呈现形式的可见消息处理与公告行为;使用方用法仍在 FieldStatus.doc.mjs 中记录。
兼容性与迁移¶
- 发布默认保留:
yes - 兼容性类别:仅追加文档;运行时、DOM、样式和公共 API 保持不变,唯一例外是在已挂载的 live 容器内的投递遵循
spec:AST-086FR4 - 受控/非受控行为:不适用
- 迁移决策:拒绝直接支持
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-086FR4。 - AR6 — 重复提交是表单的时机。 字段的状态在其消息或类型变化时进行公告,而不会对相同值再次公告(
spec:AST-086FR6)。提交是表单的时机(spec:AST-086FR1),因此当重复提交因未变化的错误而失败时,表单通过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