Silver Formily Vant0.0.0

Appearance

Mobile Preview Open
Open mobile preview

DatePicker ​

DatePicker 是基于 Vant 官方 DatePicker 做的 Formily 字段封装，保留滚轮日期选择体验，同时补上字段触发区、内置弹层和 readPretty 展示。

与官方的差异

  • 当前封装固定通过 Popup 弹层承载，不需要手动维护 show
  • 字段值统一保存为字符串，例如 '2026-03-30'
  • format 控制字段展示格式，value-format 控制实际写回字段的字符串格式
  • 关闭弹层时会回滚未确认的临时选择，只有点击确认按钮才会写回字段值
  • 作为 PickerGroup 默认插槽子组件使用时，会自动切换成内联模式并复用 PickerGroup 的工具栏

基础使用 ​

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

const form = createForm({
  values: {
    appointmentDate: '2026-03-30',
  },
})

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

<template>
  <Form :form="form">
    <Field
      name="appointmentDate"
      title="预约日期"
      :decorator="[FormItem, { isLink: true }]"
      :component="[DatePicker, { minDate, maxDate }]"
    />

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

自定义列类型 ​

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

const form = createForm({
  values: {
    billingMonth: '2026-06',
  },
})
</script>

<template>
  <FormProvider :form="form">
    <div class="demo-panel">
      <Field
        name="billingMonth"
        title="账单月份"
        :decorator="[FormItem, { isLink: true }]"
        :component="[
          DatePicker,
          {
            columnsType: ['year', 'month'],
            minDate,
            maxDate,
          },
        ]"
      />
    </div>
  </FormProvider>
</template>

format 与 value-format ​

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

const form = createForm({
  values: {
    appointmentDate: '30/03/2026',
  },
})

const currentValue = formilyComputed(() => {
  return form.values.appointmentDate as string | undefined
})

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

<template>
  <Form :form="form">
    <div class="demo-panel">
      <Field
        name="appointmentDate"
        title="按 DD/MM/YYYY 提交"
        :decorator="[FormItem, { isLink: true }]"
        :component="[
          DatePicker,
          {
            format: 'YYYY年MM月DD日',
            minDate,
            maxDate,
            valueFormat: 'DD/MM/YYYY',
          },
        ]"
      />

      <div class="demo-value">
        当前写回值：{{ currentValue || '暂无' }}
      </div>
    </div>

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

<style scoped>
.demo-panel {
  display: grid;
  gap: 12px;
}

.demo-value {
  padding: 0 16px;
  color: var(--van-text-color-2);
  font-size: 14px;
  line-height: 20px;
}
</style>

自定义弹出位置 ​

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

const form = createForm({
  values: {
    renewalDate: '2026-08-18',
  },
})
</script>

<template>
  <FormProvider :form="form">
    <div class="demo-panel">
      <Field
        name="renewalDate"
        title="顶部弹出"
        :decorator="[FormItem, { isLink: true }]"
        :component="[
          DatePicker,
          {
            position: 'top',
            minDate,
            maxDate,
          },
        ]"
      />
    </div>
  </FormProvider>
</template>

API ​

使用约定 ​

  • 推荐和 FormItem 搭配使用，由 FormItem 负责标题、箭头和反馈状态
  • 默认值类型为 string | null
  • 内部会先按 value-format 解析字段值，再转换成 Vant DatePicker 需要的滚轮数组
  • 如果未显式传 value-format，会按 columnsType 推导默认格式，例如 ['year', 'month'] -> 'YYYY-MM'
  • 如果未显式传 format，字段展示会默认复用 value-format
  • readonly / readOnly / disabled 都会阻止弹层打开
  • 当前不支持通过组件 ref 调用官方实例方法

封装补充 Props ​

属性名类型描述默认值
modelValuestring | null当前字段值-
formatstring字段展示格式与 value-format 一致
valueFormatstring字段值格式，对应模板里的 value-formatYYYY-MM-DD
placeholderstring未选择时的展示文案'请选择日期'
displayFormatterFunction自定义字段展示区文案，优先级高于 format-
readonlyboolean只读态，阻止打开弹层false
disabledboolean禁用态，阻止打开弹层false

官方 DatePicker Props ​

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

属性名类型描述默认值
titlestring顶部标题官方默认值
columnsTypeArray<'year' | 'month' | 'day'>日期列类型官方默认值
minDateDate可选最小日期官方默认值
maxDateDate可选最大日期官方默认值
cancelButtonTextstring取消按钮文案官方默认值
confirmButtonTextstring确认按钮文案官方默认值
loadingboolean是否显示加载状态官方默认值
optionHeightnumber | string选项高度官方默认值
visibleOptionNumnumber | string可见选项个数官方默认值
swipeDurationnumber | string滚动惯性动画时长官方默认值
allowHtmlboolean是否渲染 HTML 文案官方默认值
formatterFunction自定义选项展示官方默认值
filterFunction自定义选项过滤官方默认值

官方 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
columns-top选项区顶部内容-
columns-bottom选项区底部内容-

Events ​

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

参考 ​