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-apiINV5);listbox和option角色以及选项状态保持组件所有,正如component:CommandPaletteInputAR3 所记录。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