跳转至

FormLayout 组件契约

契约概览

领域 契约
公共契约 FormLayout 通过 vertical、horizontal 和 horizontal-labels 方向排列调用方拥有的字段,提供表单级可选性与输入错误行为默认值,导出其上下文和支持类型,并接受根节点 BaseProps。
行为 Vertical 垂直堆叠子项;horizontal 按逻辑行内顺序为每个子项创建一个分数网格轨道;horizontal-labels 将 Field 标签与控件配对,然后在 481px 视口以下折叠。
最终用户影响 用户会获得可预测的字段间距和顺序,辅助技术即使在表单级视觉约定未标记常见情况时,也能收到必填状态信息。
构建者影响 构建者提供字段以及任何语义化 <form>、标题或页脚;嵌套布局会用自身的 direction、可选性和输入错误行为上下文替换其后代的外层上下文。
兼容性/就绪状态 已发布行为记录为当前行为,加上可选的 defaultEntryErrorBehavior prop(FR7),未设置时字段保持其已发布行为。
审查检查 拒绝丢失根 props、物理行内排序、更改折叠边界、可被调用方覆盖的方向反映、丢失嵌套上下文遮蔽、与 ARIA 不一致的可见可选性约定,或优先级高于字段自身设置的输入错误行为默认值。
治理规则 已建立的公共 FormLayout 接口;family:input-fields 外层排列所有权;architecture:public-component-api/INV5–INV9;architecture:component-theming-surface/INV2–INV6。

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

意图

FormLayout 拥有调用方拥有的表单字段之间的外层空间关系。它不创建表单提交、字段状态、标签、控件或操作区域。

兼容性与迁移

  • 保留已发布的默认值:是的;direction 默认值为 vertical;当 defaultOptionality 未设置时,可选性仍由字段自身拥有;当 defaultEntryErrorBehavior 未设置时,字段保持其已发布的 'complete' 行为。
  • 兼容性类别:增量式;defaultEntryErrorBehavior 是新的可选 prop(spec:AST-117 FR2);没有其他公共 prop、默认值或行为变化。
  • 受控/非受控行为:不适用;FormLayout 不拥有任何表单值或提交状态。
  • 迁移决策:无。

所有权边界

拥有

  • 外层字段排列、间距、方向,以及 horizontal labels 的视口折叠。
  • 表单级可选性和输入错误行为上下文,以及嵌套布局遮蔽。
  • 根 DOM 元素、根 prop 组合,以及 form-layout 主题目标。

不拥有 / 非目标

  • 表单语义、提交、验证或操作位置——由产品调用点和原生 <form> 拥有。FormLayout 仅传递输入项显示自身拒绝信息的默认时机(FR7)。
  • 字段标签、控件、状态和内部几何——由 component:Field、每个输入项和 family:input-fields 拥有。
  • 调用方提供的标题和页脚的内容或视觉契约——由其渲染的组件或调用点拥有。

公共概念

概念 封闭值或状态 含义 按变体/方向/状态的可用性 默认值 所有者 稳定性 无效值行为
direction vertical;horizontal;horizontal-labels 选择外层排列,并将该值提供给后代。 所有布局。 vertical component:FormLayout 稳定 类型约束
默认可选性 未设置;optional;required 仅标记例外项,同时控件保留已解析的必填状态。 所有方向;最近的嵌套布局遮蔽外层。 未设置 / 按字段 component:FormLayout 稳定 类型约束
根组合 DOM/data/ARIA/events;ref;class/style/xstyle 扩展根布局容器,而不替换其拥有的反映。 所有方向。 无调用方装饰 component:FormLayout 稳定 共享合并契约
输入错误行为 未设置;complete;blur-or-enter 设置后代输入何时显示其自身的拒绝信息;字段自身的 prop 优先。 所有方向;最近的嵌套布局遮蔽外层。 未设置 / complete spec:AST-117 稳定 类型约束
布局上下文 方向、可选性和输入错误行为 让 Field 和输入控件能适配布局、必填状态和拒绝时机。 同一层作用域内的后代。 vertical / 未设置 component:FormLayout 稳定 最近的提供者生效

