Checkbox

Checkbox 适合布尔值字段，Checkbox.Group 适合多选数组字段，整体延续 dataSource + option slot + readPretty 这套现有 Vant 封装习惯。

提示

本组件的封装的dataSource，统一使用 { label, value } 格式的对象数组

单个复选框

vue

<script setup lang="ts">
import { createForm } from '@silver-formily/core'
import { Checkbox, Form, FormButtonGroup, Submit } from '@silver-formily/vant'
import { Field } from '@silver-formily/vue'
import { showDemoResult } from '../shared'

const form = createForm({
  values: {
    agreement: true,
    subscribe: false,
  },
})

async function handleSubmit(values: typeof form.values) {
  await showDemoResult(values)
}
</script>

<template>
  <Form :form="form">
    <div class="checkbox-stack">
      <Field name="agreement" :component="[Checkbox]">
        我已阅读并同意《服务协议》
      </Field>

      <Field
        name="subscribe"
        :component="[Checkbox, { shape: 'square' }]"
      >
        接收新品上架与活动提醒
      </Field>
    </div>

    <FormButtonGroup>
      <Submit @submit="handleSubmit">
        查看结果
      </Submit>
    </FormButtonGroup>
  </Form>
</template>

<style scoped>
.checkbox-stack {
  display: grid;
  gap: 14px;
  padding: 4px 16px 0;
}
</style>

基础多选

vue

<script setup lang="ts">
import { createForm } from '@silver-formily/core'
import { Checkbox, Form, FormButtonGroup, FormItem, Submit } from '@silver-formily/vant'
import { Field } from '@silver-formily/vue'
import { showDemoResult } from '../shared'
import { featureOptions } from './shared'

const form = createForm({
  values: {
    features: ['photo', 'location'],
  },
})

async function handleSubmit(values: typeof form.values) {
  await showDemoResult(values)
}
</script>

<template>
  <Form :form="form">
    <Field
      name="features"
      title="采集能力"
      :decorator="[FormItem, { labelAlign: 'top' }]"
      :component="[Checkbox.Group]"
      :data-source="featureOptions"
    />

    <FormButtonGroup>
      <Submit @submit="handleSubmit">
        查看结果
      </Submit>
    </FormButtonGroup>
  </Form>
</template>

排列方式与最多选择数量

vue

<script setup lang="ts">
import { createForm } from '@silver-formily/core'
import { Checkbox, FormItem } from '@silver-formily/vant'
import { Field, FormProvider } from '@silver-formily/vue'
import { channelOptions } from './shared'

const form = createForm({
  values: {
    channels: ['sms'],
  },
})
</script>

<template>
  <FormProvider :form="form">
    <div class="demo-panel">
      <div class="checkbox-tip">
        最多选择两种提醒方式，适合移动端设置页里比较常见的“偏好开关”场景。
      </div>

      <Field
        name="channels"
        title="提醒方式"
        :decorator="[FormItem, { labelAlign: 'top' }]"
        :component="[Checkbox.Group, { direction: 'horizontal', max: 2, shape: 'square' }]"
        :data-source="channelOptions"
      />
    </div>
  </FormProvider>
</template>

<style scoped>
.checkbox-tip {
  margin-bottom: 12px;
  color: var(--van-text-color-2);
  font-size: 12px;
  line-height: 1.6;
}
</style>

搭配单元格组件使用

vue

<script setup lang="ts">
import { createForm } from '@silver-formily/core'
import { Checkbox, Form, FormButtonGroup, Submit } from '@silver-formily/vant'
import { Field } from '@silver-formily/vue'
import { Cell, CellGroup, Tag } from 'vant'
import { showDemoResult } from '../shared'
import { serviceOptions } from './shared'

const form = createForm({
  values: {
    services: ['install'],
  },
})

function toggleService(value: string) {
  const currentValues = Array.isArray(form.values.services)
    ? [...form.values.services]
    : []
  const nextValues = currentValues.includes(value)
    ? currentValues.filter(item => item !== value)
    : currentValues.concat(value)

  form.setValues({
    services: nextValues,
  })
}

async function handleSubmit(values: typeof form.values) {
  await showDemoResult(values)
}
</script>

<template>
  <Form :form="form">
    <Field name="services" :component="[Checkbox.Group]">
      <CellGroup inset>
        <Cell
          v-for="option in serviceOptions"
          :key="option.value"
          center
          clickable
          :title="option.label"
          :label="option.description"
          @click="toggleService(option.value)"
        >
          <template #title>
            <div class="service-title">
              <span>{{ option.label }}</span>
              <Tag plain type="primary">
                {{ option.tag }}
              </Tag>
            </div>
          </template>

          <template #right-icon>
            <Checkbox :name="option.value" />
          </template>
        </Cell>
      </CellGroup>
    </Field>

    <FormButtonGroup>
      <Submit @submit="handleSubmit">
        查看结果
      </Submit>
    </FormButtonGroup>
  </Form>
</template>

<style scoped>
.service-title {
  display: inline-flex;
  align-items: center;
  gap: 8px;
}
</style>

自定义选项内容

vue

<script setup lang="ts">
import { createForm } from '@silver-formily/core'
import { Checkbox, FormItem } from '@silver-formily/vant'
import { Field, FormProvider } from '@silver-formily/vue'
import { Tag } from 'vant'
import { serviceOptions } from './shared'

const form = createForm({
  values: {
    services: ['express'],
  },
})
</script>

<template>
  <FormProvider :form="form">
    <div class="demo-panel">
      <Field
        name="services"
        title="增值服务"
        :decorator="[FormItem, { labelAlign: 'top' }]"
        :component="[Checkbox.Group, { direction: 'vertical' }]"
        :data-source="serviceOptions"
      >
        <template #option="{ option }">
          <div class="service-option">
            <div class="service-option__main">
              <div class="service-option__label">
                {{ option.label }}
              </div>
              <div class="service-option__description">
                {{ option.description }}
              </div>
            </div>
            <Tag plain size="medium" type="primary">
              {{ option.tag }}
            </Tag>
          </div>
        </template>
      </Field>
    </div>
  </FormProvider>
</template>

<style scoped>
.service-option {
  display: flex;
  align-items: flex-start;
  justify-content: space-between;
  gap: 12px;
  width: 100%;
}

.service-option__main {
  display: grid;
  gap: 4px;
  flex: 1;
}

.service-option__label {
  color: var(--van-text-color);
  font-size: 14px;
  font-weight: 600;
  line-height: 1.4;
  text-align: left;
}

.service-option__description {
  color: var(--van-text-color-2);
  font-size: 12px;
  line-height: 1.5;
  text-align: left;
}
</style>

禁用状态

vue

<script setup lang="ts">
import { createForm } from '@silver-formily/core'
import { Checkbox, FormItem } from '@silver-formily/vant'
import { Field, FormProvider } from '@silver-formily/vue'

const form = createForm({
  values: {
    disabledChannels: ['sms'],
  },
})
</script>

<template>
  <FormProvider :form="form">
    <div class="demo-panel">
      <Field
        name="disabledChannels"
        title="禁用态"
        :decorator="[FormItem, { labelAlign: 'top' }]"
        :component="[Checkbox.Group, { disabled: true }]"
        :data-source="[
          { label: '短信提醒', value: 'sms' },
          { label: '邮件提醒', value: 'email' },
        ]"
      />

      <div class="status-tip">
        Vant 官方没有提供 `readonly` 版 Checkbox，这里保持和官方一致，只演示 `disabled` 场景。
      </div>
    </div>
  </FormProvider>
</template>

<style scoped>
.status-tip {
  margin-top: 12px;
  color: var(--van-text-color-2);
  font-size: 12px;
  line-height: 1.6;
}
</style>

API

Checkbox 官方透传属性

单个 Checkbox 的属性、插槽、事件直接参考 Vant Checkbox 官方文档。

Checkbox.Group 透传的官方分组属性也直接参考同一页里的 Group API。

Checkbox.Group 扩展属性

属性名	类型	描述	默认值
`options`	`CheckboxOption[]`	选项列表，通常由 `dataSource` 自动映射	`[]`
`labelPosition`	`enum`	统一控制选项文字相对图标的位置	`-`
`labelDisabled`	`boolean`	是否禁用点击文字切换	`-`

CheckboxOption

统一使用 { label, value } 格式来描述选项。

除 label / value 之外，CheckboxOption 支持直接透传 Vant 单个 Checkbox 可用属性，具体请直接参考 Vant Checkbox 官方文档。

额外说明：

通过 option 作用域插槽自定义渲染时，可以继续在选项对象上挂 description、tag 这类业务字段。
这类额外业务字段会保留在插槽参数 option 上，但不会透传到内部 VanCheckbox DOM。

Checkbox ​

单个复选框 ​

基础多选 ​

排列方式与最多选择数量 ​

搭配单元格组件使用 ​

自定义选项内容 ​

禁用状态 ​

API ​

Checkbox 官方透传属性 ​

Checkbox.Group 扩展属性 ​

CheckboxOption ​