跳转至

CommandPalette 组件契约

契约概览

区域 契约
公共契约 CommandPalette 及其文档化的 props 和插槽,由 CommandPaletteInput、CommandPaletteList、CommandPaletteItem、CommandPaletteGroup、CommandPaletteEmpty 和 CommandPaletteFooter 组成,位于 Dialog 内。
行为 Dialog 中的可搜索命令:一个 combobox 查询字段;仅当存在可选结果时才显示结果 listbox,否则显示空消息;以及一个键盘引导页脚。模态 Escape 归属于 Dialog 的共享关闭机制。
最终用户影响 键盘和屏幕阅读器用户可以搜索并运行命令,原生文本编辑功能保持不变,听到所显示的空消息,并且每按一次 Escape 关闭一层嵌套层。
构建者影响 无。
兼容性/就绪状态 记录已发布行为;无公开变更。AR1 的调用方 aria-label 规则是 component:CommandPaletteList 中的一个实现缺口,已在 Current-state impact 中列出;两个所有者问题仍未解决(OQ2 询问 INV5 是否应将此复合语义解读声明为整个组件族范围)。
评审检查 拒绝本地模态 Escape 处理、IME 路由、Home/End 结果导航、空 listbox、过期的 active descendant、仅占位符的名称、不匹配的 Empty 公告或缺口。
治理规则 family:overlay-dismissal/FR1、FR2、FR4、FR5;spec:AST-056/FR3、AR1、AR2;spec:AST-092/FR4;spec:AST-092/FR9(仅其结果;FR10);现有公共组件和委托所有者契约。

此表是评审投影;下方正文具有权威性。

意图

CommandPalette 在 Dialog 内呈现可搜索的命令。它负责搜索与选择的编排,以及整体消费者结构,同时将其表面和模态关闭顺序委托给 Dialog。

兼容性与迁移

  • 已发布的默认行为保留:yes
  • 兼容性类别:记录已发布行为;无公开变更
  • 受控/非受控行为:如 CommandPalette.doc.mjs 中所记录
  • 迁移决策:无

消费者迁移说明属于消费者文档和发布说明。

当前状态影响

  • List 会替换调用方的名称(AR1)。 构建者明确提供的 aria-label 目前不会为 List 命名;component:CommandPaletteList 记录了该缺口。

所有权边界

拥有

  • 搜索编排,以及当前 Input、List、Item、Group、Group heading、Empty 和 Footer 部件及目标的组合。
  • 默认 Input 内部渲染的原生 Query 字段的组合;该字段的语义和原生透传由 component:CommandPaletteInput 拥有。

不拥有 / 非目标

  • Dialog 的表面、Icon 的字形、Spinner 的加载指示器或 Kbd 的快捷键徽章——由各自组件拥有。
  • 调用方提供的替换 Input、Footer、item 内容或尾部输入内容——由产品调用点拥有。
  • Item 选项的透传、指针、禁用、选中、高亮和独立滚动语义——由 component:CommandPaletteItem 拥有。
  • command-palette 根目标——不存在此类目标。
  • 超出下方所链接当前记录之外的共享层托管、定位或生命周期规则。
  • List 根的 accessible name、list-id 应用、原生透传和溢出滚动——由 component:CommandPaletteList 拥有。
  • Group 的角色、名称和标题——由 component:CommandPaletteGroup 拥有;Footer 的引导——由 component:CommandPaletteFooter 拥有;Empty 表面——由 component:CommandPaletteEmpty 拥有。

公共概念

没有引入新的公共概念。消费者 props、插槽和用法仍记录在 CommandPalette.doc.mjs 及其子组件文档中。

行为与布局契约

