跳转至

Field 组件契约

契约概览

区域 契约
公开契约 Field 用一个标签、可选描述和状态、可选性指示符、显式宽度以及根 BaseProps 包裹调用方拥有的控件;它还消费 FormLayout 的水平标签模式。
行为 单个控件使用原生标签关联;分组使用带标签的 span。状态消息获得稳定 ID 并使用持久化的实时区域。水平标签模式暴露一个受保护的 data-layout 主题轴。
终端用户影响 用户可以识别自定义控件、听到其描述和变化的状态,并在普通和水平表单布局中保持标签/控件/状态之间的关系。
构建者影响 构建者提供控件及其 ID,将描述/状态 ID 关联到该控件,在需要时选择分组语义,并使用对包裹表面安全的状态放置方式。
兼容性/就绪状态 记录已发布行为;无 API、默认值或 DOM 变更。任意子元素的默认 statusVariant="attached" 与 family:input-fields/FR8 冲突;列在“当前状态影响”下,迁移保持开放(OQ1)。
审查检查 拒绝丢失的标签/分组关联、被丢弃的根 props、调用方替换 data-layout、重复/缺失的状态播报、逃逸的局部 z-index、未文档化的公开字面量,或声称所有自定义控件都安全支持 attached 状态的声明。
治理规则 已确立的公开 Field 接口;family:input-fields 共享所有权和 FR8;architecture:public-component-api/INV5–INV8;spec:AST-027/FR1–FR3;HTML label 和 ARIA 命名/描述语义。

此表为审查投影;下文正文具有权威性。

意图

Field 为尚未拥有 Astryx 字段外壳的原生、自定义或第三方控件提供共享的标签、描述、状态、宽度和布局装饰。调用方继续拥有控件的值、交互模型和控件特定的无障碍语义。

兼容性与迁移

  • 已发布默认值保持不变:是;statusVariant 在当前实现中仍默认为 attached。
  • 兼容性类别:记录已发布行为;无公开 prop、默认值、导出或 DOM 变更。
  • 受控/非受控行为:由调用方拥有且保持不变。
  • 迁移决策:无;解决 OQ1 需要单独的兼容性决策。

所有权边界

拥有

  • 根字段盒、显式宽度、局部层叠边界和组合顺序。
  • 围绕调用方控件的标签和描述放置。
  • 单控件与分组标签语义。
  • 状态消息放置和持久化实时区域播报。
  • FormLayout 水平标签投影。

不拥有 / 非目标

  • 被包裹控件的值、焦点模型、键盘行为、禁用行为或事件语义——由调用方或被包裹组件拥有。
  • 将 aria-describedby 应用于被包裹控件——调用方提供控件并关联生成或显式的 ID。
  • FieldLabel、FieldStatus、Tooltip 或调用方拥有的子元素的视觉和语义契约——由这些组件拥有。
  • 输入族成员 API 和控件盒 part props——由 family:input-fields 和每个成员拥有。

公开概念

概念 封闭值或状态 含义 按变体/方向/状态的可用性 默认值 所有者 稳定性 无效值行为
标签模式 单控件;分组 选择原生的 <label htmlFor> 或通过 aria-labelledby 命名的 <span>。 所有布局。 单控件 component:Field 已发布 类型约束
标签可见性 可见;视觉隐藏 在视觉上隐藏标签和描述,同时为辅助技术保留它们。 所有布局。 可见 component:Field 已发布 类型约束
可选性标记 无;可选;必填 显示 FormLayout 可选性默认值的本地化例外。 标签呈现方式。 无 component:Field 已发布 两者同时设置时发出警告;可选状态在视觉上优先,除非 FormLayout 的默认值为可选,此时会隐藏可选状态并显示必填状态。
状态放置 attached;detached;tooltip 将状态框放置在控件后方、下方,或保留可见的 tooltip 提示以指向输入。 渲染状态框需要消息;tooltip 仍会播报消息。 attached(见 OQ1) family:input-fields 已发布;存在一致性差距 受类型约束
宽度 无;数字;CSS 尺寸字符串 设置完整普通字段框的尺寸。 普通框布局;水平标签模式使用 display: contents。 所属布局 component:Field 已发布 受类型约束
字段布局 普通框;来自 FormLayout 的 horizontal-labels 将内容堆叠,或将标签和输入组投射到父级网格中。 从 FormLayoutContext 解析。 普通框 component:Field 已发布 受上下文约束
描述/状态 ID 显式;根据 inputID 生成;无 为调用方拥有的 aria-describedby 连接提供稳定的描述和消息元素名称。 仅当相应文本存在时生成。 存在文本时生成 component:Field 已发布 空文本会省略输出

