Reka UI logoReka
backdrop
示例
组件

复选框

一种允许用户在选中和未选中之间切换的控件。

特性

  • 支持不确定状态。
  • 完整的键盘导航。
  • 可受控或不受控。

安装

从命令行安装此组件。

sh
$ npm add reka-ui

结构

导入所有部分并将其组合。

vue
<script setup>
import { CheckboxGroupRoot, CheckboxIndicator, CheckboxRoot } from 'reka-ui'
</script>

<template>
  <CheckboxRoot>
    <CheckboxIndicator />
  </CheckboxRoot>

  <!-- or with array support -->
  <CheckboxGroupRoot>
    <CheckboxRoot>
      <CheckboxIndicator />
    </CheckboxRoot>
  </CheckboxGroupRoot>
</template>

API 参考

根

包含复选框的所有部分。在 `form` 中使用时，还会渲染一个 `input` 元素，以确保事件正确传播。

属性默认类型
as
'button'
AsTag | 组件

此组件应渲染为的元素或组件。可通过 asChild 覆盖。

asChild
布尔值

更改默认渲染元素为作为子项传递的元素，合并它们的属性和行为。

阅读我们的 组合指南了解更多详情。

defaultValue
boolean | 'indeterminate'

复选框初次渲染时的值。在您不需要控制其值时使用。

disabled
布尔值

当 `true` 时，阻止用户与复选框交互

id
string

元素的 ID

modelValue
boolean | 'indeterminate' | null

复选框的受控值。可与 v-model 绑定。

name
string

字段的名称。随其所属的表单一起作为名称/值对提交。

required
布尔值

当为 true 时，表示用户必须在所属表单提交前设置值。

value
'on'
AcceptableValue

与 `name` 一起提交时作为数据给出的值。

事件触发载荷
update:modelValue
[value: boolean | 'indeterminate']

当复选框的值改变时调用的事件处理程序。

插槽（默认）载荷
modelValue
假 | 真 | '不确定'

当前值

state
CheckedState

当前状态

数据属性值
[data-state]"已选中" | "未选中" | "不确定"
[data-disabled]禁用时存在

指示器

当复选框处于选中或不确定状态时渲染。您可以直接设置此元素的样式，也可以将其用作放置图标的包装器，或者两者兼而有之。

提示
使用 Presence 组件构建 - 支持任何 动画技术，同时保持对 Presence 发出事件的访问。
属性默认类型
as
'span'
AsTag | 组件

此组件应渲染为的元素或组件。可通过 asChild 覆盖。

asChild
布尔值

更改默认渲染元素为作为子项传递的元素，合并它们的属性和行为。

阅读我们的 组合指南了解更多详情。

forceMount
布尔值

当需要更多控制时，用于强制挂载。在与 Vue 动画库控制动画时很有用。

数据属性值
[data-state]"已选中" | "未选中" | "不确定"
[data-disabled]禁用时存在

分组根

包裹 `CheckboxRoot` 以支持 `modelValue` 数组。

属性默认类型
as
'div'
AsTag | 组件

此组件应渲染为的元素或组件。可通过 asChild 覆盖。

asChild
布尔值

更改默认渲染元素为作为子项传递的元素，合并它们的属性和行为。

阅读我们的 组合指南了解更多详情。

defaultValue
AcceptableValue[]

复选框初次渲染时的值。在您不需要控制其值时使用。

dir
'ltr' | 'rtl'

项目之间导航的方向。

disabled
布尔值

当 `true` 时，阻止用户与复选框组交互

loop
布尔值

键盘导航是否应循环。

modelValue
AcceptableValue[]

复选框的受控值。可与 v-model 绑定。

name
string

字段的名称。随其所属的表单一起作为名称/值对提交。

orientation
'vertical' | 'horizontal'

分组的方向。主要用于相应地进行箭头导航（左 & 右 vs. 上 & 下）。

required
布尔值

当为 true 时，表示用户必须在所属表单提交前设置值。

rovingFocus
true
布尔值

当 `false` 时，禁用使用箭头键在项目间导航。

事件触发载荷
update:modelValue
[value: AcceptableValue[]]

当复选框的值改变时调用的事件处理程序。

示例

不确定状态

您可以通过控制其状态将复选框设置为不确定状态。

vue
<script setup>
import { Icon } from '@iconify/vue'
import { CheckboxIndicator, CheckboxRoot } from 'reka-ui'

const checked = ref('indeterminate')
</script>

<template>
  <CheckboxRoot v-model="checked">
    <CheckboxIndicator>
      <Icon
        v-if="checked === 'indeterminate'"
        icon="radix-icons:divider-horizontal"
      />
      <Icon
        v-if="checked"
        icon="radix-icons:check"
      />
    </CheckboxIndicator>
  </CheckboxRoot>

  <button
    type="button"
    @click="() => (checked === 'indeterminate' ? (checked = false) : (checked = 'indeterminate'))"
  >
    Toggle indeterminate
  </button>
</template>

可访问性

遵循 三态复选框 WAI-ARIA 设计模式。

键盘交互

键描述
空格键
选中/取消选中复选框