ID 不变量 依据
FR1 默认渲染会在委派的 Dialog 内部将 Input 和 Footer 放置在结果表面周围。该表面在存在 Items 时是一个 List(listbox),否则是一个普通 Empty 容器。在首次查询的结果提交之前,当该查询处于待处理状态时,结果表面保持 Empty 容器的大小,且不显示任何消息;一旦答案被提交,后续待处理的查询会保留当前结果或“搜索为空”消息,直到其自身结果提交(即“Pending search”状态行;component:CommandPaletteEmpty FR2)。默认 Footer 仅在 footer 被省略、为 null 或 undefined 时渲染;任何其他 footer 值都会替换它,因此 footer={false} 不显示 Footer 指引,同时 Footer 区域保留其分隔线(architecture:react-component-runtime INV16)。 当前源码、文档、测试以及 ARIA required-child 规则
FR2 Input、List、Item、Group、Group 标题、Empty 和 Footer 携带下文记录的七个当前 command-palette-* 目标;不存在 command-palette 根目标。 当前源码与目标文档
FR3 默认 Input 会将其 Search 字形委托给 Icon,并将待处理的 Loading spinner 委托给 Spinner;默认 Footer 会将键盘快捷键委托给 Kbd;承载它们的表面会委托给 Dialog。 当前源码与组件文档
FR4 查询字段是 Input 内部一个独立的原生文本字段,且没有单独的公共目标。command-palette-input 目标位于周围的搜索区域,而非原生字段上。 当前源码与目标文档
FR5 模态面板不占用 Escape,将其留给 Dialog 的共享关闭栈,以便嵌套成员处理第一次按键;内联预览不会注册为层,因此在本地关闭。 family:overlay-dismissal/FR1, FR2, FR4, FR5
FR6 可编辑查询字段保留 Home 和 End 以用于原生光标移动,使用 PageUp 和 PageDown 导航到第一个/最后一个结果,并且不将活动中的 IME 组合键路由到命令。 WAI-ARIA 可编辑组合框(combobox)约定;客观 IME 完整性
FR7 已提交的结果集在展示前重置高亮;查询输入仅对当前可选集合中存在的索引发出 active-descendant。 WAI-ARIA active-descendant 完整性
FR8 空搜索公告镜像所渲染的 emptySearchText,包括富调用方内容;查询输入的默认可访问名称独立于其占位符。 spec:AST-056/FR3, AR1, AR2
FR9 当面板打开时,新的 searchSource 会针对它重新运行当前查询,若查询为空则针对 bootstrap 运行:查询文本保持不变,来自先前来源的结果会被作为过期结果拒绝(spec:AST-092 的过期查询规则),并且高亮按 FR7 的要求重置。 与 spec:AST-092/FR4(SearchSource 契约)保持一致
FR10 被拒绝的 search() 以空答案结束并显示空结果状态,正如 typeahead 失败的答案在没有任何内容显示时所表现的那样;被拒绝的 bootstrap() 以无初始项结束并显示初始空状态。两者都不会抛给错误边界。 与 spec:AST-092/FR9 要求 typeahead 产生的结果保持一致。

允许的变化

  • AV1 — 结果。 项目数量、分组、选中内容和空状态可以变化,而不改变整体结构。
  • AV2 — 插槽。 调用方提供的 Input 和 Footer 内容可以替换默认内容,而不会成为 CommandPalette 所有的子部件。
  • AV3 — 委托渲染。 Dialog、Icon、Spinner 和 Kbd 可以在保留各自公开契约的同时改变其内部元素结构。

代表性状态

状态 必需不变式 允许的变化
未分组结果 列表包含 Item 实例。 项目数量和调用方渲染的内容。
分组结果 列表包含 Group、Group 标题和 Item 实例。 组名、数量、排序和项目内容。
空引导/搜索 Empty 取代 listbox 语义;搜索为空文本按渲染结果播报。 调用方提供的丰富内容,包括普通控件。
待处理搜索 默认 Input 可能包含 Loading spinner。 没有待处理搜索时不显示 Spinner。
默认插槽 Input 和 Footer 渲染其文档化的默认内容。 Footer 快捷键文本和翻译后的标签。
调用方替换的插槽 插槽内容替换相应的默认内容。 替换结构仍归调用方所有。

转换与优先级顺序

  • 除 FR1–FR10 外,不存在搜索、选择、布局或样式的优先级规则。

性能与资源

  • 无资源规则。

可访问性契约

  • AR1 — 命名复合体。 包含的 Dialog、combobox、已填充的 listbox、组、选项、忙碌状态、空状态和键盘指南都保留其归属的可访问名称和角色。调用方显式提供的 aria-label 为 List 或 Group 命名(architecture:public-component-api INV5);listbox 和 option 角色以及选项状态保持组件所有,正如 component:CommandPaletteInput AR3 所记录。component:CommandPaletteList 记录了当前 List 替换调用方名称的位置。当不存在可选中结果时,结果表面和 combobox 会省略 listbox、expanded、controls 和 active-descendant 语义,使丰富的 Empty 内容保持普通的非嵌套内容。
  • AR2 — 最顶层 Escape。 模态命令面板将无人认领的 Escape 按键委托给 Dialog 的共享关闭栈。嵌套的已注册表面处理第一次按键;宿主命令面板保持打开,直到它成为最顶层。
  • AR3 — 内联预览。 仅用于文档的内联渲染保持在共享层栈之外,并保留其本地的 Escape 关闭行为。
  • AR4 — 可编辑查询键。 Home 和 End 保留原生光标移动行为;PageUp 和 PageDown 导航到第一个和最后一个结果;处于活动状态的 IME 组合键仍由输入法管理。
  • AR5 — 渲染的空消息。 搜索进入死胡同时,会播报由 emptySearchText 渲染的文本,包括调用方组件和链接生成的文本。
  • AR6 — 查询字段名称。 默认查询字段名称是一个本地化的“搜索命令”标签,与其占位符无关;调用方的 label 和原生 aria-label 覆盖仍受支持。
  • AR7 — 现有的活动选项。 结果变化会重置高亮,并且仅当索引选项存在于当前可选集中时,aria-activedescendant 才会存在。

设计关系

Anatomy or state 设计要求 呈现权威 层级角色 组件契约
Dialog 呈现包含的模态表面。 component:Dialog 辅助 FR1, FR3
Input 绘制查询字段周围的搜索区域及辅助视觉。 当前源码与公共文档 突出 FR1, FR2, FR4
Search glyph 在默认 Input 中呈现搜索符号。 component:Icon 辅助 FR3
Query field 在 Input 内接受原生文本查询。 当前源码与公共文档 突出 FR1, FR4
Loading spinner 在默认 Input 中指示进行中的搜索。 component:Spinner 辅助 FR3
List 呈现当前结果集合或空状态。 当前源码与公共文档 辅助 FR1, FR2
Item 呈现一个可选择的命令结果。 当前源码与公共文档 突出 FR1, FR2
Group 将相关 Item 归组排列。 当前源码与公共文档 辅助 FR1, FR2
Group heading 在视觉上标记一个 Group。 当前源码与公共文档 辅助 FR1, FR2
Empty 呈现无结果或无查询消息。 当前源码与公共文档 突出 FR1, FR2
Footer 呈现默认指引或调用方提供的页脚内容。 当前源码与公共文档 辅助 FR1, FR2
Keyboard shortcut 在默认 Footer 中将一个快捷键呈现为绘制的按键徽标。 component:Kbd 辅助 FR3

原生 Query field 与承载 command-palette-input 的 Input 区域相互独立。它没有直接目标;是否应该有目标属于 OQ1。

主题结构

{
  "Dialog": {
    "delegatesTo": {"owner": "component:Dialog", "target": "dialog"}
  },
  "Input": {"target": "command-palette-input"},
  "Search glyph": {
    "delegatesTo": {"owner": "component:Icon", "target": "icon"}
  },
  "Query field": {
    "none": {
      "reason": "unsettled: No current public target is applied directly to the native query field; future exposure still needs an owner decision"
    }
  },
  "Loading spinner": {
    "delegatesTo": {"owner": "component:Spinner", "target": "spinner"}
  },
  "List": {"target": "command-palette-list"},
  "Item": {"target": "command-palette-item"},
  "Group": {"target": "command-palette-group"},
  "Group heading": {"target": "command-palette-group-heading"},
  "Empty": {"target": "command-palette-empty"},
  "Footer": {"target": "command-palette-footer"},
  "Keyboard shortcut": {
    "delegatesTo": {"owner": "component:Kbd", "target": "kbd"}
  }
}

这七个本地目标是当前的公共接缝。委托部分保留其现有的组件所有者。Query field 的 none 处置尚未确定(OQ1),并不授权新目标。

家族与系统关系

  • architecture:component-theming-surface 负责结构资格认定、目标映射、委托以及事实性的 none 处置。
  • architecture:public-component-api 负责稳定的 props 与组合表面。
  • architecture:interaction-modality/INV4 负责受支持模态路径的可达性;确切的查询键细节遵循客观的 editable-combobox 与 IME 组合标准。
  • spec:AST-056/FR3、AR1 和 AR2 负责渲染后的空搜索公告一致性,以及独立于占位文本的可访问查询字段名称。
  • family:overlay-dismissal 负责最顶层 Escape 与关闭请求的排序;CommandPalette 通过 Dialog 采用该机制,同时保留本地内联预览的关闭行为,因为内联模式不注册为层。
  • architecture:layer-runtime 记录:模态路径将 Escape 委托给 Dialog 的共享关闭注册,而未注册的内联预览保留本地关闭行为。

验证映射

