Lzh on GitHub

Checkbox

允许用户在选中和未选中之间切换的控件。
<script setup lang="ts">
import { Icon } from '@iconify/vue'
import { CheckboxIndicator, CheckboxRoot } from 'reka-ui'
import { ref } from 'vue'

const checkboxOne = ref(true)
</script>

<template>
  <div class="flex flex-col gap-2.5">
    <label class="flex flex-row gap-4 items-center [&>.checkbox]:hover:bg-neutral-100">
      <CheckboxRoot
        v-model="checkboxOne"
        class="hover:bg-stone-50 flex h-5 w-5 appearance-none items-center justify-center rounded-md bg-white shadow-sm border outline-none focus-within:shadow-[0_0_0_2px_black]"
      >
        <CheckboxIndicator class="bg-white h-full w-full rounded flex items-center justify-center">
          <Icon
            icon="radix-icons:check"
            class="h-5 w-5 text-grass9"
          />
        </CheckboxIndicator>
      </CheckboxRoot>
      <span class="select-none text-stone-700 text-sm dark:text-white">Accept terms and conditions.</span>
    </label>
  </div>
</template>

特性

  • 支持 不确定(indeterminate) 状态。
  • 完整的键盘导航。
  • 可作为受控或非受控组件使用。

安装

从命令行安装组件：

$ npm add reka-ui

结构

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

<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 参考

Root

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

Prop默认值类型描述
as'button'AsTag | Component此组件应渲染为的元素或组件。可以通过 asChild 覆盖。
asChildboolean将默认渲染的元素更改为作为子元素传递的元素，合并它们的 prop 和行为。请参阅我们的组合指南了解更多详情。
defaultValueboolean | 'indeterminate'复选框初始渲染时的值。当您不需要控制其值时使用。
disabledboolean当为 true 时，阻止用户与复选框交互。
idstring元素的 ID。
modelValueboolean | 'indeterminate' | null复选框的受控值。可以通过 v-model 绑定。
namestring字段的名称。作为名称/值对的一部分与所属表单一起提交。
requiredboolean当为 true 时，表示用户必须设置值，然后才能提交所属表单。
value'on'AcceptableValue作为数据提交时随 name 提交的值。

事件负载

事件名称Payload描述
update:modelValue[value: boolean | 'indeterminate']复选框值更改时调用的事件处理程序。

默认插槽

插槽参数插槽参数类型描述
modelValuefalse | true | 'indeterminate'当前值
stateCheckedState当前状态

数据属性

数据属性值
[data-state]"checked" | "unchecked" | "indeterminate"
[data-disabled]禁用时存在。

Indicator

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

使用了 Presence 组件构建 - 支持任何动画技术同时保持对 Presence 发射事件的访问。
Prop默认值类型描述
as'span'AsTag | Component此组件应渲染为的元素或组件。可以通过 asChild 覆盖。
asChildboolean将默认渲染的元素更改为作为子元素传递的元素，合并它们的 prop 和行为。请参阅我们的组合指南了解更多详情。
forceMountboolean当需要更多控制时用于强制挂载。在与 Vue 动画库一起控制动画时很有用。

数据属性

数据属性值
[data-state]"checked" | "unchecked" | "indeterminate"
[data-disabled]禁用时存在。

Group Root

CheckboxRoot 的包装器，支持 modelValue 数组。

Prop默认值类型描述
as'div'AsTag | Component此组件应渲染为的元素或组件。可以通过 asChild 覆盖。
asChildboolean将默认渲染的元素更改为作为子元素传递的元素，合并它们的 prop 和行为。请参阅我们的组合指南了解更多详情。
defaultValueAcceptableValue[]复选框初始渲染时的值。当您不需要控制其值时使用。
dir'ltr' | 'rtl'项目之间的导航方向。
disabledboolean当为 true 时，阻止用户与复选框交互。
loopboolean键盘导航是否应循环。
modelValueAcceptableValue[]复选框的受控值。可以通过 v-model 绑定。
namestring字段的名称。作为名称/值对的一部分与所属表单一起提交。
orientation'vertical' | 'horizontal'组的方向。主要用于相应地进行箭头导航（左 & 右 vs. 上 & 下）。
requiredboolean当为 true 时，表示用户必须设置值，然后才能提交所属表单。
rovingFocustrueboolean当为 false 时，禁用使用箭头键在项目之间导航。

EmitPayload

事件名称Payload描述
update:modelValue[value: AcceptableValue[]]复选框值更改时调用的事件处理程序。

示例

不确定状态

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

<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'))"
  >
    切换不确定状态
  </button>
</template>

可访问性

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

键盘交互

按键描述
Space选中/取消选中复选框。