Silver Formily Vant1.0.1

Appearance

Mobile Preview Open
Open mobile preview

PickerGroup ​

PickerGroup 是基于 Vant 官方 PickerGroup 做的 Formily 字段封装，交互层面和 Picker 一样通过点击字段打开弹层，但弹层内部会按 tab 分步完成多项选择。

提示

  • PickerGroup 内部通过 createPopup 创建弹层，弹层内容复用 PickerGroupPanel。
  • 默认插槽中推荐使用 PickerPanel、DatePickerPanel、TimePickerPanel、AreaPanel 这类 Panel 组件；如果直接使用 Vant 官方组件，需要自行处理字段值与 Vant 内部值结构之间的转换。

基础使用 ​

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

const form = createForm({
  values: {
    appointment: ['sh', 'night'],
  },
})

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

<template>
  <Form :form="form">
    <Field
      name="appointment"
      title="预约信息"
      :decorator="[FormItem, { isLink: true }]"
      :component="[PickerGroup]"
      :data-source="appointmentOptions"
    >
      <template #default="{ dataSource, panelProps }">
        <PickerPanel
          v-bind="panelProps[0]"
          :columns="dataSource[0].options"
        />
        <PickerPanel
          v-bind="panelProps[1]"
          :columns="dataSource[1].options"
        />
      </template>
    </Field>

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

自定义步骤内容 ​

vue
<script setup lang="ts">
import type { PickerGroupResolvedValue } from '@silver-formily/vant'
import { createForm } from '@silver-formily/core'
import { DatePickerPanel, Form, FormButtonGroup, FormItem, PickerGroup, Submit, TimePickerPanel } from '@silver-formily/vant'
import { Field } from '@silver-formily/vue'
import { showDemoResult } from '../shared'
import { scheduleTabs } from './shared'

const form = createForm({
  values: {
    schedule: ['2026-03-30', '09:30'],
  },
})

const minDate = new Date(2025, 0, 1)
const maxDate = new Date(2027, 11, 31)

function formatSchedule(value: PickerGroupResolvedValue) {
  const [date = '', time = ''] = value ?? []

  const dateText = String(date ?? '')
  const timeText = String(time ?? '')

  return [dateText, timeText]
    .filter(Boolean)
    .join(' / ')
}

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

<template>
  <Form :form="form">
    <Field
      name="schedule"
      title="预约时间"
      :decorator="[FormItem, { isLink: true }]"
      :component="[PickerGroup, { displayFormatter: formatSchedule }]"
      :data-source="scheduleTabs"
    >
      <template #default="{ panelProps }">
        <DatePickerPanel
          v-bind="panelProps[0]"
          :min-date="minDate"
          :max-date="maxDate"
        />
        <TimePickerPanel v-bind="panelProps[1]" />
      </template>
    </Field>

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

Area 与 TimePicker 组合 ​

vue
<script setup lang="ts">
import type { PickerGroupResolvedValue } from '@silver-formily/vant'
import { createForm } from '@silver-formily/core'
import { AreaPanel, Form, FormButtonGroup, FormItem, PickerGroup, Submit, TimePickerPanel } from '@silver-formily/vant'
import { Field } from '@silver-formily/vue'
import { areaList } from '@vant/area-data'
import { showDemoResult } from '../shared'
import { deliveryTabs } from './shared'

const form = createForm({
  values: {
    delivery: ['330106', '19:30'],
  },
})

function resolveAreaText(code: string) {
  if (!code)
    return ''

  const province = areaList.province_list[`${code.slice(0, 2)}0000`]
  const city = areaList.city_list[`${code.slice(0, 4)}00`]
  const county = areaList.county_list[code]

  return [province, city, county]
    .filter(Boolean)
    .join(' / ')
}

function formatDelivery(value: PickerGroupResolvedValue) {
  const [areaCode = '', time = ''] = value ?? []
  const areaText = typeof areaCode === 'string'
    ? resolveAreaText(areaCode)
    : ''
  const timeText = String(time ?? '')

  return [areaText, timeText]
    .filter(Boolean)
    .join(' | ')
}

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

<template>
  <Form :form="form">
    <Field
      name="delivery"
      title="配送时间"
      :decorator="[FormItem, { isLink: true }]"
      :component="[PickerGroup, { displayFormatter: formatDelivery }]"
      :data-source="deliveryTabs"
    >
      <template #default="{ panelProps }">
        <AreaPanel
          v-bind="panelProps[0]"
          :area-list="areaList"
        />
        <TimePickerPanel v-bind="panelProps[1]" />
      </template>
    </Field>

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

工具栏与选项插槽 ​

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

const form = createForm({
  values: {
    appointment: ['hz', 'am'],
  },
})
</script>

<template>
  <FormProvider :form="form">
    <div class="demo-panel">
      <Field
        name="appointment"
        title="自定义插槽"
        :decorator="[FormItem, { isLink: true }]"
        :component="[PickerGroup]"
        :data-source="appointmentOptions"
      >
        <template #default="{ dataSource, panelProps }">
          <PickerPanel
            v-bind="panelProps[0]"
            :columns="dataSource[0].options"
          >
            <template #option="option">
              <div class="picker-group-slot-option">
                <span>{{ option.text }}</span>
                <Tag plain size="medium" :type="option.value === 'sh' ? 'danger' : 'primary'">
                  {{ option.value === 'sh' ? '热门' : '常用' }}
                </Tag>
              </div>
            </template>
          </PickerPanel>

          <PickerPanel
            v-bind="panelProps[1]"
            :columns="dataSource[1].options"
          >
            <template #option="option">
              <div class="picker-group-slot-option">
                <span>{{ option.text }}</span>
                <Tag plain size="medium" :type="option.value === 'night' ? 'danger' : 'primary'">
                  {{ option.value === 'night' ? '热门' : '常用' }}
                </Tag>
              </div>
            </template>
          </PickerPanel>
        </template>

        <template #title>
          <div class="picker-group-slot-title">
            分步选择预约
          </div>
        </template>

        <template #cancel>
          <span class="picker-group-slot-action">关闭</span>
        </template>

        <template #confirm>
          <span class="picker-group-slot-action picker-group-slot-action--confirm">下一步 / 完成</span>
        </template>
      </Field>
    </div>
  </FormProvider>
</template>

<style scoped>
.picker-group-slot-title {
  padding: 8px 0;
  font-size: 16px;
  font-weight: 600;
}

.picker-group-slot-action {
  font-size: 14px;
  color: var(--van-text-color-2);
}

.picker-group-slot-action--confirm {
  color: var(--van-primary-color);
}

.picker-group-slot-option {
  display: flex;
  align-items: center;
  justify-content: space-between;
  gap: 12px;
  width: 100%;
}
</style>

API ​

使用约定 ​

  • dataSource 的推荐结构如下：
ts
interface PickerGroupDataSourceItem {
  title: string
  options?: PickerColumn
}

type PickerGroupDataSource = PickerGroupDataSourceItem[]
  • title 用于生成内部 tab 标题
  • options 默认推荐使用 { label, value, children }；内部会自动映射成 Vant Picker 所需的 text
  • 旧数据里的 text 仍会被当成 label 兼容处理
  • 最终字段值会按 tab 保留每个 panel 自己的 modelValue 结构，例如 ['2026-03-30', '09:30']
  • 触发区默认把每个 tab 的选中文案用 separator 拼接，默认值为 ' / '
  • readPretty 模式下会自动回显当前选项文案；组合日期、时间、地区等非 dataSource.options 场景时，推荐同时提供 displayFormatter
  • 当前不提供外部 activeTab prop / v-model:active-tab 控制模型；步骤切换由内部 PickerGroupPanel 管理
  • 默认插槽里的各个 panel 不会自动读取 dataSource[index].options，需要按需把 dataSource[index].options 传给 PickerPanel 的 columns

补充 Props ​

属性名类型描述默认值
placeholderstring未选择时的展示文案'请选择选项'
popupPropsPickerGroupPopupProps传给内部 Popup 的配置{}
separatorstring字段展示区分隔符' / '
displayFormatterFunction自定义字段展示区文案；默认插槽模式建议显式提供-

分步选择相关属性可直接参考 PickerGroupPanel，例如 modelValue、dataSource、tabs、columnsFieldNames、nextStepText、readonly、disabled 等。

Panel 绑定 Props ​

默认插槽提供 dataSource 和 panelProps。其中 dataSource[index].options 可作为 PickerPanel 的 columns，panelProps[index] 可通过 v-bind 绑定给各类 panel。panelProps 会提供 modelValue、onUpdate:modelValue、onConfirm、readonly、disabled、showToolbar: false，以及以下通用 Picker 配置：

属性名类型描述默认值
optionHeightnumber | string选项高度官方默认值
visibleOptionNumnumber | string可见选项个数官方默认值
swipeDurationnumber | string滚动惯性动画时长官方默认值
allowHtmlboolean是否渲染 HTML 文案官方默认值

配置项与默认值可以直接参考createPopup。

Slots ​

以下插槽已转发：

插槽名描述插槽参数
default自定义步骤内容，推荐传入各类 *Panel 组件{ dataSource, modelValue, values, panelProps, setValue }
title自定义顶部标题-
cancel自定义取消按钮-
confirm自定义确认按钮-
toolbar自定义整个工具栏-

Events ​

事件名描述回调参数
update:modelValue最后一步确认后同步字段值Function
confirm最后一步点击确认时触发Function
cancel点击取消按钮时触发Function
open弹层打开时触发-
close弹层关闭时触发-
opened弹层打开且动画结束后触发-
closed弹层关闭且动画结束后触发-
clickOverlay点击遮罩层时触发Function
update:show弹层开关变化时触发Function