行为与布局契约

ID 不变式 依据
FR1 单控件标签渲染为 <label htmlFor={inputID}>;组标签渲染为带有 labelID 的非标签元素,供调用方拥有的 aria-labelledby 使用。 已确立的公共接口;HTML 和 ARIA 语义
FR2 视觉隐藏的标签和描述保留在 DOM 中,且不参与布局流。 已确立的公共接口和可访问性行为
FR3 描述和状态 ID 在显式提供时使用显式值;否则仅在文本存在时解析为 ${inputID}-desc 和 ${inputID}-status。 已确立的公共接口
FR4 错误状态消息通过持久化实时区域以断言方式播报,警告/成功消息以礼貌方式播报;tooltip 放置不渲染 FieldStatus 框,但保留播报。 现有测试;组件族职责
FR5 普通布局按标签、控件、可选状态的顺序排列。水平标签模式将标签包装器放在一个描述/控件/状态组之前,并体现 data-layout="horizontal-labels";调用方 props 不能替换该所属主题标记。 已确立的布局接口;architecture:public-component-api/INV5
FR6 width 应用于普通根字段框;它不会为调用方拥有的控件设置样式,且在水平标签模式下没有可作用的目标框。 已确立的公共接口;family:input-fields 共享所属者
FR7 根引用、data/ARIA/DOM 输入、事件、xstyle、类名和内联样式都到达或组合在根上,而不会替换组件所属的语义。 architecture:public-component-api/INV5–INV8
FR8 Field 根元素隔离每个本地附加状态绘制关系,而不为根元素分配页面级 z-index。 spec:AST-027/FR1–FR3, FR11
FR9 Field MUST 仅将附加放置给予不透明、有边框、固定高度且尺寸反映可靠的控件;对于过高、换行、半透明、无边框或其他不合格的控件(自定义控件通常如此),应使用分离式或组件所属的放置。实现差距:statusVariant 对每个子项默认取 attached,因此除非调用方另行选择,否则不合格控件会获得附加放置 (OQ1)。 family:input-fields/FR8

允许的变体

  • AV1 — 调用方拥有的控件。 任何控件标记都可以占据该插槽;Field 不会检查、克隆或更改它。
  • AV2 — 表单排列。 FormLayout 可以选择普通排列或水平标签排列,而无需更改标签、描述、状态或公告的所属关系。
  • AV3 — 状态表面。 符合条件的控件可以使用附加放置;其他控件使用分离式或成员拥有的工具提示呈现。

代表性状态

状态 必需不变量 允许的变体
仅标签 一个关联标签位于调用方拥有的控件之前。 可见或视觉隐藏。
描述 一个描述元素接收解析后的 ID。 调用方可以使用显式 ID 或生成的值。
组 组标签不是字面 <label>,并且可通过 ID 引用。 调用方拥有组角色和 aria-labelledby。
状态 消息接收解析后的 ID,并在其紧急通道上播报一次。 附加/分离式框或工具提示拥有的可见提示。
水平标签 标签和输入组参与父级网格并保留 data-layout。 描述/状态可以不存在。
显式宽度 普通根元素接收请求的大小并保持可收缩。 数字或 CSS 尺寸字符串。

转换与优先级顺序

  • ORD1 — 根 props。 调用方的 DOM/data/event props 首先转发;随后应用 Field 拥有的视觉状态反射;StyleX、调用方类名和调用方内联样式按文档记录的顺序组合。
  • ORD2 — ID。 显式描述/状态 ID 优先;否则,文本存在时从 inputID 派生 ID;文本不存在时不生成带 ID 的元素。
  • ORD3 — 可选项。 FormLayout 的默认可选项会抑制匹配的可见标记;如果两个局部布尔值都为 true,Field 会发出警告,并且可选标记在可见性上获胜,除非 FormLayout 的默认值为 optional,此时会抑制它,以便显示必填标记。

性能与资源

  • PR1 — 无字段级全局资源。 Field 不拥有监听器、观察器、定时器或外部存储。状态播报委托给共享的持久实时区域运行时,labelTooltip 引入共享 Tooltip 的监听器和层。

无障碍契约

  • AR1 — 标签关联。 单一控件获得原生标签关联;分组控件使用由调用方接线的 aria-labelledby,绝不使用会误导的字面 <label>。
  • AR2 — 描述关联。 描述文本与可访问名称保持分离,并暴露一个稳定 ID,供调用方拥有的 aria-describedby 使用。
  • AR3 — 状态播报。 变化中的状态文本通过持久实时区域播报,包括在未渲染消息框时通过 tooltip 放置位置播报。
  • AR4 — 隐藏标签。 视觉上隐藏的标签和描述文本仍可供辅助技术使用。

设计关系

当前仓库中没有设计记录约束组件局部的视觉调优。 标签、描述和状态使用共享的语义化类型、颜色和间距令牌。

主题化结构

{
  "Container": {"target": "field"},
  "Label": {"target": "field-label"},
  "Ordinary description": {
    "none": {
      "reason": "reachability-gap: The ordinary-layout description paints supporting text outside the field-label target and has no current public target of its own."
    }
  },
  "Horizontal-label description": {
    "delegatesTo": {"owner": "component:Text", "target": "text"}
  },
  "Control slot": {
    "none": {
      "reason": "intentional: The wrapped control is caller-owned or another Astryx component and retains its own theming surface."
    }
  },
  "Status message": {"target": "field-status"},
  "Input status icon": {"target": "input-status-icon"},
  "Input clear button": {"target": "input-clear-button"},
  "Input clear icon": {"target": "input-clear-icon"},
  "Optional/Required indicator": {"inherits": "field-label"},
  "Label tooltip trigger": {
    "none": {
      "reason": "unsettled: the trigger is component:InfoTip's button, which has no public theming target yet; its info icon stays on Icon/icon through InfoTip"
    }
  },
  "Label tooltip surface": {
    "delegatesTo": {"owner": "component:Tooltip", "target": "tooltip"}
  }
}

普通描述保持稳定的消费方结构,不包含 Field 拥有的目标。可见的水平标签描述委托给 Text/text;当 isLabelHidden 为 true 时,相同内容委托给 VisuallyHidden,且不暴露任何可绘制目标。标签 tooltip 将其 component:InfoTip 触发按钮(尚无公开目标)与其由层承载的 Tooltip/tooltip 表面分离。

家族与系统关系

  • family:input-fields 拥有共享的状态放置能力,并将 Field 标识为独立标签、描述、状态放置和显式宽度的所有者。
  • architecture:public-component-api 拥有根级 prop、样式、事件和 ref 组合。
  • architecture:component-theming-surface 拥有结构限定与目标处置。
  • architecture:component-test-sufficiency 拥有突变敏感的证据和有界划分。
  • spec:AST-027 拥有控件与其附属状态之间隔离的局部绘制关系。

验证映射