契约 验证 代表性状态 变更或失败预期 审计章节
FR1 TBD TBD TBD TBD
FR2 TBD TBD TBD TBD
FR3 TBD TBD TBD TBD
FR4 TBD TBD TBD TBD
AR1 TBD TBD TBD TBD
AR2 TBD TBD TBD TBD
AR3 TBD TBD TBD TBD
AR4 TBD TBD TBD TBD
INV5 TBD TBD TBD TBD
FR1, AR1 CommandPalette 根组件与子组件测试套件;CommandPalette.test.tsx 的 pending 状态用例;CommandPalettePending.a11y.chromium.spec.ts(pending 状态下保持空表面的高度) 默认、分组、空、pending、富空(rich Empty)和已替换插槽 暴露空的 listbox、使 Input 的 popup 属性保持为空,或将富空(rich Empty)控件嵌套在 option 语义之下,都会导致聚焦的角色断言失败。证据缺口:FR1 的 footer 规则(仅当 footer 被省略、为 null 或 undefined 时才显示默认 footer;footer={false} 会留下一个空的 footer 栏)仅通过源码检查核实;没有任何测试传入 footer={false}。 audit:CommandPalette/anatomy
FR2 聚焦子组件的测试套件及 themingTargets.test.ts 七个位于其所属元素上的本地目标 移除或移动当前目标会导致聚焦的放置断言或全局清单断言失败。 audit:CommandPalette/theming
FR3 CommandPaletteInput.test.tsx 和 CommandPaletteFooter.test.tsx 默认的搜索字形、pending 状态的 Spinner 以及 Footer 的 Kbd 替换或移除被委托的 Icon、Spinner 或 Kbd 实例会导致 composed-owner 断言失败。 audit:CommandPalette/theming
FR4 CommandPaletteInput.test.tsx 原生查询字段,含 idle 与 pending 状态的 Input 移除该字段会导致 combobox 测试失败;添加字段目标需要显式更新映射。 audit:CommandPalette/anatomy
FR5, AR2, AR3 CommandPalette.test.tsx 带嵌套层的 Modal 宿主;内联预览 恢复本地 modal 的 Escape 处理会关闭宿主而不是嵌套表面;移除内联分支会丢失预览关闭功能。 audit:CommandPalette/interaction
FR6, AR4 CommandPalette.test.tsx 和 CommandPaletteInput.test.tsx Home、End、PageDown、Enter 以及激活的 IME 组合输入 将 Home/End 路由到结果,或转发组合中的命令按键,会导致 user-event 与原生组合断言失败。 audit:CommandPalette/interaction
FR7, AR7 CommandPalette.test.tsx 和 CommandPaletteInput.test.tsx 已填充、空和重新填充的结果集 保留超出范围的高亮,或暴露其不存在的活动后代,会导致转换断言和直接边界断言失败。 audit:CommandPalette/a11y
FR8, AR5, AR6 CommandPalette.test.tsx、CommandPaletteInput.test.tsx 以及 i18n 检查 富调用方;空内容;默认查询名称和调用方查询名称 如果播报的目录文案覆盖了渲染的调用方内容,或仅通过占位符文本命名查询,则实时区域、名称和目录断言失败。 audit:CommandPalette/a11y
FR9 CommandPalette.test.tsx “打开状态下切换新 searchSource”套件:在打开状态下,分别在有查询和空查询时切换来源;新来源仅被查询一次,不显示旧行,且高亮重置。 打开且带有已输入查询;打开且带有空查询;来自旧来源的迟到结果;一个高亮行;一个已关闭的命令面板 新来源未被查询、被查询两次、显示了旧来源的行、查询文本丢失或保留了高亮,都会失败。 —
FR10 CommandPalette.test.tsx “被拒绝的搜索来源”套件 Bootstrap 拒绝;搜索拒绝或抛出;被取代的查询被拒绝 拒绝到达错误边界、使忙碌状态保持开启、保留旧行,或让被取代的查询清空当前结果,都会失败。 audit:CommandPalette/interaction
主题结构映射 scripts/check-knowledge.mjs 规范结构(canonical anatomy)和七个当前本地目标 缺失、多余、带前缀、过期或基于别名的映射均导致仓库验证失败。缺口:如果某个已映射部件停止绘制,没有任何检查会失败。 audit:CommandPalette/theming

有针对性的目标位置断言覆盖全部七个本地目标。组合的 Input 与 Footer 测试还验证了委托的 Search Icon、pending 状态的 Spinner,以及四个默认的 Kbd 快捷键。

决策日志

未记录任何组件级决策。

开放问题

  • OQ1 — Query 字段是否应该获得一个稳定的公开主题目标?(human-api) 它目前没有直接目标,也没有负责人决定是否应该。
  • OQ2 — architecture:public-component-api 的 INV5 是否应在全家族范围内声明复合语义解读?(human-api) 在 CommandPalette 这样的复合组件中,combobox、listbox 和 option 等角色以及选项状态归组件所有,并替换调用方的角色和状态,正如 component:CommandPaletteInput 的 AR3 所记录;但调用方显式提供的名称仍然优先。在 INV5 中声明这一点会让每个复合组件都遵循;而将它留在这里,则使其成为 CommandPalette 的解读,其他复合组件可能不会共享。

内容边界

本文件不重复使用者的 prop 表格/示例、共享层或模态规则或实现步骤,而是链接到其所属文档。

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