跳转至

DropdownMenuCheckboxItem 组件契约

契约一览

领域 契约
公共契约 指针菜单中的一行,用于切换一个独立的布尔值:label、description、icon、endContent、受控的 value 与 onChange、isDisabled、hasCloseOnSelect(默认 false)、根输入以及一个 ref。
行为 该行是一个 menuitemcheckbox,其 aria-checked 等于 value;启用状态下的激活会报告 !value,除非被要求关闭,否则保持菜单打开;禁用行是惰性的。
对最终用户的影响 用户可以在不因每次变更而关闭菜单的情况下切换选项,屏幕阅读器用户每行听到一个复选框。
对构建者的影响 构建者拥有该值;该行将自身的激活与悬停聚焦逻辑与构建者的点击和指针移动处理器组合在一起。
兼容性/就绪状态 记录已发布行为;无 API 变更;禁用行获得 tabindex="-1"(FR3)。Enter 保持菜单打开的行为列入当前状态影响(OQ1)之下。
审查检查项 拒绝嵌套的被播报复选框、默认关闭的行、被丢弃的调用方处理器,或禁用状态下的激活。
管理规则 spec:AST-020 FR15;architecture:public-component-api INV5–INV8;architecture:interaction-modality。

此表是对审查的投影;以下正文具有权威性。

意图

DropdownMenuCheckboxItem 在 DropdownMenu 的指针呈现中渲染一个复合模式行,用于切换一个独立的布尔值。DropdownMenu 拥有焦点移动、键入搜索、键盘点击合成和关闭生命周期。

兼容性与迁移

  • 已发布的默认值保留:是(hasCloseOnSelect=false)。
  • 兼容性类别:记录已发布行为;无公共属性或导出变更;禁用行获得 tabindex="-1"(FR3)。
  • 受控/非受控行为:受控;value 由调用方拥有。
  • 迁移决策:无。

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

所有权边界

拥有

  • 一个 role="menuitemcheckbox" 根元素、其 aria-checked、标签、描述、图标、结束内容、禁用状态、ref、受支持的主机输入以及样式输入。
  • 激活:报告 !value、关闭策略,以及组合调用方的点击和指针移动处理器。
  • 装饰性复选框标记以及该行的 dropdown-menu-item 目标。

不拥有 / 非目标

  • 焦点进入、漫游焦点、键入搜索以及 Enter/Space 点击合成——由 component:DropdownMenu 拥有。
  • 复选框视觉装饰(chrome)——委托给 component:Indicator。
  • 键盘如何到达禁用行——component:DropdownMenu FR17。

公共概念

概念 封闭值或状态 含义 可用性 默认值 所有者 稳定性 无效值行为
选中状态 true, false 该行显示并切换的布尔值。 每一行 必需 调用方 稳定 由公共类型要求。
关闭策略 关闭;保持打开 启用状态下的切换是否关闭菜单。 每一个启用行 保持打开 组件 稳定 省略时保持菜单打开。
可用性 启用;禁用 该行是否可以激活。 每一行 启用 组件 稳定 禁用会阻止激活。

行为与布局契约

ID 不变量 依据
FR1 该行渲染一个 role="menuitemcheckbox" 元素,其 aria-checked 等于 value;复选框标记是装饰性的(aria-hidden),因此该行是唯一被播报的控件。 spec:AST-020 FR15;当前源代码和测试
FR2 通过指针或父级合成的 Enter/Space 点击触发的启用激活,会调用 onChange(!value),然后在设置了 hasCloseOnSelect 时关闭菜单,再调用调用方的 onClick;没有 hasCloseOnSelect 时菜单保持打开。APG 菜单模式的 Enter 会关闭菜单,而 spec:AST-020 FR15 要求本记录指明其未采用的任何必需部分。实现缺口:Enter 默认让菜单保持打开,且未指明任何例外(OQ1)。 spec:AST-020 FR15;architecture:public-component-api INV7;当前测试
FR3 禁用的行暴露 aria-disabled="true",并像启用行一样带有 tabindex="-1",以便父级的键盘模型能触达它(component:DropdownMenu FR17);在任何激活时,既不调用 onChange,也不调用调用方的激活处理函数,并且不关闭菜单。 当前源代码与测试
FR4 Ref、受支持的主机属性与处理函数、className、style 和 xstyle 到达或在行根节点上组合;调用方的 onPointerMove 与行的悬停焦点组合。 architecture:public-component-api INV5–INV8;当前测试
FR5 标记是共享的复选框 Indicator,在小型菜单中为 sm;该行带有与菜单尺寸对应的 dropdown-menu-item 目标。 architecture:component-theming-surface;当前源代码与测试
FR6 该行不添加自己的按键处理函数或 Tab 停靠点:每一行,包括禁用的行,都使用 tabindex="-1" 以配合父级的巡游焦点,并且父级的键盘可以触达禁用的行(component:DropdownMenu FR17)。 architecture:interaction-modality;父级测试

允许的变化

  • AV1 — 内容。 标签、描述、图标和尾部内容均为调用方内容。
  • AV2 — 主题绘制。 主题可以重新设计行与标记目标的样式。

代表性状态

状态 必需不变量 允许的变化
未选中 aria-checked="false";标记为空。 内容。
已选中 aria-checked="true";标记为选中。 内容。
选择时关闭 启用的开关会关闭菜单。 —
禁用 aria-disabled="true";无激活。 内容保持可见。

转换与优先级顺序

  • ORD1 — 激活。 禁用守卫 → onChange(!value) → 在 hasCloseOnSelect 时关闭 → 调用方 onClick。

性能与资源

  • PR1 — 共享按下监听器。 该行共享按下控制器的 window 与 document 监听器;它不会添加任何逐行监听器、观察器、定时器或请求。

无障碍契约

  • AR1 — 单个复选框控件。 该行拥有 menuitemcheckbox、其可访问名称、选中状态、焦点和激活行为;标记仅作装饰。
  • AR2 — 禁用状态。 禁用的行是惰性的。
  • AR3 — 焦点可见性。 键盘焦点在行内部绘制共享焦点环,并按焦点环自身宽度内缩,适用于所有颜色模式,包括强制颜色模式;指针输入后,该行仅显示叠加色调(architecture:interaction-modality INV1, INV3)。共享的行处理方式是 component:DropdownMenuItem FR8。

设计关系

构成或状态 设计要求 呈现权威 层级角色 组件契约
行 一个全宽的开关行。 当前源代码 突出 FR1, FR5
标记 显示选中状态。 component:Indicator 辅助 FR1, FR5

共享的 DropdownMenu.doc.mjs 结构与 component:DropdownMenu 主题结构均映射了行和复选框指示器,因此此记录不携带结构-主题映射。

家族与系统关系

  • component:DropdownMenu 拥有键盘模型和关闭生命周期。
  • component:Indicator 拥有复选框外观。
  • architecture:public-component-api 拥有根组合和处理程序顺序。

验证映射

契约 验证 代表性状态 变更或失败预期 审计章节
FR1, AR1 DropdownMenuSelectable.test.tsx “保持复选框指示器为装饰性(行是唯一被宣告的控件)”;“ref 可到达 menuitemcheckbox 元素” 已选中和未选中 宣告的标记或不是 menuitemcheckbox 的行将失败。 audit:DropdownMenuCheckboxItem/semantics
FR2, ORD1 DropdownMenuSelectable.test.tsx “在点击时以切换后的值调用 onChange”、“将调用者的点击处理程序与选中状态变更组合”、“在键盘激活时组合调用者的点击处理程序”、“仅在请求时于成功切换后关闭”;DropdownMenu.test.tsx “使用 Enter 激活聚焦的 menuitemradio,并使用 Space 激活 menuitemcheckbox” 指针和键盘;关闭开启与关闭 错误的值、丢失的调用者 onClick,或未经选择加入即关闭将失败。证据缺口:没有测试断言 onChange、关闭、onClick 的顺序。 audit:DropdownMenuCheckboxItem/behavior
FR3, AR2 DropdownMenuSelectable.test.tsx “禁用时不调用使用方的激活处理程序”和“禁用时不进行切换” 已禁用 禁用状态下进行切换、关闭或调用使用方处理程序将失败。证据缺口:没有测试断言禁用行的 tabindex="-1"。 audit:DropdownMenuCheckboxItem/behavior
FR4 DropdownMenuSelectable.test.tsx “将调用者的指针移动处理程序与菜单悬停焦点组合”,以及“ref 可到达 menuitemcheckbox 元素” Ref;指针移动 丢失的 ref 或处理程序将失败。证据缺口:没有测试断言行上的宿主属性、className、style 或 xstyle。 audit:DropdownMenuCheckboxItem/api
FR5 DropdownMenuSelectable.test.tsx “将小菜单映射到共享的小复选框标记” 小菜单 忽略菜单尺寸的标记将失败。证据缺口:没有测试断言此行上的 dropdown-menu-item 目标。 audit:DropdownMenuCheckboxItem/theming
FR6 DropdownMenu.test.tsx “箭头导航可到达使用方渲染的 menuitemradio 和 menuitemcheckbox 项目”以及禁用行的键盘用例(component:DropdownMenu FR17) 已启用和已禁用的行 箭头遗漏的行、跳过的禁用行,或切换或关闭菜单的禁用行将失败。 audit:DropdownMenuCheckboxItem/accessibility
AR3, PR1 DropdownMenuForcedColors.test.tsx(行的 :focus-visible 环和令牌内边距);DropdownMenuAudit.a11y.chromium.spec.ts 强制颜色帧。证据缺口:没有测试断言绑定的监听器 — — audit:DropdownMenuCheckboxItem/behavior

当前状态影响

  • Enter 保持菜单打开(FR2)。 在复选框行上按 Enter 会切换该行并默认保持菜单打开,这与 spec:AST-020 FR15 所采用的 Menu 模式 Enter 行为相悖,且没有命名例外(OQ1)。

决策日志

没有组件局部的决策。

开放问题

  • OQ1 — 复选框行是否作为 Menu 模式的命名例外,在按 Enter 时保持菜单打开,还是像其他行一样关闭?(human-api) 保持打开可以让使用者在一次访问中切换多个选项;关闭则符合模式的 Enter 行为,也与其他行类型一致。

内容边界

本文件不重复使用方 prop 表格/示例、当前审计结果、实现步骤或父级契约。它链接到这些内容的归属方。

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