行为与布局契约

ID 不变量 依据
FR1 vertical(默认值)在 flex 列中堆叠子元素,间距为 --spacing-4。 已发布的源码、测试和 stories
FR2 horizontal 将每个直接子元素按文档的逻辑行内顺序放入一个 1fr 网格列,间距为 --spacing-4,且没有组件自有的换行规则。 已发布的源码、测试和 stories
FR3 horizontal-labels 是一个两列网格(auto 1fr),行间距为 --spacing-3,列间距为 --spacing-4,项目对齐到起始位置,因此 Field 标签位于其控件的行内起始侧;在视口宽度为 480px 或以下时,它变为一个 flex 列,间距为 --spacing-4。OQ1 记录折叠后的标签和控件是否需要更紧密的配对间距。 已发布的源码、Field 组合和测试
FR4 FormLayout 将其方向、defaultOptionality 和 defaultEntryErrorBehavior 提供给同一层中的后代;嵌套的 FormLayout 会为自身的后代替换这三者,包括未设置的值在内,而在 FormLayout 内部打开的层中的内容则在没有这些值的情况下开始(spec:AST-038 FR7、FR8)。 上下文源码和测试
FR5 defaultOptionality 只抑制可见的、用于重申表单默认值的标记;后代控件仍会暴露解析后的 aria-required,而原生 required 始终与字段显式的 isRequired 绑定。未设置时则保留各字段自身的指示符。例外:CheckboxList、CheckboxInput 和 Switch 将空选择、未勾选的复选框或关闭的开关视为一种答案,因此 defaultOptionality 不会为它们提供必填状态:它们不会从它那里获得 aria-required 或原生 required。CheckboxInput 和 Switch 只能通过自身的 isRequired 成为必填项,而 CheckboxList 及其行不会从表单默认值中获取任何必填状态;上述标记规则对它们同样适用,且不做改变。 测试;family:input-fields 所有权
FR6 根元素是一个 div。ref、DOM、data、ARIA 和事件 props、xstyle、类名以及内联样式都能在根元素上生效或组合,而不会替换 data-direction 或 form-layout 目标。 architecture:public-component-api/INV5–INV8;源代码和测试
FR7 defaultEntryErrorBehavior 设置未自行指定 entryErrorBehavior 的 DateInput、DateTimeInput、TimeInput 和 NumberInput 后代元素的输入错误行为;未设置时保持 'complete',即它们的出厂行为(spec:AST-117 FR2、FR3)。它不会改变其他后代元素,也不会改变调用方的 status。NumberInput 在两种值下的行为相同(component:NumberInput FR14)。 spec:AST-117 DEC-2;上下文源代码和测试

允许的变化

  • AV1 — 调用方内容。 任何调用方拥有的字段、标题、说明性内容或操作区域都可以作为子元素;FormLayout 不会检查或重写它们。
  • AV2 — 嵌套排列。 构建者可以嵌套垂直和水平布局;每个 provider 只拥有其后代作用域。
  • AV3 — 根元素样式。 调用方样式可以更改容器的呈现方式,同时保留公开的方向和子元素契约。

代表性状态

状态 必需不变量 允许的变化
垂直 单一块轴堆叠,带有 token 化的间距。 任何调用方拥有的子元素。
水平 每个子元素按逻辑行内顺序占有一个 1fr 网格轨道。 子元素数量与内容。
水平标签 / 宽 标签/控件对共享一致的两列轨道。 标签和控件内容。
水平标签 / 窄 在 480px 及以下宽度时变为单垂直列,带有 --spacing-4 间距,且没有组件自身的溢出。 调用方拥有的内容可以换行;OQ1 询问每对标签和控件是否应保持更紧凑的间距。
默认可选 只有明确必填的字段显示例外标记。 字段和输入类型。
默认必填 只有明确可选的字段显示例外标记。 字段和输入类型。
嵌套 内部的方向、可选性和输入错误行为会替换外层的值。 任何受支持的内层方向/默认值组合。
默认 blur-or-enter 未自行设置 entryErrorBehavior 的成员只在提交时暴露自身的拒绝信息。 字段和输入类型;字段自身的 entryErrorBehavior。

转换与优先级顺序

  • ORD1 — 上下文。 显式 props 依次对照 vertical 和未设置的默认值进行解析,然后最近的 provider 将解析后的值暴露给后代组件。
  • ORD2 — 根 props。 FormLayout 拥有的 target 与 direction 反射与 StyleX 及调用方样式组合;调用方的 DOM props 到达同一根节点,而不会替换已拥有的反射。
  • ORD3 — 可选性。 布局默认值确立了未标记的大多数情况;字段级的 isRequired 或 isOptional 标记例外情况,并且仅在明确要求时才控制原生验证。CheckboxList、CheckboxInput 和 Switch 属于 FR5 例外:默认值不会为它们设置必填状态,因此只有它们自身的 isRequired 才会使它们成为必填项。
  • ORD4 — 进入错误行为。 字段自身的 entryErrorBehavior 优先于最近布局的 defaultEntryErrorBehavior,后者优先于 'complete'(spec:AST-117 FR2)。

性能与资源

  • PR1 — 稳定的上下文标识。 后代组件按方向、可选性与进入错误行为的每种组合接收一个 memoized 的上下文值;FormLayout 不拥有任何监听器、观察器、定时器或外部资源。

无障碍契约

  • AR1 — 布局保持非语义。 FormLayout 渲染一个 <div>,不暗示 <form>、分组、标签或提交语义;调用方在其组合需要时自行提供这些语义。
  • AR2 — 必填状态保持可感知。 表单级可选性约定可以移除冗余的可见标记,但后代控件会为辅助技术保留解析后的必填状态。这不适用于 FR5 例外(CheckboxList、CheckboxInput、Switch),它们的未标记状态是一个答案,而不是缺失的必填值;标记了 isRequired 的控件仍会暴露其必填状态。
  • AR3 — 逻辑顺序得以保留。 每个方向都保留 DOM 顺序和逻辑内联流;FormLayout 不会创建独立的键盘顺序。

设计关系

组成部分或状态 设计需求 表示权属 层级角色 组件契约
布局容器 调用方字段的外部排列与间距。 当前源码与文档 支撑 FR1–FR3, FR6
表单标题 调用方内容;FormLayout 不渲染或样式化。 调用方所有 突出 —
字段 调用方的 Field 与输入组件。 它们各自的组件 突出 FR4, FR5
页脚 调用方操作区域;FormLayout 不渲染或样式化。 调用方所有 支撑 —

没有共享的设计记录规定 FormLayout 特有的表示;间距使用 token 刻度。

主题化结构

{
  "Layout container": {"target": "form-layout"},
  "Form title": {
    "none": {
      "reason": "intentional: A title is caller-owned content; FormLayout neither renders nor styles a title part."
    }
  },
  "Fields": {
    "none": {
      "reason": "intentional: Caller-owned Field and input components retain their own theming targets."
    }
  },
  "Footer": {
    "none": {
      "reason": "intentional: A footer is caller-owned content; FormLayout neither renders nor styles an action region."
    }
  }
}

根 target 反映封闭的 direction 轴。它拥有外部排列容器,并且不声称拥有由子组件渲染的视觉部分。

家族与系统关系

  • family:input-fields 将 FormLayout 标识为外部排列、间距、方向、表单级可选性以及表单级进入错误行为默认值的所有者。
  • spec:AST-117 拥有进入错误行为;FR7 与 ORD4 承接其 FR2。
  • component:Field 消费水平标签方向与可选性,同时保留标签、控件、描述和状态的所有权。
  • architecture:public-component-api 拥有根 prop、样式、事件、ref 与发布类型组合。
  • architecture:component-theming-surface 规定了 form-layout target 及其反映的方向所遵循的规则。
  • architecture:component-test-sufficiency 拥有有界且对突变敏感的证据选择。

验证映射

契约 验证 代表性状态 突变或失败预期 审计章节
FR1–FR3 FormLayout.test.tsx 方向快照;FormLayout.stories.tsx 播放检查;稳定视觉基线 core-formlayout--vertical 垂直、水平、水平标签(宽、窄) 更改样式类集合会导致快照失败;水平标签控件比布局更窄,或宽标签不在其控件之前,会导致播放检查失败;垂直布局一旦更改,即会作为变更项返回以供审阅。Story 播放守卫还会在 320px 与默认宽度下从右到左运行 AuditMatrix 播放,并断言水平列呈镜像。缺口:缺少从右到左的检查来断言水平标签位于其控件的内联起始侧。 audit:FormLayout/behavior
FR4, ORD1 FormLayout.test.tsx 上下文与嵌套测试;Layer/layerScopedContext.test.tsx 默认、显式、嵌套;固定 Layer 与内联 Dialog 中的内容 默认值或值丢失、内层布局显式值的遮蔽丢失,或 Layer 内部内容仍读取外层 defaultOptionality,均会导致失败。缺口:没有测试覆盖未设置 props(由自身提供默认值)的内层布局,或跨 Layer 边界的 direction。 audit:FormLayout/behavior
FR5, ORD3, AR2 FormLayout.test.tsx 可选性(optionality)与 aria-required 测试 必填、可选、未设置的默认值;显式例外 冗余标记、缺少 aria-required,或来自默认值的原生 required,均会导致失败。FileInput、Slider、Typeahead 和 Tokenizer 测试覆盖了 required 默认值。 audit:FormLayout/accessibility
FR5 FormLayout.test.tsx “必填默认值使未标记的复选框、开关与复选框组不携带必填状态” 在 defaultOptionality="required" 下,未标记的 CheckboxInput、Switch 和 CheckboxList(每个复选框)不携带 aria-required,也不携带 required,而旁边的 TextInput 仍携带 aria-required;标记遵循 FieldLabel FR4 未标记的复选框、开关或复选框组若携带 aria-required,则失败。 audit:FormLayout/accessibility
FR6, ORD2 FormLayout.test.tsx ref、透传与自有元数据测试;themingTargets.test.ts Ref、属性、冲突的 data-direction 非 div 上的 ref、丢失的 id 或 role,或被替换的 data-direction,均会导致失败。缺口:没有测试覆盖事件 props 或样式输入的合并顺序。 audit:FormLayout/api
AR1, AR3 FormLayout.test.tsx div 与 passthrough 测试;FormLayout.stories.tsx play 检查 普通根节点;调用方的 role 非 div 根节点或丢失调用方的 role 会导致失败。在 story play 守卫下,未镜像 RTL 的水平列会导致 AuditMatrix play 失败。覆盖缺口:若 FormLayout 添加了自己的 role,目前没有任何检查会失败。 audit:FormLayout/accessibility
FR7, ORD4 FormLayout.test.tsx 中的 “FormLayout defaultEntryErrorBehavior” 用例 未设置、complete、blur-or-enter;带有自身 entryErrorBehavior 的字段;有值与没有值的嵌套布局;位于层中的字段 忽略默认值的成员、凌驾于字段自身设置之上的默认值,或保留外部默认值的嵌套/分层字段,都会导致失败。 audit:FormLayout/behavior
PR1 源码审查 所有方向 覆盖缺口:没有自动化检查覆盖上下文身份或新增资源。 audit:FormLayout/behavior

决策日志

此处未记录任何内容。spec:AST-117 的 DEC-2 决定了输入错误行为的默认值。

未决问题

  • OQ1 — 在 480px 及以下宽度,每个水平标签对是否应保留较小的字段内标签/控件间距,使其小于相邻字段之间的间距?(human-design)

内容边界

本文件不重复使用者 prop 表格/示例、当前审计结果、实施步骤或组件族/系统规则。它链接到其对应的所有者。

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