输入字段家族契约¶
意图¶
一个人应当遇到一个连贯的输入系统:状态显示、行为、外观和尺寸在成员之间使用一致的处理方式和 API 契约。每个组件仍然拥有其编辑值所特有的交互模型。
本记录将规范性家族要求与已交付的事实区分开。frontmatter 中的 verified_by 列表列出的是代表性证据锚点,而非每个成员套件。成员列表和采用表对当前家族是穷尽的;对任何成员的更改仍需要其聚焦证据。
成员规则¶
当一个组件的主要公开目的是通过带有内容通道的带标签字段表面来收集或编辑表单值时,它属于该家族。成员使用 Field 语义或拥有等效的字段外壳,并且可以参与 FormLayout。
- 成员: TextInput、TextArea、NumberInput、DateInput、DateRangeInput、DateTimeInput、TimeInput、FileInput、Selector、MultiSelector、ComplexSelector、Typeahead 和 Tokenizer。
- 协作者: Field 和 FieldStatus 提供共享的字段装饰;FormLayout 排列字段;InputGroup 对明确采用其能力契约的成员进行分组;InputClearButton、Spinner、Tooltip 和 BaseTypeahead 提供共享的提示或交互行为。这些协作者不是成员。
- 排除项: CheckboxInput、RadioList、Switch 和 Slider 使用带标签的控件模型,不具备这种内容/末端通道几何。PowerSearch 和 ChatComposer 是更高级的组合,它们消费成员行为而非定义另一个字段原语。BaseTypeahead 是无字段表面的组合框引擎。RichTextEditor 在家族采纳被记录之前保持在该家族之外。
FR10 和 DEC-7 也约束 CheckboxList、RadioList 和 Slider。它们不受该家族几何规则的约束,但它们组合 Field,并且每个组合 Field 的组件都以相同的方式针对基础 props 和样式。
成员资格遵循公开责任,而非是否使用 inputWrapperStyles 或其他实现辅助工具。
共享所有者¶
- 该家族拥有输入状态显示、行为、外观和尺寸的一致跨组件处理和 API 契约。尺寸和末端控件几何是该更广泛目的中的不变式,而非目的本身。
Field拥有独立的标签、描述、状态放置和显式width接缝,并且当它渲染一个盒子时,在 FR10 下是成员的container*样式目标。当受支持的 InputGroup 拥有组标签和辅助文本时,成员会省略其嵌套的 Field。FormLayout拥有外部排列、间距、方向、表单级可选性,以及表单级输入错误行为默认值(FR14)。它不会重新定义成员的内部控件几何。InputGroup拥有行高(当前为固定值;在spec:AST-102FR4 下会随设定的文本大小增长,而固定高度是一个缺口)、连接的外部表面、边缘对齐,以及为获准的子组件提供的组级焦点呈现。获准遵循 FR3 中的能力契约,而不是永久的组件允许列表;仅凭输入家族成员资格并不表示支持。- 每个获准成员都拥有满足 FR3 的分组适配。未分组的外观和行为仍由组件拥有,不因获准而改变。末端控件可以是普通的 flex 项目或组件本地通道;该家族不要求统一的共享包装、测量钩子、目标、自定义属性或新的公开 prop。
- 共享原语保留它们自己的视觉和无障碍所有权。特别是,InputClearButton、Spinner、Tooltip、FieldStatus 和 Icon 在组合到字段中时不会成为特定于成员的 API。
- 内部钩子
useEntryErrorReport(packages/core/src/Field/useEntryErrorReport.ts)拥有 DateInput、DateTimeInput、NumberInput 和 TimeInput 在 FR15 中的共享部分:当显示的拒绝接管调用方的status时;在没有任何显示状态会通告该消息时,由 alert 进行通告;以及onEntryErrorChange报告(spec:AST-118FR5、FR7、FR8)。每个成员传递其拒绝、其消息,以及在没有回调时,调用方error状态是否优先;何时拒绝输入以及消息内容由成员决定。 - 内部钩子
useValueReplacesEntry(packages/core/src/Field/useValueReplacesEntry.ts)为同样的成员决定新的value何时替换保留的输入:在保留被拒绝文本的 Enter 或 blur 同一更新中到达的value不会替换(spec:AST-118FR4、FR6、DEC-14)。每个成员传递其value和一个在每次此类提交时变化的信号。 - 内部钩子
useEntryErrorBehavior(packages/core/src/Field/useEntryErrorBehavior.ts)为 DateInput、DateTimeInput 和 TimeInput 解析 FR14:优先使用字段自身的entryErrorBehavior,否则使用最近的 FormLayout 的defaultEntryErrorBehavior,否则使用'complete'(spec:AST-117FR2)。每个成员决定解析后的值在提交前保留其哪些拒绝。NumberInput 在两种取值下都会在提交时显示所有拒绝,因此它不解析任何行为。 - FieldStatus 拥有其直接的
attached和detached消息框呈现。Field 拥有与输入的组合:它在渲染 FieldStatus 之前消费tooltip,并应用成员支持的放置契约。
规范概念¶
| 概念 | 值或状态 | 默认语义 | 稳定性 |
|---|---|---|---|
| 字段外壳 | 独立 Field 或受支持的 InputGroup 路径 | 一个标签/状态所有者环绕控件 | 已发布的模式 |
| 字段尺寸 | 支持的 sm、md、lg |
相同尺寸的单行控件对齐,且不会因某一状态而改变行 | 已批准的家族规则 |
| 内联尺寸 | 固有、显式 Field.width,或包含布局 |
成员在值和忙碌状态变化期间保持其可用的内联尺寸 | 已批准的规则;Selector 例外见下文 |
| 尾部控件 | 无、清除、忙碌、状态、披露或组件内容 | 每个渲染的控件都有不重叠的空间;不存在的控件不留下无法解释的预留 | 已批准的家族规则 |
| 分组行 | 独立或获准入组的 InputGroup 子项 | InputGroup 拥有行高(在 spec:AST-102 FR4 下随设定的文本大小增长)、连接边缘和组焦点;子项拥有其分组适配 |
已批准的能力契约;已发布的采用见下文 |
| 禁用原因 | 无或组件支持的 disabledMessage |
在变更保持被阻止时,原因仍然可通过键盘和辅助技术触达 | 在暴露处已批准的家族规则 |
| 输入忙碌 | 显式 isLoading 或在暴露处待处理的 changeAction |
字段值正在解析或保存中 | 由 DEC-2 和 AST-001 批准 |
| 聚焦缩放下限 | iOS 或非 iOS 文本输入 | iOS 文本输入控件将渲染文本下限设为 16 CSS px 以防止聚焦缩放;其他平台保留主题尺寸 | 已批准的家族规则 |
| 数据源忙碌 | 组件拥有的异步搜索或选项加载 | 支撑性数据工作与输入的 isLoading 相互独立 |
由组件/系统规范拥有 |
| 过渡动作 | 无或组件支持的 changeAction |
先回调,再乐观值,在过渡中执行 Action,一次忙碌呈现 | 在暴露处已批准的家族规则 |
| 状态放置 | 输入家族层的 attached、detached 或 tooltip |
在成员支持安全重叠处,attached 为默认;detached 和 tooltip 仍对所有输入可用 | 已批准的家族规则 |
| 属性目标 | 基础 props、container*、control* |
基础 props 到达主要语义控件;container* 到达 Field;control* 到达控件框;无根样式输入 |
由 DEC-7 批准 |
| 输入错误行为 | 拒绝输入的成员上的 complete 或 blur-or-enter |
成员在发布时揭示其自身的拒绝,或将其所有信号保留到提交时;字段自身的 prop 优先于表单的 | 由 spec:AST-117 批准 |
跨组件不变量¶
- FR1 — 内联尺寸在普通字段状态下保持稳定。在相同的包含布局中,成员不得仅因占位内容变为值,或因出现忙碌、状态或清除控件而改变其外部可用内联尺寸。显式
width、父布局和响应式约束仍然适用。独立 Selector 是 DEC-1 例外,可以跟随其显示的内容。 - FR2 — 渲染的尾部控件拥有不重叠的空间。文本、令牌、光标和已选内容不得在清除动作、Spinner、状态控件、披露或组件拥有的尾部内容下方绘制或接收指针输入。不存在的通道不得留下陈旧或无法解释的空间。这是一个可观察的要求,而非对测量或共享通道原语的强制。
- FR3 — InputGroup 准入需要完整的分组适配。当所属组件显式采用分组模式并证明以下所有内容时,任何输入成员都可以参与:它从组中解析出兼容的控件高度和尺寸;移除或抑制竞争性的外部 Field、边框、圆角和表面几何;连贯地委托连接的外部边框、圆角和组级焦点呈现;通过组件拥有的截断、折叠、裁剪或溢出将内容保持在单行组几何内;并保留输入的可访问名称和描述、值语义、键盘行为、焦点行为以及编辑或选择模型。准入遵循这些能力而非永久允许列表。仅凭家族成员身份或上下文消费是不够的。
- FR4 — 在支持处,禁用原因保持可触达。当成员暴露
disabledMessage时,非活动字段保持可聚焦(spec:AST-085),并在编辑、选择和激活保持被阻止时暴露原因。没有该公共概念的组件不需要添加它。 - FR5 — 输入加载描述的是值,而非支撑性数据。在成员暴露
isLoading处,它表示字段值正在解析或保存中。它不得使独立提供的选项不可用,也不得更改数据源 prop 的契约。初始选项源待定是 AST-001 要求的单独显式状态。 - FR6 — 过渡动作保留即时反馈。在成员暴露
changeAction处,每个文档化的值变更路径都先运行onChange,乐观地呈现提议的受控值,在 React 过渡中运行changeAction,并参与相同的忙碌呈现,直到受控值接受或替换它。 - FR7 — 组件拥有的数据源工作保持家族几何和可访问性。Typeahead 和 Tokenizer 通过 BaseTypeahead 拥有异步搜索状态,而非通过家族的
isLoading含义。它们可见的数据源忙碌反馈仍然必须被命名,在 combobox 上暴露忙碌语义——或者,在没有 combobox 的呈现中,例如 Tokenizer 的面板(component:TokenizerDEC-3),在搜索更新的结果列表上暴露——并在分组处满足 FR1、FR2 和 FR3。 - FR8 — 状态放置遵循成员能力。每个输入都必须提供
detached和tooltip。成员仅在其直接控件是不透明、有边框、固定高度(由解析尺寸设定的高度,在spec:AST-102FR4 下随设定的文本大小增长)且其所属根可靠地反映用于重叠的解析尺寸时,才支持attached。在支持处,attached是默认值。包裹的、自定义的、较高的或半透明的表面通常使用detached或组件拥有的放置。直接 FieldStatus 继续仅支持attached和detached;Field 在渲染tooltip之前消费它。 - FR9 — 聚焦缩放下限是 iOS 特有的。使用家族聚焦缩放防护的文本输入控件,必须在受支持的 iOS 触摸路径上将其可编辑文本解析为至少 16 CSS px。Android、桌面触摸和其他非 iOS 粗指针环境必须保持当前主题的字号比例,而不是继承 iOS 下限。平台检测机制仍是实现细节,但它必须保留那些可观察的结果。
- FR10 — 基础 props 到达控件;样式只到达命名部分。这是输入家族对基础样式的例外:当
architecture:public-component-api和spec:AST-071赋予组件根级xstyle、className和style时,组合 Field 的组件则没有这些。在每个组合 Field 的组件中: ref、id、data-*(包括data-testid)、aria-*、hidden、inert、dir和 DOM 事件处理器必须到达主要语义控件:承载字段可访问名称和值的原生 input、textarea 或 combobox/trigger 元素。对于分组输入(RadioList、CheckboxList),主要语义控件是组元素(role="radiogroup"或role="group");每个选项的 props 保留在选项 API 上。- 组件的 props 类型不得接受根级
xstyle、className或style;传入这些是类型错误。开发构建在未类型化的调用者于运行时传入时会发出警告,且该值不会被应用。 containerXstyle、containerClassName和containerStyle必须在渲染 Field 框时到达该框。在没有框渲染处(InputGroup 内部,以及在水平标签 FormLayout 中——Field 将其子项直接布局在表单列中),它们没有效果,且开发构建会发出警告;在 InputGroup 内部,调用者为组设置样式。controlXstyle、controlClassName和controlStyle必须到达视觉控件框:绘制字段边框和背景并包含其图标和尾部控件的元素。它们永远不针对原生 input。每组是一个spec:AST-071部件集。- 样式永远不会改道:没有任何布局将
container*移动到控件框,或将control*移动到 Field。
组件自有的值回调(onChange(value))从基础 props 中排除类型,并保持其值签名。重定向基础 prop 会改变消费者 DOM 处理程序所到达的元素,而不是其顺序或取消行为:组件保持其发布的顺序和取消行为,并在其文档和 JSDoc 中说明任何与组件优先组合不同的顺序。组件首次转发的处理程序通过共享的组合辅助函数按组件优先进行组合。任何组件和任何布局都不得改变 prop 的目标。
- FR11 — 清除控件的工具提示命名的是操作,而不是字段。 每个成员的清除控件 MUST 在悬停和键盘聚焦时显示本地化的通用工具提示“清除”,无论字段标签或清除范围是什么。其可访问名称保持上下文相关且由成员所有,例如“清除搜索”或“清除所有国家”,并包含可见单词。
-
FR12 — 搜索输入要求使用搜索键且不进行自动更正。 Typeahead、Tokenizer 以及 Selector 和 MultiSelector 的搜索行的搜索输入 MUST 携带
enterkeyhint="search"和autocorrect="off",以便触摸键盘显示其搜索键并按输入原样保留名称和标识符。它们只是键盘提示:Enter 按每个成员自身契约的规定执行,无论按键显示什么,桌面浏览器都会忽略这两者。它们是成员自有的默认值,在这些成员上没有调用方 prop;component:TextInputFR16 仅允许 TextInput 和 TextArea 使用键盘 props,调用方可在其中为搜索字段设置enterKeyHint="search"。 -
FR13 — 唤起键盘的成员保持在其上方。 当屏幕键盘打开时,成员的聚焦文本输入字段在以下情况下保持在其上方可见:该成员渲染在页面的滚动内容中、在诸如 sheet 之类的 Core 宿主中,或在应用固定栏中且该固定栏停靠在视口底边并无自身的
translate;处于这种栏中的成员会随键盘一起移动,如spec:AST-099FR9 所定义。位于任何其他固定容器中的成员——漂浮在底边上方、设置自身translate或占满整个视口的容器——不会被移动;由应用定位它。这涵盖 TextInput、TextArea、NumberInput、DateInput、DateTimeInput 和 TimeInput 的键入字段、Typeahead 和 Tokenizer 的输入,以及 Selector 和 MultiSelector 的搜索行。这是内部行为,没有 prop 或其他公共 API,如spec:AST-099FR9 所要求;该记录拥有可观察规则和所涵盖字段的完整列表,包括 PowerSearch、CommandPalette 和 ChatComposer 的字段。字段不唤起键盘的成员,例如 DateRangeInput、FileInput、ComplexSelector 或没有输入模式的触摸选择器字段,不在其范围内。 -
FR14 — 拒绝输入的成员共享同一种输入错误行为。 DateInput、DateTimeInput、TimeInput 和 NumberInput 接受
entryErrorBehavior:默认值'complete'保持各成员自带的时间安排,而'blur-or-enter'会保留所有拒绝信号,直到 Enter 或 blur。 FormLayout 的defaultEntryErrorBehavior为表单设置该行为,字段自身的 prop 优先。spec:AST-117拥有该规则。自身不拒绝任何内容的成员(如 TextInput、Selector 和 DateRangeInput)不接受输入错误行为。 - FR15 — 被拒绝的输入绝不会提前标记或静默丢弃。
DateInput、DateTimeInput、TimeInput 和 NumberInput 在输入完成时揭示值拒绝,并在提交时揭示文本拒绝;在独立字段中,将每次拒绝显示为带有无效状态和一条公告的可见消息,并在提交时保留被拒绝的已输入文本;原生控件在 blur 时恢复其已提交的值,并保留拒绝消息。表单提交的内容不会改变(
spec:AST-118FR4)。warning或success调用方状态,或没有消息的error状态,绝不会隐藏拒绝消息。带有消息的调用方error状态会在 NumberInput 和 TimeInput 上取代它显示;在 DateInput 上仅在onEntryErrorChange时显示;NumberInput 和 TimeInput 通过onEntryErrorChange报告每次拒绝。键入的数字仅在提交时才算完成,因此 NumberInput 在 Enter 或 blur 时揭示其拒绝,而在输入时什么也不揭示。spec:AST-118拥有该规则,包括每种输入何时完成。FileInput 的拒绝针对所选取的文件,它会将这些文件从值中丢弃,并且不在此规则范围内。
允许的组件变体¶
- AV1 — 原生控件与组合控件。 文本字段可以使用原生 inputs;选择控件可以使用 button/listbox 或对话框组合。
- AV2 — 末端控件的机制与含义。 成员可以使用文档流内的 flex 项目或组件局部的脱离文档流通道,并可渲染清除、忙碌、状态、披露、步进器或已文档化的自定义内容。该机制不会削弱 FR1 或 FR2。
- AV3 — 块轴增长与分组适配。 TextArea 和 Tokenizer 在未分组状态下可以沿块轴增长,以容纳多行或多 token 内容。InputGroup 的接纳并不改变这些独立默认值。在分组模式下,被接纳的组件拥有满足 FR3 的呈现。Tokenizer 基于此被接纳,并且当调用方未选择其他受支持的溢出模式时,MUST 默认采用组件自有的溢出处理方式,以保持组的单行外观。此分组默认设置不需要新的公共 prop 或主题目标。
- AV4 — 动作回调形式。 文本编辑成员可以将其 change 事件传递给
changeAction;结构化值成员只能传递提议的值。组件文档自行规定确切的回调类型。 - AV5 — 支持的概念各不相同。 成员不必仅仅为了加入该系列而添加
size、isLoading、changeAction、disabledMessage、清除或 InputGroup 支持。当它暴露其中某个概念时,相应的系列规则适用。 - AV6 — 附加状态支持。 无法满足 FR8 的成员保持附加状态不可用,而不是近似实现该重叠。它仍然通过系列状态契约提供分离状态和工具提示。
- AV7 — 平台检测。 实现可以使用任何受支持的能力测试来识别 iOS 触摸路径,同时不将下限应用于非 iOS 粗略指针。本契约不要求特定的 CSS 查询、浏览器字符串或共享辅助函数。
代表性矩阵¶
| 成员和状态 | 共享不变量 | 有意的变化 |
|---|---|---|
| TextInput / 空、有值或输入中 | 内联尺寸稳定;常规流中的末尾控件不与文本重叠 | 原生输入框以及可选的清除/状态控件 |
| Selector / 占位或已选中 | 末尾控件和分组行保持有界 | 在 DEC-1 下,独立模式的内联尺寸可随显示内容变化 |
| Typeahead / 空、已选或数据源忙碌 | 无论独立还是分组,内联尺寸稳定,且有一个不重叠的末尾区域 | 可编辑输入变为已选 Token;数据源忙碌状态由 BaseTypeahead 负责 |
| Tokenizer / 独立 Token、数据源忙碌和 endContent | 内联尺寸稳定,内容与末尾控件分离清晰 | 独立 Token 可能换行并在块轴方向扩展字段 |
| Tokenizer / 已接纳的 InputGroup 模式 | 分组高度、连接表面、语义和键盘行为保持连贯 | 分组默认采用单行溢出处理;调用者选择的支持的溢出方式在 FR3 范围内可能有所不同 |
| ComplexSelector / 占位、已选或输入中 | 字段表面稳定,Spinner/展开指示器不重叠 | 由调用者负责丰富的弹层内容;不提供内置 InputGroup 支持 |
| 已接纳成员 / InputGroup | 尺寸/高度兼容,只有一个外部表面/焦点所有者,单行几何结构,且语义得以保留 | 组件自行负责其内部的分组截断、折叠、裁剪或溢出处理 |
带有 disabledMessage 的成员 |
原因可触达;变更仍被阻止 | 组件负责焦点目标和 Tooltip 组合 |
| 成员 / 校验状态 | 分离式与 Tooltip 均可用;仅在支持时才默认使用附加式 | 组件自行决定其控件是否安全满足附加式资格 |
| 带下限的文本输入 / iOS 触控 | 可编辑文本至少解析为 16 CSS px,且聚焦不会触发浏览器缩放 | 主题字号可能已满足该下限 |
| 带下限的文本输入 / 非 iOS 粗指针 | 当前主题的字阶保持生效 | 平台和输入硬件可能不同 |
| 由 Field 构成的组件 / 独立、水平标签、InputGroup | 基础 props 放在主要语义控件上;container* 放在渲染 Field 盒子的位置;control* 放在控件盒子上;对根元素设置样式是类型错误 |
在没有 Field 盒子渲染的位置,container* 不生效 |
采用与例外¶
当前发布事实¶
| 组件 | 当前采用情况 | 已记录的例外 |
|---|---|---|
| TextInput | Field、FormLayout、InputGroup、size、width、isLoading、changeAction、清除、状态和禁用原因 |
无 |
| TextArea | Field、FormLayout、size、width、isLoading、changeAction、状态和禁用原因;块轴增长 |
与 InputGroup 不兼容 |
| NumberInput | Field、FormLayout、InputGroup、size、width、clear、status 和禁用原因 | 未随附 isLoading 或 changeAction |
| DateInput | Field、FormLayout、InputGroup、size、width、isLoading、changeAction、clear、status 和禁用原因 |
无 |
| DateRangeInput | Field、FormLayout、size、width、isLoading、changeAction、clear、status 和禁用原因 |
不兼容 InputGroup |
| DateTimeInput | Field、FormLayout、size、width、isLoading、changeAction、clear、status 和禁用原因 |
不兼容 InputGroup |
| TimeInput | Field、FormLayout、InputGroup、size、width、isLoading、changeAction、clear、status 和禁用原因 |
分组的 sheet 表面缺少隐藏标签、描述和 status,且分组 tooltip 的 status 不描述任何内容(component:TimeInput FR10) |
| FileInput | Field、FormLayout、width、isLoading、changeAction、clear、status 和禁用原因 |
没有公开的 size;compact 和 dropzone 模式为组件自有 |
| Selector | Field、FormLayout、InputGroup、size、width、isLoading、changeAction、clear、status 和禁用原因 |
DEC-1 允许独立的内容自适应宽度 |
| MultiSelector | Field、FormLayout、InputGroup、size、width、isLoading、changeAction、clear、status 和禁用原因 |
trigger-display 模式仍为组件自有 |
| ComplexSelector | Field、FormLayout、size、width、isLoading、changeAction 和 status |
没有 InputGroup 或禁用原因 API |
| Typeahead | Field、FormLayout、InputGroup、size、width、clear、status、禁用原因和 BaseTypeahead 数据源加载 | 没有家族级 isLoading 或 changeAction;搜索生命周期由组件自有 |
| Tokenizer | Field、FormLayout、InputGroup、size、width、clear、status、禁用原因、BaseTypeahead 数据源加载以及多 token 块增长 | 没有家族级 isLoading 或 changeAction |
当前已经带有 16px 抗缩放下限的文本输入控件仅在 iOS 上应用该下限。这包括 input 家族成员,以及受家族级 source guard 覆盖的现有共享或更高级文本输入协作者;DEC-6 不要求无关组件额外增加新的下限。
实现差距¶
- Typeahead 状态几何: 当前 main 在显示已选 Token 时将 intrinsic-width 输入移出布局,因此内容自适应父容器可能将字段折叠到值上。其 clear 控件被单独定位,当前的 source-busy 反馈是文档流中的一个静态时钟,且没有
aria-busy;selected、source-busy 和 grouped 组合不具备 FR1–FR3 和 FR7 所要求的 focused 几何覆盖。PR #5555 和 #5682 记录了尝试过的实现,属于非权威证据。任何实现的 DOM/CSS 机制仍归组件自有,并且必须在其确切 head 上依据本契约进行审查。 - Tokenizer 状态几何与分组准入: 当前 main 将
endContent和 clear 控件置于文档流之外,且未预留其渲染宽度,因此较窄的输入内容可能从其下方穿过。Token 数量也可能改变 intrinsic inline size。PR #5555 是尝试组件本地预留的非权威证据。Tokenizer 兼容 InputGroup:component:TokenizerFR30 在 FR3 下记录其 grouped 模式,采用单行溢出处理,且 ungrouped 行为保持不变。 - Selector 数据源状态语义: Selector 和 MultiSelector 在输入
isLoading为 true 时仍保留已提供的选项,但当前的 empty/no-result 展示仍将该标志视为选项数据源 pending,并且两个组件都没有 AST-001 所要求的显式 source-pending API。 - Transition Action 覆盖: 当前 FileInput 的 clear 操作调用
onChange但不带changeAction,并且 FileInput 未在其 Action 处于 pending 期间将提议的受控文件作为乐观值显式持有。在当前 main 上检查到的其他暴露 clear 路径都经由其普通 Action 管线。这些是 FR6 下的符合性缺口,而非替代性的家族语义。 - Status 放置符合性: 当前 Field 默认对任意子元素采用 attached 放置,而未证明该控件满足 FR8。TextArea、Tokenizer 和 FileInput 的 dropzone 是典型的高型、包裹型或自定义表面,不能仅从共享默认值继承 attached。某些成员文档也省略了 tooltip 或整个 status-placement 投影,尽管 Field 会消费家族 sentinel。后续工作必须让 attached 能力以及三个 input-level 选项在每个成员的 API 和文档中准确反映。
- Attached FieldStatus 重叠: attached 放置仅限于合格成员,这些成员的直接控件和所属 root 能可靠暴露解析后的尺寸。合格成员保留 attached 放置;不支持的包裹型、自定义、高型和半透明表面保留组件自有放置,通常为 detached。PR #5769 是尝试从后代
data-size推导重叠实现的非权威证据;该机制本身并不能确立合格性或 root 尺寸所有权。 - Prop 目标: 当前组件尚未满足 FR10。下面的每个组件都接受根级
xstyle/className/style,并且都不接受container*或control*。当前目标:
| 组件 | 根样式作用到 | 基础 props 直达 | 主要语义控件 | 根样式迁移至 |
|---|---|---|---|---|
| FileInput | 控制盒 | 原生文件输入 | 原生文件输入 | control* |
| DateRangeInput | 控制盒 | 控制盒;ref 在触发按钮上 |
范围触发按钮 | control* |
| Selector | 控制盒 | 触发按钮 | 触发按钮 | control* |
| Typeahead | Field | Field | combobox 输入框 | container* |
| Tokenizer | Field | Field | combobox 输入框 | container* |
| Slider | Field | 不转发;ref 在轨道上 |
滑块控件 | container* |
符合性是一种经批准的根样式移除机制;astryx upgrade codemod 会按最后一列将每个组件的根样式重写为它当前所作用到的部件。codemod 无法追踪通过产品包装器自身 props 或 spread 传递的样式;FR10 的类型错误会将这些调用点暴露出来。
- 屏幕键盘(FR13): 当前 main 分支上没有成员满足 FR13。没有任何成员具备键盘处理逻辑,键盘模块也尚不存在;
spec:AST-099列出了每项差距。 - 被拒绝的条目(FR15): 在 InputGroup 内部,成员自身的拒绝状态不会显示可见消息。
spec:AST-118列出了每项差距。 - 验证覆盖情况: 当前单元测试证实了组合、语义和单项状态行为,但尚未提供下文完整的真实浏览器 inline-size/end-overlap 矩阵。本条记录指出这些实现差距,而不是声称它们已经修复。
验证映射表给出的是代表性证据,并非每个成员的全部测试套件。完整覆盖义务以成员表和采用表为准。
验证映射表¶
| 契约 | 验证 | 代表性成员与状态 | 变异或失败预期 |
|---|---|---|---|
| FR1 | 在真实 Chromium 中测量 block、flex-item、inline-block、grid auto-track 及显式宽度容器内的前后 inline-size | TextInput 基线;Selector 例外;Typeahead 空/已选/数据源忙;Tokenizer 零个/一个/多个 token | 值或忙碌状态在已记录例外之外改变了字段的外部 inline-size |
| FR2 | 在受支持的窄宽度及 LTR/RTL 下,真实 Chromium 的 content-box/control-box 重叠矩阵 | clear、Spinner、status、disclosure、Tokenizer 的 endContent;单独及组合 |
内容、光标或指针命中区域与已渲染的末端控件相交,或在该控件卸载后仍残留过期预留空间 |
| FR3 | InputGroup 单元测试,加上渲染尺寸/高度、表面/焦点归属、溢出和交互检查 | 每个获准成员;Tokenizer 零个/一个/多个 token、聚焦/未聚焦、显式/默认溢出;子项/组尺寸不匹配 | 子项保持相冲突的外部几何尺寸、扩展或增加一行、失去关联的焦点/边框归属,或改变命名、键盘、焦点、编辑或选择语义 |
| FR4 | 键盘、指针和辅助功能树测试 | 每个暴露 disabledMessage 的成员 |
原因变得不可达,或被禁用的控件发生突变/激活 |
| FR5 | 来自 AST-001 的 Selector 和 MultiSelector 交互及播报测试 | 输入忙碌时已填充的选项;显式源待定;完成时为空 | 输入忙碌抑制已提供的选项,或替代源状态 |
| FR6 | 针对每个支持 Action 的突变路径的聚焦回调/顺序/乐观/忙碌测试 | 输入、选择、日历/预设、文件选择以及暴露的清除操作 | 回调/Action 顺序改变,乐观反馈消失,或清除路径绕过 Action 契约 |
| FR7 | Typeahead/Tokenizer 源忙碌测试和真实浏览器几何检查 | 直接的 BaseTypeahead、独立包装器、分组 Typeahead、已选择/已分词的值 | 忙碌反馈未命名/重复,缺失 aria-busy,或源加载改变行/内联几何 |
| FR8 | 代表性成员测试以及真实浏览器重叠/透明度/高度检查 | 符合条件的单行直接控件;换行、自定义、高和半透明控件;所有三种放置位置 | 在支持的位置缺少 Attached,在不安全的位置出现,或 tooltip 直接到达 FieldStatus |
| FR9 | inputFontFloor.test.ts、聚焦计算样式检查,以及真实 iOS Safari 焦点证据 |
iOS 触摸、非 iOS 粗指针和桌面精细指针 | iOS 渲染低于 16 CSS px 或焦点缩放,或非 iOS 粗指针收到仅 iOS 的底线值 |
| FR10 | 针对每个 Field 组合组件的 props 进行类型测试,若任一组件接受根级 xstyle、className 或 style 则失败;针对每个基础 prop、container* 和 control* prop 以及两种开发警告进行逐组件渲染测试 |
每个 Field 组合组件单独、在水平标签 FormLayout 中,以及在允许的 InputGroup 内 | 组件通过根级样式进行类型检查、基础 prop 未落在主要语义控件上、container* 未落在 Field 框上或落在控件框上、control* 未落在控件框上,或缺少警告 |
| FR11 | InputClearButton.test.tsx 的工具提示和可访问名称断言,以及真实 Chromium 悬停捕获 |
较长的字段标签;区域设置覆盖;浅色与深色 | 工具提示重复了字段标签,或可访问名称丢失了字段标签 |
| FR12 | Typeahead.test.tsx、BaseTypeahead.test.tsx、Tokenizer.test.tsx、Selector.test.tsx 和 MultiSelector.test.tsx 中针对两个属性的用例,Enter 保持其成员拥有的效果;在触摸模拟手机上的 SearchKeyboard.interaction.browser.spec.ts,其中点击聚焦的搜索输入同时携带两者 |
Typeahead;Tokenizer;Selector 和 MultiSelector 搜索行;带触摸模拟的手机视口 | 缺少某个属性,或 Enter 的效果随标签改变,则失败 |
| FR13 | 待定(缺口):FR9 所命名的逐字段键盘焦点测试和模拟器证据 spec:AST-099 |
FR13 涵盖的每个成员,位于页面中、工作表中、由 Core 移动的停靠栏中、浮动栏中,以及带有自己的 translate 的栏中 |
聚焦字段被留在滚动器中的键盘下方(包括位于 FR9 留给应用的固定容器内的字段)、Core 宿主中,或 Core 移动的停靠栏中;或存在针对该行为的公开 prop;字段与其浮动、自有 translate 或全视口宿主之间没有滚动器时,定位由应用负责,不视为失败 |
| FR14 | DateInput.test.tsx、DateTimeInput.test.tsx、TimeInput.test.tsx 和 NumberInput.rejectedEntry.test.tsx 的 entryErrorBehavior 用例;FormLayout.test.tsx 的 “FormLayout defaultEntryErrorBehavior” 用例 |
每种值下的 DateInput、DateTimeInput、TimeInput 和 NumberInput,独立使用及在 FormLayout 中 | 在 'blur-or-enter' 下出现提交前信号、'complete' 与已发布行为不同,或表单默认值覆盖字段自身的 prop |
| FR15 | NumberInput.rejectedEntry.test.tsx;TimeInput.test.tsx 和 NativeTimeInput.test.tsx 的 rejected-entry 套件;以及其记录所指名的 DateInput 和 DateTimeInput rejected-entry 套件 |
DateInput、DateTimeInput、TimeInput 和 NumberInput,键入型和原生型,独立及分组 | 未完成的输入被标记、提交丢弃被拒绝的文本、拒绝时未显示消息,或其信号部分 |
决策链接¶
DEC-1 — Selector 是独立的内联尺寸例外¶
决策者: cixzhang,2026-08-30
Selector 属于输入字段家族,但独立使用的 Selector 可根据其显示的占位文本或所选值来确定尺寸。此例外并不会移除 FormLayout、受支持的 InputGroup 或明确产品布局所施加的约束。
DEC-2 — Input 加载描述的是值的解析或保存¶
决策者: cixzhang,2026-08-30
对于暴露 isLoading 的成员,它描述的是字段值正在解析或保存,并不意味着选项或支持数据正在加载。当值处于忙碌状态时,数据源 props 保持其正常契约。
spec:AST-001/DEC-1 和 spec:AST-001/DEC-2 将该区别应用于 Selector 和 MultiSelector:已提供的选项保持可用,零选项表示无选择状态,并且初始选项源处于待定状态时必须明确说明。
DEC-3 — Transition Actions 是输入家族契约¶
决策者: cixzhang,2026-08-30
可选的 changeAction API 及其乐观/待定行为属于输入家族。组件文档各自管理其值和事件类型,但成员不得独立重新定义回调顺序、乐观反馈或忙碌状态语义。
公共 API 准入仍由 spec:AST-002/DEC-1 负责;该家族不增设独立的无效状态或 API 护栏策略。
DEC-4 — Attached 状态是有条件的能力,而非通用几何¶
决策者: cixzhang,2026-08-31
每个输入都提供 detached 和 tooltip 状态放置。仅当成员的直接控件是不透明、有边框、固定高度,并且其所属根节点能够可靠反映用于重叠的解析尺寸时,该成员才提供 attached。只要支持 attached,它就是默认方式。包裹式、自定义、过高或半透明的表面通常使用 detached 或保留组件自有的放置方式。固定高度是由解析尺寸设定的,在 spec:AST-102 FR4 下会随设定的文本尺寸而增长。
直接 FieldStatus 仍仅限于 attached 和 detached 两种呈现形式。Tooltip 是输入家族的一种组合,Field 在渲染 FieldStatus 之前会先消费它。
已拒绝:从任何后代 data-size 推导通用 attached 重叠,因为后代元数据并不能证明直接表面是不透明、有边框、固定高度的,也不能证明它是该解析尺寸的所有者。
DEC-5 — InputGroup 准入基于能力¶
决策者: cixzhang,2026-09-09
InputGroup 兼容性并非封闭的组件白名单。任何输入家族成员,只要其组件契约和实现明确采用分组模式并满足 FR3,即可参与:兼容的解析尺寸和控件高度,不存在相互竞争的外部 Field 或表面几何,一致且连贯的连接边框/圆角/焦点归属,单行分组几何,以及保持不变的输入语义和键盘行为。
Tokenizer 在此规则下获得准入。其非分组的换行和溢出默认行为保持不变。在分组模式下,当调用方未选择受支持的溢出模式时,Tokenizer 默认采用组件自有的处理方式,以保持分组的单行外观。实现可以复用其现有的溢出表面;此决策不新增任何公共 prop、回调、主题目标或通用 InputGroup 分支。
已拒绝:永久硬编码的白名单、仅针对 Tokenizer 的例外、允许在未完成完整分组适配的情况下消费上下文,或强制将独立的多行/多 token 输入改为单行呈现。
DEC-6 — 16px 聚焦缩放下限仅适用于 iOS¶
决策者: cixzhang,2026-09-20
带有抗缩放保护措施的文本输入控件,在受支持的 iOS 触摸路径上将可编辑文本解析为至少 16 CSS px。其他粗指针平台保留当前主题的字号比例,因为它们不存在此保护措施所针对的 iOS 聚焦缩放行为。
该契约管理的是可观察的平台结果,而非特定的特性查询或源码模式。现有的共享和更高级文本输入表面可以复用该家族规则而不必成为输入家族成员,且此决策不要求无关控件采用新的下限。
已拒绝:将 16px 下限应用于所有粗指针。指针精度并不能确立 iOS 浏览器行为,而且会在 Android 和具备输入能力的触摸笔记本上放大文本,却无法防止相应的聚焦缩放失败。
DEC-7 — Field 组合组件禁止根样式¶
决策者: cixzhang、2026-10-11
调用方将基础 prop 传给字段时,期望它作用于人实际操作的控件,因此 ref、ID、测试 ID、ARIA 和事件处理器都应到达主要语义控件。字段有两个可设置样式的表面:整个字段和其可视控件框;根级 xstyle 必须静默选择其中之一。因此,该组件族声明基础样式的一个例外:不接受根样式输入,只提供 container*(用于 Field)和 control*(用于控件框),每组都对应一个 AST-071 part 集。产品包装组件将 props 展开到 input 中时,会在调用处收到类型错误,而不是产生 codemod 无法察觉的视觉迁移。每个 part 在每个成员和布局中只保持一个目标;当其元素不渲染时,该 part 不生效,而不是移到另一个元素。
已否决:保留根级 xstyle 并将其路由到 Field;props 展开和包装器会静默地转移样式。
DEC-8 — Prop 重定向保持各组件的处理器顺序¶
决策者: cixzhang、2026-10-11
消费者处理器相对组件自身处理器的运行时机,以及它能否取消内置行为,都属于已发布的交互行为,architecture:public-component-api INV9 会保持其稳定。将基础 props 移到语义控件会改变消费者处理器到达的元素,但不会改变该行为;因此组件保持其已发布的顺序和取消能力,并记录任何不同于组件优先组合的顺序。组件优先的取消组合仅适用于组件首次转发的处理器。
已否决:将所有被重定向的处理器都按组件优先方式组合;消费者如果取消内置行为,或观察组件取消的事件,其行为会在没有 API 变更提示的情况下发生变化。
DEC-9 — 清除按钮的工具提示仅命名该操作¶
决策者: cixzhang、2026-10-13
字段的标签已经位于清除图标旁边,因此视力正常的用户只需要知道该操作。重复标签会让较长或名词短语形式的标签读起来很别扭。屏幕阅读器用户看不到按钮周围的字段,因此无障碍名称保留标签。
已否决:工具提示重复无障碍名称;这会使屏幕上的标签加倍。
DEC-10 — 搜索输入框将 Return 键标注为“搜索”¶
决策者: cixzhang、2026-11-01
成员组件的搜索输入框已经知道 Enter 会进行搜索或提交结果,因此它自行标注该按键(architecture:public-component-api INV4),就像 NumberInput 会选择其数字键盘(component:NumberInput FR1)一样。搜索词是会被自动更正重写的名称和标识符,因此自动更正处于关闭状态。
开放问题¶
无。
内容边界¶
本记录仅涵盖跨组件的字段行为。组件 props、选择/搜索算法、视觉目标映射、实现机制、当前审计结果以及产品特定的组合,仍归属于各自的组件、架构、设计、审计或调用点所有者。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx