复选框

QCheckbox 组件是一个基础的用户输入元素，可以用来为用户提供一个开关选项。

用法

基础用法

自定义图标

v2.5+

标签

颜色定制

在下面示例的第二行中，使用了 keep-color 属性来保持复选框在未选中状态下也保留指定的颜色。

紧凑模式

强制暗色模式

尺寸

除了以下标准尺寸之外，您还可以通过 size 属性自定义尺寸（最后一个即为自定义尺寸的示例）。

不确定状态

在下面的示例中，点击第一个复选框后它会在 true/false 之间切换。而第二个复选框借助 toggle-indeterminate 属性，可以在三种状态之间切换（不确定/true/false）。您还可以通过 indeterminate-value 属性来指定不确定状态的值，否则不确定状态的值默认为 null。

切换顺序

默认情况下，QCheckbox 的切换顺序为：不确定 -> 选中 -> 未选中。不过，您可以通过 toggle-order 属性来更改这一行为。该属性决定了状态的切换顺序，可选值为 tf（默认）或 ft（t 代表 true/选中状态，f 代表 false/未选中状态）。

切换顺序如下：

• 如果 toggle-indeterminate 为 true：不确定 -> 第一个状态 -> 第二个状态 -> 不确定（循环往复）
• 否则（未启用 toggle-indeterminate）：不确定 -> 第一个状态 -> 第二个状态 -> 第一个状态 -> 第二个状态 -> …

数组 model 数据

自定义 model 值

配合 QOptionGroup 使用

配合 QItem 使用

在下面的示例中，我们渲染了一个 <label> 标签（注意 tag="label"），这样点击 QItem 时 QCheckbox 也会响应并切换选中状态。

禁用

原生表单提交

当使用带有 action 和 method 的原生表单时（例如在 Quasar 与 ASP.NET 控制器配合使用时），您需要为 QCheckbox 指定 name 属性，否则 formData 中将不会包含该字段。注意所有值都会被转换为字符串（这是浏览器的原生行为，因此不要使用 Object 类型的值）：

无障碍访问

v2.25+

QCheckbox 实现了 WAI-ARIA 复选框模式：它暴露 role="checkbox" 并通过三态 aria-checked（true、false 或不确定状态时的 mixed）反映状态。label 属性同时作为无障碍名称（aria-label）——使用插槽定义 label 时，名称从渲染内容中派生——禁用的复选框会暴露 aria-disabled="true"。你可能在 DOM 中注意到的原生 <input type="checkbox"> 仅用于原生表单提交和 <label> 的点击转发；它对辅助技术是隐藏的。

复选框是一个 Tab 焦点（参见 tabindex 属性），可通过 Enter 或 Space 进行切换。键盘聚焦时会显示可见的焦点环，而鼠标点击则刻意不显示，以免分散指针用户的注意力。