跳转至

CommandPaletteInput 组件契约

契约概览

领域 契约
公共契约 一个查询字段,具有上下文支持的搜索状态、可选尾部内容,以及包装器/字段属性的拆分边界。
行为 无弹出属性的独立使用是一个搜索框;调用方的弹出属性或 CommandPalette 上下文提供组合框状态和关联关系。在触摸键盘上,该字段显示搜索键且不进行自动更正(FR6)。
最终用户影响 屏幕阅读器用户会获得与是否存在受控结果弹出项相匹配的角色和弹出状态。
构建者影响 上下文拥有的弹出语义无法通过原生透传属性替换;仍然支持独立的调用方拥有的弹出语义。
兼容性/就绪状态 一个 [fix] 恢复无弹出语义,同时保留已发布的调用方拥有的弹出关联,并将字段默认命名为“Search commands”而不是其占位符;主要回调命名仍为 OQ1。
审查检查 拒绝无关联的独立组合框状态、可被覆盖的拥有弹出语义、空尾部装饰,或更改的输入 ref 路由。
治理规则 architecture:public-component-api/INV2,INV4,INV5;spec:AST-017/FR1,FR3,FR5,FR7,FR53;spec:AST-020/FR1,FR2;spec:AST-056/AR2;family:input-fields/FR12;WCAG 2.2 4.1.2。

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

意图

CommandPaletteInput 呈现命令面板的文本查询。它可以绑定到 CommandPalette 的搜索和导航上下文,或在不存在结果弹出上下文时充当独立的搜索字段。

兼容性与迁移

  • 发布的默认值保留:对于无弹出独立语义输出和默认可访问名称,保留值为 no;调用方拥有的弹出关联以及所有其他 CommandPalette 输出保持等效
  • 兼容性类别:在 spec:AST-017/FR1,FR3,FR5 下对独立语义进行契约恢复,因为无弹出的独立使用没有已发布的弹出关联需要保留;在 spec:AST-017/FR53 下对默认名称进行可访问性行为修复
  • 搜索键盘提示:FR6 的 enterkeyhint 和 autocorrect 是 spec:AST-017/FR5,FR7 下的补丁 [feat];它们不改变任何 API,且 Enter 保持 FR2 的路由
  • 受控/非受控行为:不变
  • 迁移决策:role="combobox" 保留早期的独立语义,label 或 aria-label 保留特定名称;主要回调命名问题仍为 OQ1

消费者迁移说明应包含在消费者文档和发布说明中。

所有权边界

拥有

  • Input 内部的布局:搜索图标、原生查询字段、加载 Spinner 的放置和尾部内容。
  • 当存在 CommandPalette 上下文时,查询字段的角色和弹出状态。
  • 搜索值、值更新和键盘导航的上下文回退。

不拥有 / 非目标

  • 结果弹出、选项集合、选择或搜索编排——由 component:CommandPalette 及其列表/项部分拥有。
  • Spinner 和搜索图标的渲染——委托给 Spinner 和 Icon。
  • 调用方提供的尾部内容行为——由产品调用点拥有。

公共概念

概念 封闭值或状态 含义 按变体/方向/状态的可用性 默认值 所有者 稳定性 无效值行为
查询绑定 显式;CommandPalette 上下文;原生 查询文本变更的源和目标。 所有使用 上下文,其次原生 component:CommandPaletteInput 已发布 缺少处理器时保留原生状态
弹出语义 独立搜索框;独立的调用方拥有的弹出;上下文的 CommandPalette 弹出 查询字段是否控制结果弹出。 取决于上下文 独立搜索框 component:CommandPaletteInput 稳定 独立覆盖持续存在;CommandPalette 上下文优先
尾部内容 忙碌指示器;endContent;两者;不存在 查询后的支持状态或调用方内容。 所有使用 不存在 component:CommandPaletteInput 已发布 布尔值、空字符串、null 和 undefined 值均视为不存在

行为与布局契约

