InputGroup 组件契约¶
契约概览¶
| 区域 | 契约 |
|---|---|
| 公共契约 | 无更改。InputGroup 接受 label、isLabelHidden、description、isOptional、isRequired、isDisabled、size、status、labelTooltip 以及 input 子元素和附加组件子元素。 |
| 行为 | 一个由 Field 标记的 role="group" 行,采用共享元素高度,将认可的输入项、InputGroupText 附加组件和 Button 附加组件连接成一个整体形状,并为每个分组的输入提供该组的名称和描述。 |
| 最终用户影响 | 人们将前缀、输入和后缀视为一个字段,屏幕阅读器用户会听到组标签以及每个输入自身的标签。禁用的组会同时禁用其输入项和 Button 附加组件。 |
| 构建者影响 | 无。 |
| 兼容性/就绪性 | 记录已发布的行为;没有 API 或 DOM 变更,也没有更改的 prop 值。该行保持固定高度,Button 附加组件在减少动态效果下缩放,并且该行在 FR10 的范围内接受根样式;所有这些都列在“当前状态影响”之下。 |
| 审查检查 | 拒绝失去组标签或描述的组输入、内角圆化、兼容子项仍可操作的禁用组,或将内部输入按钮重塑为附加组件的做法。 |
| 治理规则 | family:input-fields FR3, AV3; architecture:component-size-cascade INV3–INV8; spec:AST-085 FR7; spec:AST-038 FR7, FR8; spec:AST-102 FR4; design:reduced-motion DR1. |
此表是审查投影;以下正文具有权威性。
意图¶
InputGroup 将输入项与前后缀附加组件连接成一个整体行,正如 family:input-fields 所规定:它负责行高度、连接后的外部形状、边缘对齐,以及组的标签和支持文本。消费者用法见 InputGroup.doc.mjs。
兼容性与迁移¶
- 已发布的默认值保持不变:
yes;size="md"、标签可见、未禁用 - 兼容性类别:记录已发布的行为;无公共 prop、默认值、导出或 DOM 变更
- 受控/非受控行为:不适用
- 迁移决策:无
消费者迁移说明属于消费者文档和发布说明。
所有权边界¶
拥有
- 组 Field(标签、描述、可选或必填标记、标签提示、脱离的状态消息)以及
role="group"行。 - 行高度,以及它向直到下一个层级边界为止的后代提供的大小。
- 组上下文,告知被认可的子项它们是分组的,以及要组合哪些标签和描述 id。
- 直接 Button 附加组件的连接几何形状。
input-group目标。
不拥有 / 非目标
- 每个分组的输入自身的适配(隐藏的内部标签、不嵌套 Field、分组角、状态图标处理)——由该输入在
family:input-fieldsFR3 下拥有。 - 文本附加组件——由
component:InputGroupText(本通道)拥有。 - 哪些输入项被认可——由每个组件在
family:input-fieldsFR3 下决定;仅凭成员身份并不能认可一个输入项。 - 禁用不读取该组的调用方拥有的控件——不提供此功能。
公共概念¶
| 概念 | 封闭值或状态 | 含义 | 按变体/方向/状态的可用性 | 默认值 | 拥有者 | 稳定性 | 无效值行为 |
|---|---|---|---|---|---|---|---|
| 尺寸 | sm、md、lg |
行高度和子项的默认大小。 | 始终。 | 继承的大小,否则为 md |
family:input-fields |
稳定 | TypeScript 拒绝其他值。 |
| 状态 | error、warning、success、可选消息 |
组验证状态。 | 始终;消息是脱离的。 | 无 | component:InputGroup |
稳定 | TypeScript 拒绝其他类型。 |
| 禁用 | off、on | 禁用该组及其兼容的子项。 | 始终。 | off | component:InputGroup |
稳定 | 不适用。 |
行为与布局契约¶
| ID | 不变量 | 依据 |
|---|---|---|
| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| FR1 | InputGroup 在 group-label 模式下渲染一个 Field,包含 label(除非 isLabelHidden 否则可见)、description、可选或必填标记、labelTooltip,以及作为独立消息的 status。在内部,该行是一个带有 role="group" 的元素,aria-labelledby 设置为标签的 id,aria-describedby 设置为存在的描述和状态消息 id。 |
family:input-fields FR3;当前测试 |
| FR2 | 分组的输入通过 context 接收标签 id 和描述 id。每个被接受的输入由分组标签加上其自身标签来命名,并由分组的描述和状态加上其自身的信息来描述。 | family:input-fields FR3;当前测试 |
| FR3 | 该行是 inline-flex、拉伸且透明的;其高度是对于其尺寸的共享元素高度,作为在 spec:AST-102 FR4 下随设定文本大小增长的最小值。实现差距:高度固定在该尺寸。它向直到下一层边界的后代提供其解析后的尺寸(spec:AST-038 FR7、FR8):显式 size,然后是最近的外部 provider,然后是 md。 |
family:input-fields FR3;architecture:component-size-cascade;当前源码 |
| FR4 | 直接的 Button 附加物加入该形状:朝向相邻元素没有内角圆角,占据整行高度,并且其键盘焦点环高于相邻成员。更深层位于分组输入内部的按钮(clear、calendar、disclosure),以及包裹在 Tooltip 或 HoverCard 中的 Button 附加物(不是直接子元素),保持其自身形状。紧随其后的 popover、template 或 dialog 元素不视为相邻元素。附加物是 ButtonGroup 外部的 component:Button,因此它们的按下缩放 MUST NOT 在 reduced motion 下应用(design:reduced-motion DR1)。实现差距:它仍然在 reduced motion 下应用。 |
当前源码;design:reduced-motion DR1 |
| FR5 | Field 盒子内部的 role="group" 行带有 astryx-input-group,并反映 data-size 和 data-status。ref、data-testid 和其他 DOM props 会到达该行。InputGroup 组合了 Field,因此 family:input-fields FR10 禁止根元素上的 xstyle、className 和 style。实现差距:它们被接受并到达该行。 |
architecture:component-theming-surface;family:input-fields FR10;当前测试 |
| FR6 | 当组自身的 isDisabled 或其外层 InputGroup 的 isDisabled 为 true 时,该组被禁用。被禁用的组会在行上设置 aria-disabled="true",将其调暗至半透明度并采用默认光标,将禁用状态传递给组 Field,并禁用每个兼容子元素(TextInput、NumberInput、Selector、MultiSelector、DateInput、TimeInput、Typeahead、Tokenizer 作为 family:input-fields FR3 下的受接纳成员,以及 Button 附加组件)和嵌套组,直至下一个层边界;每个子元素随后遵循其自身的禁用合约。当组被启用时,自行禁用的子元素或嵌套组保持禁用。不读取该组的调用方所拥有的控件不受影响。 |
spec:AST-085 FR7; spec:AST-038 FR7, FR8; 当前测试 |
允许的变体¶
- AV1 — 成员。 任何受接纳的输入、InputGroupText、Button 以及由 Button 触发的控件都可以按任意顺序出现。
- AV2 — 状态绘制。 主题可以根据
data-status绘制组;核心不为其绘制组边框。
代表性状态¶
| 状态 | 必需的不变量 | 允许的变体 |
|---|---|---|
| 前缀文本 + TextInput | 单行;仅外角;输入由组及其自身标签命名。 | 尺寸。 |
| 输入 + Button 后缀 | Button 全高,朝向输入的一侧为方形。 | 变体。 |
| 带描述和状态 | 组和输入均由两者描述;消息在下方分离显示。 | — |
| 隐藏标签 | 标签在视觉上隐藏;仍命名该组。 | — |
转换与优先级顺序¶
- ORD1 — 尺寸。 显式
size,然后是外部提供者,再然后是md;组内输入自身的显式size仍对该输入生效。 - ORD2 — 描述。 组描述,然后是组状态消息。
性能与资源¶
- PR1 — 无测量。 几何形状来自 CSS 选择器;InputGroup 不添加任何观察器或监听器。
无障碍合约¶
- AR1 — 组名称。
role="group"由可见或隐藏的标签(FR1)标注。 - AR2 — 输入名称。 每个受接纳的输入将组标签与其自身标签组合在一起,因此其用途保持明确(FR2)。
- AR3 — 焦点。 获得焦点的成员被抬高到其相邻元素之上,使其焦点呈现不被遮挡。
设计关系¶
| 解剖结构或状态 | 设计要求 | 表示权威 | 层级角色 | 组件合约 |
|---|---|---|---|---|
| 标签 | 组标签位于行上方,或隐藏。 | 当前来源 | 突出 | FR1 |
| 前缀附加组件 | 输入之前的文本或 Button,与其连接。 | 当前来源 | 辅助 | FR4 |
| 输入 | 受接纳的输入,填充剩余宽度。 | 当前来源 | 突出 | FR2 |
| 后缀附加组件 | 输入之后的文本或 Button,与其连接。 | 当前来源 | 辅助 | FR4 |
design:reduced-motion 控制 Button 附加组件的按下缩放(FR4);没有其他设计记录控制 InputGroup。行上带有 input-group;消费方解剖结构未命名任何行部分,因此本记录不携带解剖主题映射。
家族与系统关系¶
family:input-fields为 InputGroup 分配行高、连接表面、边缘对齐和组焦点;接纳权仍归每个输入所有。component:InputGroupText提供文本附加组件。component:Button从组上下文应用 FR4 的附加组件几何形状。architecture:component-size-cascade负责尺寸继承(FR3)。
验证映射¶
| 合约 | 验证 | 代表性状态 | 变异或失败预期 | 审计章节 |
|---|---|---|---|---|
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- |
| FR1, AR1 | InputGroup.test.tsx 中 label、description、status、hidden-label、marker 和 label-tooltip 用例;InputGroupAudit.a11y.chromium.spec.ts 中 label、hidden-label、description 和 status 用例 |
可见和隐藏标签;可选与必选标记;标签工具提示;描述和状态 | 缺少组名或描述、缺少标记或标签工具提示、隐藏标签被显示、状态消息未包含在描述中或未显示在行下方,均视为失败。 | audit:InputGroup/accessibility |
| FR2, AR2 | InputGroup.test.tsx 中分组输入命名用例和分组 DateInput 语义用例 |
TextInput、NumberInput、DateInput、Typeahead、Tokenizer、Selector、MultiSelector | 分组输入若失去组标签或自身标签,则失败。 | audit:InputGroup/accessibility |
| FR4 | InputGroupAudit.a11y.chromium.spec.ts 中 joined-corner(连接角)和 member-height(成员高度)检查 |
Button 附加组件组合;前缀和后缀;从右到左 | 成员朝相邻成员一侧圆角化、外角应为圆角却是直角、或成员高度小于行高,均失败。证据缺口:没有测试覆盖换行的附加组件或减少动画的按下状态;component:Button 验证自身侧边。 |
audit:InputGroup/layout |
| FR5 | InputGroup.test.tsx 中 row-reflection 和 data-testid 用例 |
Root;size 和 status |
缺少 astryx-input-group 目标、data-size 或 data-status、ref 未到达行、或测试 id 丢失,均失败。证据缺口:没有测试断言 className、style 或 xstyle。 |
audit:InputGroup/theming |
| FR6 | InputGroup.test.tsx 中 disabled 传播用例 |
每个兼容输入和 Button 附加组件;嵌套组;重新启用组并带有显式禁用的子元素 | 在禁用组中仍可操作的子元素、选择退出的嵌套组、或重新启用后仍保持显式禁用的子元素,均失败。 | audit:InputGroup/behavior |
| FR3, ORD1 | InputGroup.test.tsx 中 size 优先级用例;InputGroupAudit.a11y.chromium.spec.ts 中行高度检查 |
显式 size、外层 provider、未提供 size;sm、md、lg 行 |
忽略 prop 或 provider 的尺寸、输入未采用组的尺寸、或行未从 sm 增长到 lg,均失败。证据缺口:没有测试断言在设置文本尺寸后的增长(FR3 的缺口)。 |
audit:InputGroup/layout |
| FR6 (paint), ORD2, AR3 | InputGroupAudit.a11y.chromium.spec.ts 中 disabled、description 和 focus 用例;InputGroup.test.tsx 中 description 顺序用例 |
禁用组;description 后跟 status;键盘焦点分别位于两个相邻成员上 | 禁用行未以半透明度显示且未使用箭头光标、状态消息出现在描述之前、或聚焦成员未位于所有未聚焦成员之上,均失败。 | audit:InputGroup/behavior |
| PR1 | 证据缺口:没有测试断言不存在观察者 | — | — | audit:InputGroup/behavior |
当前状态影响¶
- 固定高度(FR3)。 该行保持固定的共享元素高度,而不是随设定文本大小增长,这违反了
spec:AST-102FR4。 - 减弱动态效果下的附加组件按下状态(FR4)。 当用户偏好减弱动态效果时,Button 附加组件在按下时会缩放至 0.98,正如
component:ButtonFR15 所记录,这违反了design:reduced-motionDR1。 - 根元素样式(FR5)。 InputGroup 在其行上接受根级
className、style和xstyle,这超出了family:input-fieldsFR10 的范围。FR10 第 3 项将 InputGroup 指定为调用方的样式表面,并且组件族覆盖测试Field/fieldInputFamily.test.tsx未将 InputGroup 纳入其字段输入,因此该缺口可能通过澄清 FR10 而非修改代码来关闭。
决策日志¶
组件本地无决策。InputGroup 应用 family:input-fields。
开放问题¶
无。
内容边界¶
本文件不重复消费者属性表/示例、当前审计结果、实现步骤或组件族/系统规则。它链接到其所有者。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx