Silver Formily Vant1.0.1

Appearance

Mobile Preview Open
Open mobile preview

Picker ​

Picker 是基于 PickerPanel 做的弹出式封装，大部分的属性值可以参考 PickerPanel。

提示

Field 上的 dataSource 会自动映射到 columns

基础使用 ​

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

const form = createForm({
  values: {
    city: 'sz',
  },
})

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

<template>
  <Form :form="form">
    <Field
      name="city"
      title="出发城市"
      :decorator="[FormItem, { isLink: true }]"
      :component="[Picker, { popupProps: { closeOnClickOverlay: false } }]"
      :data-source="cityOptions"
    />

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

多列选择 ​

当 dataSource 是二维数组时，会自动切换成多列 Picker，字段值也会同步变成数组。

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

const form = createForm({
  values: {
    schedule: ['sh', 'night'],
  },
})
</script>

<template>
  <FormProvider :form="form">
    <div class="demo-panel">
      <Field
        name="schedule"
        title="行程时段"
        :decorator="[FormItem, { isLink: true }]"
        :component="[Picker]"
        :data-source="scheduleColumns"
      />
    </div>
  </FormProvider>
</template>

级联选择 ​

带 children 的根列数据会自动识别为级联结构，但交互仍然保留 Vant 官方滚轮选择器的体验。

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

const form = createForm({
  values: {
    region: ['zj', 'nb'],
  },
})
</script>

<template>
  <FormProvider :form="form">
    <div class="demo-panel">
      <Field
        name="region"
        title="服务区域"
        :decorator="[FormItem, { isLink: true }]"
        :component="[Picker]"
        :data-source="regionColumns"
      />
    </div>
  </FormProvider>
</template>

自定义字段名 ​

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

const form = createForm({
  values: {
    scene: ['travel', 'flight'],
  },
})
</script>

<template>
  <FormProvider :form="form">
    <div class="demo-panel">
      <Field
        name="scene"
        title="出行方案"
        :decorator="[FormItem, { isLink: true }]"
        :component="[
          Picker,
          {
            columnsFieldNames: customFieldNames,
          },
        ]"
        :data-source="customFieldColumns"
      />
    </div>
  </FormProvider>
</template>

自定义展示文案 ​

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

const form = createForm({
  values: {
    schedule: ['sz', 'pm'],
  },
})

function displayFormatter(_value: unknown, selectedOptions: Array<{ text?: any } | undefined>) {
  return selectedOptions
    .map(option => option?.text)
    .filter(Boolean)
    .join(' · ')
}
</script>

<template>
  <FormProvider :form="form">
    <div class="demo-panel">
      <Field
        name="schedule"
        title="自定义文案"
        :decorator="[FormItem, { isLink: true }]"
        :component="[
          Picker,
          {
            displayFormatter,
          },
        ]"
        :data-source="scheduleColumns"
      />
    </div>
  </FormProvider>
</template>

自定义插槽 ​

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

const form = createForm({
  values: {
    city: 'nb',
  },
})
</script>

<template>
  <FormProvider :form="form">
    <div class="demo-panel">
      <Field
        name="city"
        title="自定义插槽"
        :decorator="[FormItem, { isLink: true }]"
        :component="[Picker]"
        :data-source="cityOptions"
      >
        <template #title>
          <div class="picker-slot-title">
            选择服务城市
          </div>
        </template>

        <template #cancel>
          <span class="picker-slot-action">返回</span>
        </template>

        <template #confirm>
          <span class="picker-slot-action picker-slot-action--confirm">确认并写回</span>
        </template>

        <template #columns-top>
          <div class="picker-slot-note">
            这里直接复用 Vant Picker 官方的 columns-top 区域。
          </div>
        </template>

        <template #option="option">
          <div class="picker-slot-option">
            <span>{{ option.text }}</span>
            <Tag plain size="medium" :type="option.value === 'sh' ? 'danger' : 'primary'">
              {{ option.value === 'sh' ? '热门' : '常用' }}
            </Tag>
          </div>
        </template>

        <template #columns-bottom>
          <div class="picker-slot-note picker-slot-note--bottom">
            选中后点击右上角按钮才会真正写回字段值。
          </div>
        </template>
      </Field>
    </div>
  </FormProvider>
</template>

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

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

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

.picker-slot-note {
  padding: 12px 16px 4px;
  font-size: 12px;
  line-height: 1.5;
  color: var(--van-text-color-2);
}

.picker-slot-note--bottom {
  padding-top: 4px;
  padding-bottom: 16px;
}

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

自定义弹出位置 ​

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

const form = createForm({
  values: {
    city: 'hz',
  },
})
</script>

<template>
  <FormProvider :form="form">
    <div class="demo-panel">
      <Field
        name="city"
        title="顶部弹出"
        :decorator="[FormItem, { isLink: true }]"
        :component="[
          Picker,
          {
            popupProps: {
              position: 'top',
            },
          },
        ]"
        :data-source="cityOptions"
      />
    </div>
  </FormProvider>
</template>

API ​

  • Field 上的 dataSource 会自动映射到 columns，默认推荐使用 { label, value, children }，更贴近 Formily 常见的 dataSource 风格。
  • 单列字段值是 string | number | null，多列 / 级联字段值是 Array<string | number> | null。
  • 触发区交互状态跟随 Field 的 disabled / readOnly / readPretty，不会透传到内部 Picker。

选项结构 ​

默认选项结构如下：

ts
interface PickerOption {
  label?: string | number
  value?: string | number
  disabled?: boolean
  children?: PickerOption[]
}
  • 默认使用 label 作为展示文案字段，内部会自动映射成 Vant Picker 所需的 text。
  • 旧数据里的 text 仍会被当成 label 兼容处理。
  • 如果后端字段名不同，可通过 PickerFieldNames 指定映射关系，其中 text 表示“文案字段名”。

补充 Props ​

属性名类型描述默认值
modelValuestring | number | Array<string | number> | null当前字段值-
columnsPickerColumn | PickerColumn[]选项列，通常由 dataSource 提供[]
columnsFieldNamesPickerFieldNames自定义字段名映射官方默认值
placeholderstring未选择时的展示文案'请选择选项'
popupPropsPickerPopupProps传给内部 Popup 的配置-
separatorstring字段展示区分隔符' / '
displayFormatterFunction自定义字段展示区文案-

除上述补充能力外，Picker 选项结构、滚轮交互和已透传的官方属性 / 插槽可参考 Vant Picker 官方文档。当前封装固定通过 Popup 弹层承载，不需要手动维护 show；内部固定显示工具栏，不支持隐藏 showToolbar。

参考createPopup