ID 候选不变量 依据 草稿审查状态
FR1 显式 value 和 onValueChange 优先;否则 CommandPalette 上下文提供搜索状态;当两者都不存在时,保留原生非受控状态。 已发布的源码、文档和测试 已验证当前行为
FR2 调用方的 onKeyDown 先于上下文导航运行;阻止事件或存在活动的 IME 组合会阻止上下文委托。 已发布的源码和测试 已验证当前行为
FR3 ref 和原生透传属性到达原生查询字段;独立的调用方自有弹出语义保持不变,而 CommandPalette 上下文拥有其弹出角色和关系;xstyle、className 和 style 自定义周围的 Input。 已发布的源码和文档;architecture:public-component-api/INV5 已验证当前的传递行为
FR4 待处理状态和可渲染的 endContent 共享一个尾部内容组;布尔值、空字符串、null 和 undefined 不会创建空的尾部装饰性内容。 React 渲染语义和当前工具约定 已验证当前行为
FR5 自动聚焦默认启用,并在内联 Dialog 内被抑制;hasAutoFocus={false} 同时抑制聚焦工作和自动聚焦标记。 已发布的源码、文档和测试 已验证当前行为;浏览器时序证据仍存在
FR6 查询字段携带 enterkeyhint="search" 和 autocorrect="off",独立使用和位于 CommandPalette 内部时均如此,如 family:input-fields/FR12 对搜索输入框所做的规定;无论按键上显示什么,Enter 都保持 FR2 的路由。 family:input-fields/FR12, DEC-10 已验证当前行为

允许的变体

  • AV1 — 查询内容。 值、占位符、标签和调用方提供的尾部内容可以变化,而不会改变语义归属。
  • AV2 — 委托的视觉元素。 Icon 和 Spinner 可以更改内部标记,同时保持其公共约定。

代表状态

状态 必需的不变量 允许的变体
独立,无弹出 具名 searchbox,且不含仅用于弹出层的 ARIA 状态。 显式的值和变更处理器。
独立,调用方弹出 调用方的角色、状态、关系和激活后代保持不变。 调用方自有的弹出模型。
上下文关联,已关闭 具名 combobox 引用列表并报告收起状态。 查询值和尾部内容。
上下文关联,无结果 具名 combobox 报告收起状态,且不引用任何列表。 空消息或待处理消息。
上下文关联,打开 具名 combobox 引用列表并报告展开状态。 高亮选项和结果数量。
上下文关联,已高亮 激活后代指向上下文拥有的高亮选项。 高亮的索引。
待处理或尾部 辅助内容保持在逻辑尾部边缘。 Spinner、调用方内容,或两者。
内联 Dialog 挂载不会抢占周围页面的焦点。 查询和结果内容。

转换与优先级顺序

  • ORD1 — 搜索状态。 显式属性 → CommandPalette 上下文 → 原生非受控状态。
  • ORD2 — 键盘处理。 调用方处理器 → 默认行为被阻止或 IME 组合检查 → CommandPalette 上下文处理器。
  • ORD3 — 无障碍名称。 原生 aria-label → label → 翻译后的默认文本“搜索命令”(DEC-1)。占位符文本绝不是名称。

性能与资源

  • PR1 — 焦点调度。 一个已挂载的合格字段最多调度一个动画帧焦点请求;不会保留任何监听器或观察器。

无障碍契约

  • AR1 — 名称。 原生查询字段始终具有来自 ORD3 的显式无障碍名称,且绝不会从占位符文本中获取名称,满足 spec:AST-056/AR2 和 WCAG 2.2 4.1.2。
  • AR2 — 角色与弹出状态。 没有弹出属性的独立使用暴露 searchbox,且不带仅用于弹出层的状态。提供自有弹出关系的独立调用方保留这些语义。CommandPalette 上下文暴露 combobox,带有上下文拥有的展开状态、列表关系、自动补全模式和激活后代,遵循 spec:AST-020/FR1,FR2 和 WAI-ARIA combobox 模式。当 CommandPalette 中没有可选结果时,字段报告收起状态,且没有列表关系或激活后代;并且激活后代始终指向一个存在的选项。
  • AR3 — 语义归属。 在 CommandPalette 上下文中,字段拥有 role、aria-expanded、aria-autocomplete、aria-controls 和 aria-activedescendant,这些属性会替换同名的原生透传属性;其他 ARIA 属性(包括 aria-haspopup 和 aria-owns)原样透传。独立的调用方拥有的角色和关系保持完整。

