TimePicker 时间选择

介绍

时间选择器,通常与弹出层组件配合使用。

代码演示

基础用法

通过 v-model 绑定当前选中的时间。

<z-time-picker v-model="currentTime" title="选择时间" />
import { ref } from 'vue';
const currentTime = ref(['12', '00']);

选项类型

通过 columns-type 属性可以控制选项的类型,支持以任意顺序对 hourminutesecond 进行排列组合。

比如:

  • 传入 ['hour'] 来单独选择小时。
  • 传入 ['minute'] 来单独选择分钟。
  • 传入 ['minute', 'second'] 来选择分钟和秒。
  • 传入 ['hour', 'minute', 'second'] 来选择小时、分钟和秒。
<z-time-picker
  v-model="currentTime"
  title="选择时间"
  :columns-type="columnsType"
/>
import { ref } from 'vue';
const currentTime = ref(['12', '00', '00']);
const columnsType = ['hour', 'minute', 'second'];

时间范围

你可以使用 min-hourmax-hour 等属性来限制小时(hour)范围、分钟(minute)范围和秒(second)范围。

比如以下示例,用户可以选择的小时是 10 ~ 20 ,分钟是 30 ~ 40

<z-time-picker
  v-model="currentTime"
  title="选择时间"
  :min-hour="10"
  :max-hour="20"
  :min-minute="30"
  :max-minute="40"
/>

整体时间范围

你可以使用 min-timemax-time 属性来限制整体时间范围,约定格式 10:00:00

  • 设置 min-time 后,min-hourmin-minutemin-second 属性将不会生效。
  • 设置 max-time 后,max-hourmax-minutemax-second 属性将不会生效。

比如以下示例,用户可以选择从 09:40:1020:20:50 的任意时间。

<z-time-picker
  v-model="currentTime"
  title="选择时间"
  :columns-type="['hour', 'minute', 'second']"
  min-time="09:40:10"
  max-time="20:20:50"
/>

格式化选项

通过传入 formatter 函数,可以对选项的文字进行格式化。

<z-time-picker
  v-model="currentTime"
  title="选择时间"
  :formatter="formatter"
/>
const formatter = (type: string, option: any) => {
  if (type === 'hour') {
    option.text += '时'
  }
  if (type === 'minute') {
    option.text += '分'
  }
  return option
}

过滤选项

通过传入 filter 函数,可以对选项数组进行过滤,剔除不需要的时间,实现自定义时间间隔。

<z-time-picker v-model="currentTime" title="选择时间" :filter="filter" />
const filter = (type: string, options: any) => {
  if (type === 'minute') {
    return options.filter((option: any) => Number(option.value) % 10 === 0)
  }
  return options
}

高级用法

filter 函数的第三个参数能获取到当前选择的时间,这在使用非受控模式时,可以更灵活地过滤掉不需要的时间。

<z-time-picker title="选择时间" :filter="filter" />
const filterMore = (type: string, options: any, values: any) => {
  const hour = +values[0]

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

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

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

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

  return options
}

API

Props

参数说明类型默认值
v-model当前选中的时间string-
columns-type选项类型,由 hourminutesecond 组成的数组string['hour', 'minute']
min-hour可选的最小小时number | string0
max-hour可选的最大小时number | string23
min-minute可选的最小分钟number | string0
max-minute可选的最大分钟number | string59
min-second可选的最小秒数number | string0
max-second可选的最大秒数number | string59
min-time可选的最小时间,格式参考 07:40:00,使用时 min-hour min-minute min-second 不会生效string-
max-time可选的最大时间,格式参考 10:20:00,使用时 max-hour max-minute max-second 不会生效string-
title顶部栏标题string''
confirm-button-text确认按钮文字string确认
cancel-button-text取消按钮文字string取消
show-toolbar是否显示顶部栏booleantrue
loading是否显示加载状态booleanfalse
readonly是否为只读状态,只读状态下无法切换选项booleanfalse
filter选项过滤函数(type: string, options: PickerOption, values: string) => PickerOption-
formatter选项格式化函数(type: string, option: PickerOption) => PickerOption-
option-height选项高度,支持 rpx 单位,默认 pxnumber | string44
visible-option-num可见的选项个数number | string6
swipe-duration快速滑动时惯性滚动的时长,单位 msnumber | string1000

Events

事件名说明回调参数
confirm点击完成按钮时触发{ selectedValues, selectedOptions, selectedIndexes }
cancel点击取消按钮时触发{ selectedValues, selectedOptions, selectedIndexes }
change选项改变时触发{ selectedValues, selectedOptions, selectedIndexes, columnIndex }

Slots

名称说明参数
toolbar自定义整个顶部栏的内容-
title自定义标题内容-
confirm自定义确认按钮内容-
cancel自定义取消按钮内容-
option自定义选项内容option: PickerOption, index: number
columns-top自定义选项上方内容-
columns-bottom自定义选项下方内容-