Silver Formily Vant0.0.0

Appearance

Mobile Preview Open
Open mobile preview

Picker ​

Picker 是基于 Vant 官方 Picker 做的 Formily 封装，补上了字段触发区、内置弹层、阅读态展示，以及更贴近表单字段心智的值形态适配。

与官方的差异

  • 当前封装固定通过 Popup 弹层承载，不需要手动维护 show
  • Field 上的 dataSource 会自动映射到 columns
  • 单列字段值保存为标量，多列 / 级联字段值保存为数组
  • 关闭弹层时会回滚未确认选择，只有点击确认按钮才会写回字段值
  • 内部固定显示工具栏，不支持隐藏 showToolbar

基础使用 ​

vue
<script setup lang="ts">
import { createForm } from '@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]"
      :data-source="cityOptions"
    />

    <FormButtonGroup>
      <Submit :on-submit="handleSubmit">
        查看结果
      </Submit>
    </FormButtonGroup>
  </Form>
</template>

多列选择 ​

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

vue
<script setup lang="ts">
import { createForm } from '@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 '@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 '@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 '@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 '@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 '@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,
          {
            position: 'top',
          },
        ]"
        :data-source="cityOptions"
      />
    </div>
  </FormProvider>
</template>

API ​

使用约定 ​

  • Field 上的 dataSource 会自动映射到 columns
  • 单列字段值是 string | number | null，多列 / 级联字段值是 Array<string | number> | null
  • 对象选项优先推荐写成 { label, value }，同时兼容 { text, value }、{ label, name }
  • readPretty 模式下会自动回显当前选项文案，找不到匹配项时回退为空占位
  • readonly / readOnly / disabled 都会阻止弹层打开
  • 当前不支持通过组件 ref 调用官方实例方法

封装补充 Props ​

属性名类型描述默认值
modelValuestring | number | Array<string | number>当前字段值-
columnsPickerColumn | PickerColumn[]选项列，通常由 dataSource 提供[]
columnsFieldNamesobject自定义字段名映射官方默认值
placeholderstring未选择时的展示文案'请选择选项'
separatorstring字段展示区分隔符' / '
displayFormatterFunction自定义字段展示区文案-
readonlyboolean只读态，阻止打开弹层false
disabledboolean禁用态，阻止打开弹层false

官方 Picker Props ​

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

属性名类型描述默认值
titlestring顶部标题官方默认值
loadingboolean是否显示加载状态官方默认值
toolbarPositionenum工具栏位置官方默认值
cancelButtonTextstring取消按钮文案官方默认值
confirmButtonTextstring确认按钮文案官方默认值
optionHeightnumber | string选项高度官方默认值
visibleOptionNumnumber | string可见选项个数官方默认值
swipeDurationnumber | string滚动惯性动画时长官方默认值
allowHtmlboolean是否渲染 HTML 文案官方默认值

官方 Popup Props ​

当前封装内部固定包了一层 Popup，以下弹层属性可直接使用：

属性名类型描述默认值
positionenum弹出位置'bottom'
roundboolean是否显示圆角true
overlayboolean是否显示遮罩层true
teleportstring | Element指定挂载节点官方默认值
closeOnPopstateboolean回退时是否自动关闭true
closeOnClickOverlayboolean点击遮罩是否自动关闭true
safeAreaInsetTopboolean是否开启顶部安全区官方默认值
safeAreaInsetBottomboolean是否开启底部安全区true
lockScrollboolean是否锁定背景滚动true
lazyRenderboolean是否延迟渲染内容true
zIndexnumber | string弹层层级官方默认值
durationnumber | string动画时长官方默认值
transitionstring自定义过渡动画官方默认值

Slots ​

以下官方插槽已转发：

插槽名描述插槽参数
title自定义标题-
cancel自定义取消按钮-
confirm自定义确认按钮-
toolbar自定义整个工具栏-
option自定义选项内容option
empty空状态内容-
columns-top选项区顶部内容-
columns-bottom选项区底部内容-

Events ​

事件名描述回调参数
update:modelValue点击确认后同步字段值Function
change任意列发生切换时触发Function
confirm点击确认按钮时触发Function
cancel点击取消按钮时触发Function
clickOption点击某个选项时触发Function
scrollInto滚动到某个选项时触发Function
open弹层打开时触发-
close弹层关闭时触发-
opened弹层打开且动画结束后触发-
closed弹层关闭且动画结束后触发-
clickOverlay点击遮罩层时触发Function
update:show弹层开关变化时触发Function

参考 ​