跳转至

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-fields FR3 下拥有。
  • 文本附加组件——由 component:InputGroupText(本通道)拥有。
  • 哪些输入项被认可——由每个组件在 family:input-fields FR3 下决定;仅凭成员身份并不能认可一个输入项。
  • 禁用不读取该组的调用方拥有的控件——不提供此功能。

公共概念

概念 封闭值或状态 含义 按变体/方向/状态的可用性 默认值 拥有者 稳定性 无效值行为
尺寸 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-102 FR4。
  • 减弱动态效果下的附加组件按下状态(FR4)。 当用户偏好减弱动态效果时,Button 附加组件在按下时会缩放至 0.98,正如 component:Button FR15 所记录,这违反了 design:reduced-motion DR1。
  • 根元素样式(FR5)。 InputGroup 在其行上接受根级 className、style 和 xstyle,这超出了 family:input-fields FR10 的范围。FR10 第 3 项将 InputGroup 指定为调用方的样式表面,并且组件族覆盖测试 Field/fieldInputFamily.test.tsx 未将 InputGroup 纳入其字段输入,因此该缺口可能通过澄清 FR10 而非修改代码来关闭。

决策日志

组件本地无决策。InputGroup 应用 family:input-fields。

开放问题

无。

内容边界

本文件不重复消费者属性表/示例、当前审计结果、实现步骤或组件族/系统规则。它链接到其所有者。

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