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-117FR2);没有其他公共 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-117FR2)。
性能与资源¶
- 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-layouttarget 及其反映的方向所遵循的规则。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