CommandPaletteItem 组件契约¶
契约概览¶
| 领域 | 契约 |
|---|---|
| 公共契约 | 一个结果选项,具有基于上下文的身份、高亮、选中和关闭行为;显式的独立视觉状态和指针激活仍然可用。 |
| 行为 | 消费者点击首先执行;取消会停止选择;成功激活会在本地报告、更新上下文并关闭;禁用项不会运行点击回调。 |
| 终端用户影响 | 禁用命令无法激活,键盘焦点、选中值和选项身份保持独立且持续暴露。 |
| 构建者影响 | 无。 |
| 兼容性/就绪状态 | 记录已发布行为;无公共变更。两个实现差距,列于“当前状态影响”下;两个所有者问题保持开放。 |
| 审查检查 | 拒绝禁用激活、丢失独立 DOM 身份、将高亮当作选中的 ARIA、嵌套交互子元素,或第二个上下文滚动所有者。 |
| 治理规则 | architecture:public-component-api/INV5,INV7; architecture:interaction-modality; spec:AST-017/FR1,FR3,FR5; spec:AST-020/FR1,FR2; WAI-ARIA 1.2 option。 |
此表是审查投影;下文的正文具有权威性。
意图¶
CommandPaletteItem 将一个命令结果显示为一个选项。CommandPalette 上下文提供复合状态和键盘所有权;该条目拥有其选项语义、视觉状态、指针激活、原生透传边界,以及独立滚动行为。
兼容性与迁移¶
- 已发布默认值保留:
yes - 兼容性类别:记录已发布行为;无公共变更
- 受控/非受控行为:显式条目状态仍然优先于上下文状态,然后是现有的 false 默认值
- 迁移决策:无;OQ1 持有对独立键盘契约的任何更改。条目
onSelect仅报告指针激活;键盘选择通过根的onValueChange报告。
消费者迁移说明属于消费者文档和发布说明。
当前状态影响¶
- 独立选项没有键盘模型。 在 CommandPalette 之外,条目暴露
role=option和指针激活,但没有所属的 listbox 键盘模型,因此键盘用户无法到达或激活它;WAI-ARIA 1.2 选项属于一个拥有其键盘交互的复合组件(AR5、OQ1)。 - 选中样式掩盖键盘高亮。 当一个条目同时被高亮和选中时,选中的背景会遮住高亮背景,因此该条目上的键盘位置不可见(AV2、OQ2)。
所有权边界¶
拥有
- 选项根节点、条目值标记、选中和禁用的 ARIA 状态,以及
command-palette-item主题目标。 - 高亮和选中视觉状态的优先级为:显式 → CommandPalette 上下文 → false。
- 指针激活顺序、禁用抑制,以及上下文选中/关闭。
- 独立高亮条目的滚动行为,以及内联预览的初始滚动抑制。
不拥有 / 非目标
- CommandPalette 的 listbox、查询字段的活动后代、箭头键导航、Enter 处理、搜索结果,或根
onValueChange回调。 - 分组、列表布局,或调用方提供的非交互条目内容。
- 独立复合 listbox 键盘模型;其方向仍由 OQ1 决定。
- 交互子元素。按钮和链接是兄弟操作或独立命令,而不是选项内部的内容。
公共概念¶
| 概念 | 封闭值或状态 | 含义 | 可用性 | 默认值 | 所有者 | 稳定性 | 无效值行为 |
|---|---|---|---|---|---|---|---|
| 高亮 | 显式;上下文索引;false | 激活的键盘结果,已绘制但未选中。 | 所有使用场景 | false | component:CommandPaletteItem |
稳定 | 未知的上下文值会使所有条目都未高亮。 |
| 选中 | 显式;上下文值;false | 所选值通过 aria-selected 暴露。 |
所有使用场景 | false | component:CommandPaletteItem |
稳定 | 重复值会不明确地解析;值保持唯一。 |
| 可用性 | 启用;禁用 | 指针激活是否可用。 | 所有使用场景 | 启用 | component:CommandPaletteItem |
稳定 | 禁用会抑制消费者和组件的回调。 |
| 条目身份 | 上下文生成的 id;独立调用方提供的 id | 由活动后代或调用方使用的 DOM 身份。 | 上下文或独立 | 无 | 组件或调用方 | 稳定 | 上下文身份仅对已注册的条目生效。 |
行为与布局契约¶
| ID | 不变量 | 依据 |
|---|---|---|
| FR1 | 原生 props 和 ref 到达选项根元素。option 角色、选中状态和禁用状态会取代调用方的对应设置:在 CommandPalette 内部,因为复合语义由组件拥有并取代透传,正如 component:CommandPaletteInput 的 AR3 所记录;在独立使用时,则由本记录自身的规则决定。CommandPalette 上下文拥有已注册项目的 id 与值标记;独立调用方的 id 保持不变。 |
当前源码与测试;architecture:public-component-api |
| FR2 | 指针激活先运行消费者的 onClick,若被阻止则停止;否则调用项目的 onSelect,随后执行上下文选中和关闭。禁用项目不运行上述任何路径。 |
当前源码与测试 |
| FR3 | 显式传入的 isHighlighted 和 isSelected 优先于从上下文推导的值,随后才回退为 false。高亮仅绘制激活状态;只有选中状态驱动 aria-selected。 |
当前源码、测试与文档 |
| FR4 | 上下文负责已高亮项目的滚动。在上下文之外,已高亮项目会就近滚动;但内联 Dialog 中初始即为高亮的项目不会滚动。 | 当前源码与测试 |
| FR5 | 子元素提供选项的标签和辅助性呈现,且不得包含嵌套的交互式后代。 | 选项语义与 spec:AST-020/FR1,FR2 |
允许的变体¶
- AV1 — 内容。 标签、图标、描述和快捷键提示可以变化,但须保持非交互性。
- AV2 — 视觉状态。 高亮、选中和禁用状态可以独立出现,也可以同时出现。当两者同时为真时,当前的选中绘制会遮盖高亮绘制;OQ2 提供了可见状态的补救措施。
- AV3 — 布局。 消费者的
xstyle、class 和 style 可以调整唯一的根元素,但不得替换其选项语义。
代表性状态¶
| 状态 | 必需的不变量 | 允许的变体 |
|---|---|---|
| 独立可用 | 调用方 id 与原生 props 保持不变;指针激活在本地报告。 | 内容与视觉状态。 |
| 独立禁用 | aria-disabled 为 true,且不触发任何点击回调。 |
内容。 |
| 上下文高亮 | 上下文项目 id 与 active descendant 匹配,且高亮不是选中。 | 项目索引与内容。 |
| 上下文选中 | 匹配的值暴露 aria-selected=true。 |
高亮可以相同,也可以不同。 |
| 消费者取消 | 消费者点击会运行;本地与上下文的选中/关闭不会运行。 | 消费者副作用。 |
| 内联初始状态 | 初始的独立高亮不会滚动周围的预览。 | 选中的值与内容。 |
转换与优先级顺序¶
- ORD1 — 视觉状态。 显式项目 prop → CommandPalette 上下文 → false。
- ORD2 — 指针激活。 禁用守卫 → 消费者点击 → 阻止检查 → 项目
onSelect→ 上下文选中 → 上下文关闭。 - ORD3 — 身份。 已注册的上下文 id → 独立调用方 id → 无。
性能与资源¶
- PR1 — 查找。 上下文匹配仍受当前扁平结果列表的约束,且不执行任何监听器、观察者或逐项注册表工作。
- PR2 — 滚动所有权。 只有一个所有者负责滚动已高亮的上下文项目;独立项目在未高亮时不安排任何工作。
可访问性契约¶
- AR1 — 选项语义。 根元素暴露
role=option(FR1);其内容或调用方标签提供可访问名称,aria-selected报告的是所选值而非视觉高亮。 - AR2 — 复合容器所有权。 在 CommandPalette 内部,查询字段保持焦点并指向上下文生成的条目 id;CommandPalette 在其采用的 listbox/combobox 模型下拥有方向键导航和 Enter 选择。
- AR3 — 禁用状态。 禁用条目暴露
aria-disabled=true,抑制所有指针激活回调,并省略交互覆盖层。 - AR4 — 内容。 条目子内容不得包含嵌套的按钮、链接或其他交互式后代,否则当
option角色使其后代变为呈现性内容时这些语义将丢失,遵循 WAI-ARIA 1.2 和spec:AST-020/FR1,FR2。 - AR5 — 独立使用时的缺口。 独立选项没有所属的复合键盘模型(当前状态影响;OQ1)。
设计关系¶
| 解剖结构 | 设计需求 | 表征权威 | 层级角色 | 组件契约 |
|---|---|---|---|---|
| Item | 在一个根元素上呈现启用、高亮、选中、禁用和按压状态。当两者同时适用时,选中状态掩盖高亮状态(OQ2)。 | 当前来源和公开文档 | 突出 | FR1–FR4, AR1–AR3 |
| Content | 提供选项名称和非交互式辅助呈现。 | 产品调用点 | 辅助 | FR5, AR1, AR4 |
家族与系统关系¶
component:CommandPalette拥有复合搜索、listbox、活动后代、键盘和关闭编排;本组件将单个选项绑定到它。architecture:interaction-modality拥有共享的指针和键盘行为。architecture:public-component-api拥有原生透传和已发布 API 兼容性。architecture:component-theming-surface拥有聚合的 Item 解剖结构映射和稳定的command-palette-item目标。spec:AST-017针对静默更改已发布契约的行为持有 OQ1。spec:AST-020提供可访问性证据和采用模式的边界。- WAI-ARIA 1.2 的 option 语义使后代变为呈现性内容,因此交互式控件不应位于此选项根元素内部。
验证映射¶
| 契约 | 验证 | 代表性状态 | 变更或失败预期 | 审计章节 |
|---|---|---|---|---|
| FR1, FR3, AR1–AR2 | CommandPaletteItem.test.tsx, CommandPalette.test.tsx |
独立;上下文高亮/选中 | 丢失 id/ref/原生属性、可被覆盖的 role/state,或将高亮作为选中会导致聚焦 DOM 断言失败。 | audit:CommandPaletteItem/a11y |
| FR2, AR3 | CommandPaletteItem.test.tsx |
启用;禁用;消费者取消;上下文 | 消费者激活被禁用、取消被忽略、缺少本地报告、选择或关闭会导致测试失败。 | audit:CommandPaletteItem/behavior |
| FR4, PR2 | CommandPaletteItem.test.tsx, CommandPalette.test.tsx |
独立;内联初始;高亮变化 | 最近的滚动容器丢失、重复的上下文滚动,或初始内联滚动失败会导致 Effect 断言失败。 | audit:CommandPaletteItem/behavior |
| Theme/RTL | 聚焦类断言,themingTargets.test.ts,RTL 验证不适用 |
所有视觉状态 | 目标丢失会导致清单/DOM 测试失败;任何新的方向性行为都需要非空的 RTL 维度。 | audit:CommandPaletteItem/theming |
| FR5, AR4 | 源码审查 | 条目子内容 | 缺口:如果条目子内容包含嵌套的交互式后代,则没有检查会失败。 | audit:CommandPaletteItem/accessibility |
| AR5 | 源码审查 | 独立条目 | 缺口:不存在可测试的独立键盘模型(OQ1)。 | audit:CommandPaletteItem/accessibility |
| PR1 | 源码审查 | 在 CommandPalette 内部 | 缺口:如果上下文匹配添加监听器、观察器或逐条注册工作,则没有自动化检查会失败。 | audit:CommandPaletteItem/behavior |
从源码读取,尚无聚焦测试:
- FR5, AR4:子内容不携带交互式后代。
- AR3:禁用条目上省略的交互覆盖层。
决策日志¶
未记录组件级决策。
开放问题¶
- OQ1 — CommandPaletteItem 应暴露什么样的独立键盘契约?
(
human-api)当前的独立使用暴露了一个选项和指针激活,但没有所属的 listbox 键盘模型。需要决定:是否由公共复合容器提供该模型,条目是否应获得不同的独立角色和交互契约,还是独立激活应进入迁移路径。 - OQ2 — 当条目同时被选中时,键盘高亮应如何保持可见?
(
human-design)当前选中的背景绘制会跟随并掩盖高亮背景;任何外观修复都需要容器所有者的指示。
内容边界¶
本文件不重复使用者示例、实现步骤、CommandPalette 的聚合搜索/列表行为或共享系统规则。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx