开发预览 更新于 2026-05-10

Checkbox 复选框

多选框 —— 3 种尺寸、indeterminate 半选状态,原生 input 语义保留。

基础用法

底层是真实的 <CfInput type="checkbox">,键盘 / 表单 / 屏幕阅读器全部直接可用。

背景
<script setup lang="ts">
import { ref } from 'vue';
import { CfCheckbox } from '@chufix-design/vue';

const agree = ref(false);
</script>

<template>
  <CfCheckbox v-model="agree">我同意服务协议</CfCheckbox>
</template>
import { useState } from 'react';
import { CfCheckbox } from '@chufix-design/react';

export default function Demo() {
const [agree, setAgree] = useState(false);
return (
  <CfCheckbox checked={agree} onChange={(e) => setAgree(e.target.checked)}>
    我同意服务协议
  </CfCheckbox>
);
}

尺寸与禁用

背景
<script setup lang="ts">
import { CfCheckbox } from '@chufix-design/vue';
</script>

<template>
  <div class="demo-row">
    <CfCheckbox size="sm" :model-value="true">sm 已选</CfCheckbox>
    <CfCheckbox size="md" :model-value="true">md 已选</CfCheckbox>
    <CfCheckbox size="lg" :model-value="true">lg 已选</CfCheckbox>
    <CfCheckbox disabled>禁用</CfCheckbox>
    <CfCheckbox disabled :model-value="true">禁用已选</CfCheckbox>
  </div>
</template>
<CfCheckbox size="sm" defaultChecked>sm 已选</CfCheckbox>
<CfCheckbox size="md" defaultChecked>md 已选</CfCheckbox>
<CfCheckbox size="lg" defaultChecked>lg 已选</CfCheckbox>
<CfCheckbox disabled>禁用</CfCheckbox>
<CfCheckbox disabled defaultChecked>禁用已选</CfCheckbox>

半选 indeterminate

indeterminate 是纯视觉状态,不影响实际的 checked 值。常见用法是父级 “全选” 在子项部分选中时显示。

背景
<script setup lang="ts">
import { computed, ref } from 'vue';
import { CfCheckbox } from '@chufix-design/vue';

const apple = ref(true);
const banana = ref(false);
const cherry = ref(false);

const count = computed(
  () => [apple.value, banana.value, cherry.value].filter(Boolean).length,
);
const all = computed({
  get: () => count.value === 3,
  set(v) {
    apple.value = v;
    banana.value = v;
    cherry.value = v;
  },
});
const indeterminate = computed(() => count.value > 0 && count.value < 3);
</script>

<template>
  <div class="demo-stack">
    <CfCheckbox v-model="all" :indeterminate="indeterminate">全选</CfCheckbox>
    <div class="demo-row" style="padding-left: 1.5rem;">
      <CfCheckbox v-model="apple">苹果</CfCheckbox>
      <CfCheckbox v-model="banana">香蕉</CfCheckbox>
      <CfCheckbox v-model="cherry">樱桃</CfCheckbox>
    </div>
  </div>
</template>
import { useState } from 'react';
import { CfCheckbox } from '@chufix-design/react';

export default function Demo() {
const [apple, setApple] = useState(true);
const [banana, setBanana] = useState(false);
const [cherry, setCherry] = useState(false);
const count = [apple, banana, cherry].filter(Boolean).length;

return (
  <>
    <CfCheckbox
      checked={count === 3}
      indeterminate={count > 0 && count < 3}
      onChange={(e) => {
        const v = e.target.checked;
        setApple(v); setBanana(v); setCherry(v);
      }}
    >全选</CfCheckbox>
    <CfCheckbox checked={apple} onChange={(e) => setApple(e.target.checked)}>苹果</CfCheckbox>
    <CfCheckbox checked={banana} onChange={(e) => setBanana(e.target.checked)}>香蕉</CfCheckbox>
    <CfCheckbox checked={cherry} onChange={(e) => setCherry(e.target.checked)}>樱桃</CfCheckbox>
  </>
);
}

事件与表单

change 除了返回 checked,也会给出 name / value / indeterminate 等 meta,方便做权限矩阵、批量选择和原生表单提交。

背景
mixed
切换权限后会显示 checked、name、value 与 indeterminate。
<script setup lang="ts">
import { computed, ref } from 'vue';
import { CfBadge, CfCheckbox, type CheckboxChangeMeta } from '@chufix-design/vue';

const read = ref(true);
const write = ref(false);
const deploy = ref(false);
const phase = ref('mixed');
const logs = ref(['切换权限后会显示 checked、name、value 与 indeterminate。']);

const selected = computed(() => [read.value, write.value, deploy.value].filter(Boolean).length);
const all = computed({
  get: () => selected.value === 3,
  set(next: boolean) {
    read.value = next;
    write.value = next;
    deploy.value = next;
  },
});
const indeterminate = computed(() => selected.value > 0 && selected.value < 3);

function record(name: string, checked: boolean, meta: CheckboxChangeMeta) {
  phase.value = meta.indeterminate ? 'mixed' : checked ? 'checked' : 'empty';
  logs.value = [
    `${name}: checked=${checked} / name=${meta.name ?? '-'} / value=${meta.value ?? '-'} / mixed=${meta.indeterminate}`,
    ...logs.value,
  ].slice(0, 5);
}
</script>

<template>
  <div class="checkbox-events">
    <CfCheckbox
      v-model="all"
      name="permissions"
      value="all"
      :indeterminate="indeterminate"
      @change="(checked, meta) => record('all', checked, meta)"
    >
      全部权限
    </CfCheckbox>
    <div class="checkbox-events__children">
      <CfCheckbox v-model="read" name="permissions" value="read" @change="(checked, meta) => record('read', checked, meta)">读取</CfCheckbox>
      <CfCheckbox v-model="write" name="permissions" value="write" @change="(checked, meta) => record('write', checked, meta)">写入</CfCheckbox>
      <CfCheckbox v-model="deploy" name="permissions" value="deploy" @change="(checked, meta) => record('deploy', checked, meta)">发布</CfCheckbox>
    </div>
    <div class="checkbox-events__status">
      <CfBadge tone="info" :content="phase" />
      <div class="checkbox-events__log" aria-live="polite">
        <code v-for="entry in logs" :key="entry">{{ entry }}</code>
      </div>
    </div>
  </div>
</template>

<style scoped>
.checkbox-events {
  display: grid;
  gap: 12px;
  width: min(100%, 560px);
}

.checkbox-events__children {
  display: flex;
  flex-wrap: wrap;
  gap: 12px;
  padding-left: 24px;
}

.checkbox-events__status {
  display: flex;
  align-items: flex-start;
  gap: 10px;
}

.checkbox-events__log {
  display: grid;
  gap: 4px;
  min-width: 0;
}

.checkbox-events__log code {
  white-space: normal;
}
</style>
<CfCheckbox
checked={checked}
name="permissions"
value="read"
indeterminate={partial}
onCheckedChange={(checked, meta) => console.log(checked, meta)}
onChange={(event) => setChecked(event.target.checked)}
>
读取
</CfCheckbox>

API

Prop类型默认值说明
size'sm' | 'md' | 'lg''md'整体尺寸
disabledbooleanfalse禁用
indeterminatebooleanfalse半选状态(视觉态,不影响 checked)
namestring原生 input name
valuestring | number原生 input value

Events

Vue 事件React 回调payload说明
changeonCheckedChange(checked, { event, checked, indeterminate, value, name })选中状态变化
focus / bluronFocus / onBlurFocusEvent原生焦点事件

反馈与讨论

Checkbox 复选框 的讨论

0
0 / 600
一键发送
正在加载评论...