Silver Formily Vant0.0.0

Appearance

Mobile Preview Open
Open mobile preview

TimePicker ​

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

与官方的差异

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

基础用法 ​

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

const form = createForm({
  values: {
    currentTime: '12:00',
  },
})
</script>

<template>
  <FormProvider :form="form">
    <div class="demo-panel">
      <Field
        name="currentTime"
        title="当前时间"
        :decorator="[FormItem, { isLink: true }]"
        :component="[TimePicker]"
      />
    </div>
  </FormProvider>
</template>

选项类型 ​

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

const form = createForm({
  values: {
    currentTime: '12:00:00',
  },
})
</script>

<template>
  <FormProvider :form="form">
    <div class="demo-panel">
      <Field
        name="currentTime"
        title="选择时分秒"
        :decorator="[FormItem, { isLink: true }]"
        :component="[
          TimePicker,
          {
            columnsType: ['hour', 'minute', 'second'],
          },
        ]"
      />
    </div>
  </FormProvider>
</template>

时间范围 ​

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

const form = createForm({
  values: {
    currentTime: '12:35',
  },
})
</script>

<template>
  <FormProvider :form="form">
    <div class="demo-panel">
      <Field
        name="currentTime"
        title="限制小时与分钟范围"
        :decorator="[FormItem, { isLink: true }]"
        :component="[
          TimePicker,
          {
            minHour: 10,
            maxHour: 20,
            minMinute: 30,
            maxMinute: 40,
          },
        ]"
      />
    </div>
  </FormProvider>
</template>

整体时间范围 ​

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

const form = createForm({
  values: {
    currentTime: '12:00:00',
  },
})
</script>

<template>
  <FormProvider :form="form">
    <div class="demo-panel">
      <Field
        name="currentTime"
        title="限制整体时间范围"
        :decorator="[FormItem, { isLink: true }]"
        :component="[
          TimePicker,
          {
            columnsType: ['hour', 'minute', 'second'],
            minTime: '09:40:10',
            maxTime: '20:20:50',
          },
        ]"
      />
    </div>
  </FormProvider>
</template>

格式化选项 ​

vue
<script setup lang="ts">
import type { PickerOption } from '@silver-formily/vant'
import { createForm } from '@formily/core'
import { FormItem, TimePicker } from '@silver-formily/vant'
import { Field, FormProvider } from '@silver-formily/vue'

const form = createForm({
  values: {
    currentTime: '12:00:00',
  },
})

function formatter(type: string, option: PickerOption) {
  if (type === 'hour') {
    option.text += '时'
  }
  if (type === 'minute') {
    option.text += '分'
  }
  if (type === 'second') {
    option.text += '秒'
  }

  return option
}
</script>

<template>
  <FormProvider :form="form">
    <div class="demo-panel">
      <Field
        name="currentTime"
        title="格式化时间选项"
        :decorator="[FormItem, { isLink: true }]"
        :component="[
          TimePicker,
          {
            columnsType: ['hour', 'minute', 'second'],
            formatter,
          },
        ]"
      />
    </div>
  </FormProvider>
</template>

过滤选项 ​

vue
<script setup lang="ts">
import type { PickerOption } from '@silver-formily/vant'
import { createForm } from '@formily/core'
import { FormItem, TimePicker } from '@silver-formily/vant'
import { Field, FormProvider } from '@silver-formily/vue'

const form = createForm({
  values: {
    currentTime: '12:00',
  },
})

function filter(type: string, options: PickerOption[]) {
  if (type === 'minute') {
    return options.filter(option => Number(option.value) % 10 === 0)
  }

  return options
}
</script>

<template>
  <FormProvider :form="form">
    <div class="demo-panel">
      <Field
        name="currentTime"
        title="按 10 分钟间隔选择"
        :decorator="[FormItem, { isLink: true }]"
        :component="[TimePicker, { filter }]"
      />
    </div>
  </FormProvider>
</template>

高级用法 ​

vue
<script setup lang="ts">
import type { PickerOption } from '@silver-formily/vant'
import { createForm } from '@formily/core'
import { FormItem, TimePicker } from '@silver-formily/vant'
import { Field, FormProvider } from '@silver-formily/vue'

const form = createForm({
  values: {
    currentTime: '08:40',
  },
})

function filter(type: string, options: PickerOption[], values: string[]) {
  const hour = Number(values[0])

  if (type === 'hour') {
    return options.filter((option) => {
      const value = Number(option.value)
      return value >= 8 && value <= 18
    })
  }

  if (type === 'minute') {
    const minuteOptions = options.filter(option => Number(option.value) % 10 === 0)

    if (hour === 8) {
      return minuteOptions.filter(option => Number(option.value) >= 40)
    }

    if (hour === 18) {
      return minuteOptions.filter(option => Number(option.value) <= 20)
    }

    return minuteOptions
  }

  return options
}
</script>

<template>
  <FormProvider :form="form">
    <div class="demo-panel">
      <Field
        name="currentTime"
        title="营业时间段内选择"
        :decorator="[FormItem, { isLink: true }]"
        :component="[TimePicker, { filter }]"
      />
    </div>
  </FormProvider>
</template>

API ​

使用约定 ​

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

封装补充 Props ​

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

官方 TimePicker Props ​

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

属性名类型描述默认值
titlestring顶部标题官方默认值
columnsTypeArray<'hour' | 'minute' | 'second'>时间列类型官方默认值
minHournumber | string可选最小小时官方默认值
maxHournumber | string可选最大小时官方默认值
minMinutenumber | string可选最小分钟官方默认值
maxMinutenumber | string可选最大分钟官方默认值
minSecondnumber | string可选最小秒数官方默认值
maxSecondnumber | string可选最大秒数官方默认值
minTimestring最小可选时间官方默认值
maxTimestring最大可选时间官方默认值
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

参考 ​