契约 验证 代表性状态 变异或失败预期 审计章节
FR1–FR3, ORD2, AR1, AR2, AR4 Field.test.tsx 的标签元素、分组标签、隐藏标签与描述、描述 ID 和生成 ID 用例 单一控件、分组、可见和隐藏标签、显式与生成的 ID 关联丢失、元素错误、隐藏文本缺失或 ID 错误则失败。 audit:Field/accessibility
FR4, AR3 Field.test.tsx 的播报与 tooltip 放置用例 首次挂载、更新、重复、错误、警告、tooltip、无消息 缺失、重复、过期或紧急程度错误的播报则失败。 audit:Field/accessibility
FR5, FR6, ORD1 Field.test.tsx 的水平标签、宽度和窄行用例 普通与水平布局;字符串和数字宽度;窄行 可替换的布局标记、错误的网格分组或内层控件上的宽度则失败。证据缺口:没有测试断言普通布局下的标签、控件、状态顺序。 audit:Field/layout
FR7 Field.test.tsx 的 ref 与水平标签根级 prop 用例 ref;水平模式下的 class、style、data 和事件 prop ref 丢失或调用方替换的布局标记则失败。证据缺口:没有测试断言普通布局下的根级 xstyle、class、style 和事件 prop。 audit:Field/api
ORD3 Field.test.tsx 中的 optional、required 及两者均设置(both-set)用例;FormLayout.test.tsx 中经由 Field 的默认可选性用例 可选;必填;两者均设置;表单默认值 缺少标记、两者均设置时未发出警告、或标记只是复述表单默认值,均视为失败。 audit:Field/behavior
FR8 Field.test.tsx 中的 attached 层与局部堆叠(local-stacking)用例 attached、无状态、自定义控件 移除隔离或将根节点排布在其父级之外,均视为失败。 audit:Field/code-health
FR9 Field.test.tsx 中针对自定义控件的 attached 层用例 带有 attached 状态的自定义控件 该测试固定了当前的 attached 默认值,因此当 FR9 缺口闭合时,它会随之改变。 audit:Field/behavior
PR1 证据缺口:没有测试断言不存在 per-field 全局资源 — — audit:Field/code-health
spec:AST-094 FR42 ButtonHitArea.interaction.browser.spec.ts 中的清除带(clear-band)与可清除 Selector 的 chevron 用例 文本输入框的清除按钮位于其文本旁;可清除 Selector 的清除按钮位于其 chevron 旁 清除带越过与文本或字段下一部分之间间距的一半,或点击 chevron 即触发清除,均视为失败。 audit:Field/behavior
主题结构(Theming anatomy) scripts/check-knowledge.mjs;themingTargets.test.ts Field 根节点、标签、描述、调用方控件、状态、共享输入可供性(affordances)、指示器、工具提示 无效的排布,或渲染出的 class 不在已记录的 targets 中,均视为失败。 audit:Field/theming
文档投射(Documentation projection) docPropLiterals.test.ts;docPropReferences.test.ts 状态位置(placements)、labelIcon 及其他已记录的 props 已记录的 literal(字面量)或 prop 引用偏离源类型,即视为失败。 audit:Field/docs
RTL 适用性 apps/storybook/rtl-audit/verified-not-applicable.json 中针对 core/Field 的条目 已检入的 Field stories 某个 story 若获得方向性位置或行为,则会使 not-applicable 条目失效。 audit:Field/i18n-rtl

当前状态影响

  • Attached 默认值(FR9)。 Field 对所有子元素默认将 statusVariant 设为 attached,这与 family:input-fields/FR8 相悖;如何迁移该默认值即为 OQ1。

决策日志

无组件级决策。Field 应用 family:input-fields 与 spec:AST-027。

开放问题

  • OQ1 — Field 应如何迁移已发布的 attached 默认值,使任意自定义控件不会获得 family:input-fields/FR8 所述其可能无法安全支持的 placement(位置)?(human-api)

内容边界

本文件不重复消费者 prop 表/示例、当前审计结果、实施步骤或 family/system 规则,而是链接到这些内容的拥有者。

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