• Vant React

Checkbox 复选框

介绍

在一组备选项中进行多选。

引入

import { Checkbox } from "@taroify/core"

代码演示

基础用法

通过 checked 绑定复选框的勾选状态。

<Checkbox>复选框</Checkbox>

禁用状态

通过设置 disabled 属性可以禁用复选框。

<Checkbox disabled checked={false}>复选框</Checkbox>
<Checkbox disabled checked>复选框</Checkbox>

自定义形状

将 shape 属性设置为 square，复选框的形状会变成方形。

<Checkbox shape="square">自定义形状</Checkbox>

自定义颜色

通过 css 设置选中状态的图标颜色。

<Checkbox className="custom-color">
  自定义颜色
</Checkbox>
.custom-color {
  --checkbox-checked-icon-border-color: #ee0a24;
  --checkbox-checked-icon-background-color: #ee0a24;
}

自定义大小

通过 size 属性可以自定义图标的大小。

<Checkbox size={24}>自定义大小</Checkbox>

自定义图标

通过 icon 属性自定义图标。

function CheckboxWithCustomIcon() {
  const [value, setValue] = useState(false)

  return (
    <Checkbox
      icon={
        <Image
          src={`https://img.yzcdn.cn/vant/user-${value ? "active" : "inactive"}.png`}
          style={{
            width: "25px",
            height: "20px",
          }}
        />
      }
      checked={value}
      onChange={setValue}
    >
      自定义图标
    </Checkbox>
  )
}

复选框组

复选框可以与复选框组一起使用，复选框组通过 value 数组绑定复选框的勾选状态。

<Checkbox.Group>
  <Checkbox name="a">复选框 a</Checkbox>
  <Checkbox name="b">复选框 b</Checkbox>
</Checkbox.Group>

水平排列

将 direction 属性设置为 horizontal 后，复选框组会变成水平排列。

<Checkbox.Group direction="horizontal">
  <Checkbox name="a">复选框 a</Checkbox>
  <Checkbox name="b">复选框 b</Checkbox>
</Checkbox.Group>

限制最大可选数

通过 max 属性可以限制复选框组的最大可选数。

<Checkbox.Group max={2}>
  <Checkbox name="a">复选框 a</Checkbox>
  <Checkbox name="b">复选框 b</Checkbox>
  <Checkbox name="c">复选框 c</Checkbox>
</Checkbox.Group>

搭配单元格组件使用

此时你需要再引入 Cell 和 Cell.Group 组件，并通过 Checkbox 实例上的 toggle 方法触发切换。

<Checkbox.Group max={2}>
  <Cell.Group clickable>
    <Cell title="复选框 a">
      <Checkbox name="a" />
    </Cell>
    <Cell title="复选框 b">
      <Checkbox name="b" />
    </Cell>
  </Cell.Group>
</Checkbox.Group>

API

Checkbox Props

参数 说明 类型 默认值
defaultChecked 默认是否为选中状态 boolean false
checked 是否为选中状态 boolean false
name 标识符 any -
shape 形状，可选值为 square string round
disabled 是否禁用复选框 boolean false
size 图标大小，默认单位为 px number | string 20px

CheckboxGroup Props

参数 说明 类型 默认值
defaultValue 默认所有选中项的标识符 any[] -
value 所有选中项的标识符 any[] -
disabled 是否禁用所有复选框 boolean false
max 最大可选数，0 为无限制 number | string 0
direction 排列方向，可选值为 horizontal string vertical
size 所有复选框的图标大小，默认单位为 px number | string 20px

Checkbox Events

事件名 说明 回调参数
onChange 当绑定值变化时触发的事件 checked: boolean

CheckboxGroup Events

事件名 说明 回调参数
onChange 当绑定值变化时触发的事件 names: any[]

主题定制

样式变量

组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。

名称 默认值 描述
—checkbox-size 20px * $hd -
—checkbox-font-size var(—font-size-lg) -
—checkbox-border-color var(—gray-5) -
—checkbox-transition-duration var(—animation-duration-fast) -
—checkbox-gap var(—padding-sm) -
—checkbox-label-margin var(—padding-xs) -
—checkbox-label-color var(—text-color) -
—checkbox-label-line-height var(—checkbox-size) -
—checkbox-disabled-label-color var(—gray-5) -
—checkbox-icon-font-size var(—checkbox-size) -
—checkbox-checked-icon-color var(—white) -
—checkbox-checked-icon-border-color var(—primary-color) -
—checkbox-checked-icon-background-color var(—primary-color) -
—checkbox-disabled-icon-color var(—gray-5) -
—checkbox-disabled-icon-border-color var(—gray-5) -
—checkbox-disabled-icon-background-color var(—border-color) -