跳转至

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