Silver Formily Vant0.0.0

Appearance

Mobile Preview Open
Open mobile preview

Checkbox ​

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

使用建议

协议确认、订阅开关这类单值场景优先使用 Checkbox；需要把 dataSource 直接映射成多选列表时再使用 Checkbox.Group。

单个复选框 ​

vue
<script setup lang="ts">
import { createForm } from '@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 :on-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 '@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 :on-submit="handleSubmit">
        查看结果
      </Submit>
    </FormButtonGroup>
  </Form>
</template>

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

vue
<script setup lang="ts">
import { createForm } from '@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 '@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 :on-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 '@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;
}

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

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

禁用状态 ​

vue
<script setup lang="ts">
import { createForm } from '@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 ​

使用约定 ​

  • Field 上的 dataSource 会自动映射到 Checkbox.Group 的 options
  • Checkbox.Group 在 readPretty 模式下会自动显示已选选项的 label，找不到匹配项时回退显示原始值
  • 对象选项推荐写成 { label, value }，同时也兼容直接传字符串 / 数字 / 布尔值数组
  • 如果要复刻 Vant 官方“搭配单元格组件使用”的布局，可以给 Checkbox.Group 传默认插槽，内部直接放原始 Checkbox 子节点

Checkbox 官方透传属性 ​

以下属性会直接透传给 Vant Checkbox：

属性名类型描述默认值
modelValueunknown当前勾选值-
nameunknown选项值-
shapeenum图标形状官方默认值
disabledboolean是否禁用官方默认值
iconSizenumber | string图标大小官方默认值
checkedColorstring选中颜色官方默认值
labelPositionenum文字相对图标的位置官方默认值
labelDisabledboolean是否禁用点击文字切换官方默认值
indeterminateboolean | null是否显示半选状态官方默认值
bindGroupboolean是否绑定到分组上下文官方默认值

Checkbox.Group 扩展属性 ​

属性名类型描述默认值
optionsArray<CheckboxOption | string | number | boolean>选项列表，通常由 dataSource 自动映射[]
labelPositionenum统一控制选项文字相对图标的位置-
labelDisabledboolean是否禁用点击文字切换-

Checkbox.Group 官方透传属性 ​

以下分组属性会直接透传给 Vant CheckboxGroup：

属性名类型描述默认值
modelValueunknown[]当前选中值[]
maxnumber | string最大可选数量官方默认值
shapeenum图标形状官方默认值
directionenum排列方向官方默认值
disabledboolean是否禁用官方默认值
iconSizenumber | string图标大小官方默认值
checkedColorstring选中颜色官方默认值

CheckboxOption ​

对象选项除了 label / value 之外，也支持透传 Vant 单个 Checkbox 的常见属性：

属性名类型描述默认值
labelany选项文案-
valueunknown选项值-
disabledboolean单个选项禁用-
shapeenum单个选项图标形状-
iconSizenumber | string单个选项图标大小-
checkedColorstring单个选项选中颜色-
labelPositionenum单个选项文案位置-
labelDisabledboolean单个选项是否禁用点击文案-
indeterminateboolean | null单个选项是否显示半选状态-
bindGroupboolean是否绑定到当前分组-

Slots ​

Checkbox ​

插槽名描述插槽参数
default复选框文案内容-
icon自定义图标官方参数

Checkbox.Group ​

插槽名描述插槽参数
default完全自定义分组内容，适合搭配 Cell / CellGroup-
option基于 options 自定义每个选项的渲染内容object

Events ​

事件名描述回调参数
update:modelValue勾选值变化时触发Function
changeVant 原生变更事件Function

参考 ​

属性命名和交互能力主要参考 Vant Checkbox 官方文档（正式站）。