设计关系

解剖结构或状态 设计要求 表示权威 层级角色 组件契约
输入 将搜索字形、查询字段、加载旋转器和尾部内容内联排列。 当前源码和公开文档 主要 FR3、FR4
搜索字形 标识查询操作,而不添加名称。 图标组件 辅助 AR1
查询字段 接收文本、焦点、名称和弹出语义。 当前源码和无障碍标准 主要 FR1–FR3、AR1–AR3
加载旋转器 在尾部内容之前指示待处理的上下文搜索。 旋转器组件 辅助 FR4
尾部内容 将调用方内容保持在逻辑行尾。 当前源码和公开文档 辅助 FR4

家族与系统关系

  • component:CommandPaletteInput 拥有结果弹出上下文、聚合组合以及开放的主题可达性问题;该组件拥有默认输入的查询字段语义,并将其绑定到该上下文。
  • spec:AST-017 拥有已发布独立调用方弹出和无弹出场景的兼容性分类。
  • spec:AST-020 提供 WCAG 2.2 和采用模式的证据边界。
  • spec:AST-056/AR2 要求查询字段名称不同于占位符文本;ORD3 和 AR1 满足该要求。

验证映射

契约 验证 代表性状态 变更或失败预期 审计部分
FR1–FR3 CommandPaletteInput.test.tsx 显式、上下文、阻止按键、原生、调用方弹出 反转状态优先级、重路由 ref、放弃独立弹出关系,或允许上下文语义被覆盖,都会导致聚焦的 DOM 测试失败。 audit:CommandPaletteInput/testing
FR4 CommandPaletteInput.test.tsx 数字、空、忙碌、调用方内容 真值路由会产生空白界面框架,或将数字内容移离尾部边缘。 audit:CommandPaletteInput/behavior
FR5 聚焦的单元测试以及精确 HEAD 浏览器证据 启用、禁用、内联 符合条件的焦点丢失、禁用焦点被安排,或内联模式抢走焦点。 audit:CommandPaletteInput/behavior
FR6 CommandPaletteInput.test.tsx 的属性与回车键用例(独立和上下文);SearchKeyboard.interaction.browser.spec.ts 在触摸模拟手机上的运行 独立;上下文;带触摸模拟的手机视口 缺少 enterkeyhint 或 autocorrect,或回车键路由改变,则失败。 audit:CommandPaletteInput/behavior
AR1–AR3 单元测试、精确 HEAD axe/浏览器运行以及源码审查 独立、打开、关闭、高亮 错误的角色/状态、调用方覆盖自有属性,或由占位符派生的名称,会导致语义和名称断言失败。 audit:CommandPaletteInput/a11y
主题/RTL 目标清单、Storybook 夹具和 RTL D2 审计 独立尾部内容、上下文 目标丢失或物理顺序变化会导致自有夹具失败。 audit:CommandPaletteInput/theming

决策日志

DEC-1 — 查询字段的默认名称是“Search commands”

参考: component:CommandPaletteInput/DEC-1 决策者: cixzhang,2026-10-14

屏幕阅读器用户到达该字段时,会听到它的用途,无论占位符文本是什么,或者是否设置了占位符。默认值是一个固定的、可本地化的“Search commands”;label 和 aria-label 会替换它,并且占位符文本永远不会作为名称。

已拒绝:回退到占位符,因为调用方将占位符作为视觉提示编写,而 AST-056 AR2 不接受其作为名称。

未决问题

  • OQ1 — 已发布的 onValueChange(value) 主回调和原生事件 onChange(event) 特例应如何迁移到共享的 onChange 回调语法,同时不破坏现有调用方? (human-api)

内容边界

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

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