DatetimePicker 时间选择

介绍

时间选择器,支持日期、年月、时分等维度,通常与弹出层组件配合使用。

引入

通过以下方式来全局注册组件,更多注册方式请参考组件注册

  1. import { createApp } from 'vue';
  2. import { DatetimePicker } from 'vant';
  3. const app = createApp();
  4. app.use(DatetimePicker);

代码演示

选择年月日

DatetimePicker 通过 type 属性来定义需要选择的时间类型,type 为 date 表示选择年月日。通过 min-date 和 max-date 属性可以确定可选的时间范围。

  1. <van-datetime-picker
  2. v-model="currentDate"
  3. type="date"
  4. title="选择年月日"
  5. :min-date="minDate"
  6. :max-date="maxDate"
  7. />
  1. import { ref } from 'vue';
  2. export default {
  3. setup() {
  4. const currentDate = ref(new Date(2021, 0, 17));
  5. return {
  6. minDate: new Date(2020, 0, 1),
  7. maxDate: new Date(2025, 10, 1),
  8. currentDate,
  9. };
  10. },
  11. };

选择年月

将 type 设置为 year-month 即可选择年份和月份。通过传入 formatter 函数,可以对选项文字进行格式化处理。

  1. <van-datetime-picker
  2. v-model="currentDate"
  3. type="year-month"
  4. title="选择年月"
  5. :min-date="minDate"
  6. :max-date="maxDate"
  7. :formatter="formatter"
  8. />
  1. import { ref } from 'vue';
  2. export default {
  3. setup() {
  4. const currentDate = ref(new Date());
  5. const formatter = (type, val) => {
  6. if (type === 'year') {
  7. return `${val}年`;
  8. }
  9. if (type === 'month') {
  10. return `${val}月`;
  11. }
  12. return val;
  13. };
  14. return {
  15. minDate: new Date(2020, 0, 1),
  16. maxDate: new Date(2025, 10, 1),
  17. formatter,
  18. currentDate,
  19. };
  20. },
  21. };

选择月日

将 type 设置为 month-day 即可选择月份和日期。

  1. <van-datetime-picker
  2. v-model="currentDate"
  3. type="month-day"
  4. title="选择月日"
  5. :min-date="minDate"
  6. :max-date="maxDate"
  7. :formatter="formatter"
  8. />
  1. import { ref } from 'vue';
  2. export default {
  3. setup() {
  4. const currentDate = ref(new Date());
  5. const formatter = (type, val) => {
  6. if (type === 'month') {
  7. return `${val}月`;
  8. }
  9. if (type === 'day') {
  10. return `${val}日`;
  11. }
  12. return val;
  13. };
  14. return {
  15. minDate: new Date(2020, 0, 1),
  16. maxDate: new Date(2025, 10, 1),
  17. formatter,
  18. currentDate,
  19. };
  20. },
  21. };

选择时间

将 type 设置为 time 即可选择时间(小时和分钟)。

  1. <van-datetime-picker
  2. v-model="currentTime"
  3. type="time"
  4. title="选择时间"
  5. :min-hour="10"
  6. :max-hour="20"
  7. />
  1. import { ref } from 'vue';
  2. export default {
  3. setup() {
  4. const currentTime = ref('12:00');
  5. return { currentTime };
  6. },
  7. };

选择完整时间

将 type 设置为 datetime 即可选择完整时间,包括年月日和小时、分钟。

  1. <van-datetime-picker
  2. v-model="currentDate"
  3. type="datetime"
  4. title="选择完整时间"
  5. :min-date="minDate"
  6. :max-date="maxDate"
  7. />
  1. import { ref } from 'vue';
  2. export default {
  3. setup() {
  4. const currentDate = ref(new Date());
  5. return {
  6. minDate: new Date(2020, 0, 1),
  7. maxDate: new Date(2025, 10, 1),
  8. currentDate,
  9. };
  10. },
  11. };

选择年月日小时

将 type 设置为 datehour 即可选择日期和小时,包括年月日和小时。

  1. <van-datetime-picker
  2. v-model="currentDate"
  3. type="datehour"
  4. title="选择年月日小时"
  5. :min-date="minDate"
  6. :max-date="maxDate"
  7. />
  1. import { ref } from 'vue';
  2. export default {
  3. setup() {
  4. const currentDate = ref(new Date());
  5. return {
  6. minDate: new Date(2020, 0, 1),
  7. maxDate: new Date(2025, 10, 1),
  8. currentDate,
  9. };
  10. },
  11. };

选项过滤器

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

  1. <van-datetime-picker v-model="currentTime" type="time" :filter="filter" />
  1. import { ref } from 'vue';
  2. export default {
  3. setup() {
  4. const currentTime = ref('12:00');
  5. const filter = (type, options) => {
  6. if (type === 'minute') {
  7. return options.filter((option) => Number(option) % 5 === 0);
  8. }
  9. return options;
  10. };
  11. return {
  12. filter,
  13. currentTime,
  14. };
  15. },
  16. };

自定义列排序

  1. <van-datetime-picker
  2. v-model="currentDate"
  3. type="date"
  4. title="自定义列排序"
  5. :columns-order="['month', 'day', 'year']"
  6. :formatter="formatter"
  7. />
  1. import { ref } from 'vue';
  2. export default {
  3. setup() {
  4. const currentDate = ref(new Date());
  5. const formatter = (type, val) => {
  6. if (type === 'year') {
  7. return val + '年';
  8. }
  9. if (type === 'month') {
  10. return val + '月';
  11. }
  12. if (type === 'day') {
  13. return val + '日';
  14. }
  15. return val;
  16. };
  17. return {
  18. formatter,
  19. currentDate,
  20. };
  21. },
  22. };

API

Props

参数说明类型默认值
type时间类型,可选值为 date time
year-month month-day datehour
stringdatetime
title顶部栏标题string‘’
confirm-button-text确认按钮文字string确认
cancel-button-text取消按钮文字string取消
show-toolbar是否显示顶部栏booleantrue
loading是否显示加载状态booleanfalse
readonly是否为只读状态,只读状态下无法切换选项booleanfalse
filter选项过滤函数(type: string, values: string[]) => string[]-
formatter选项格式化函数(type: string, value: string) => string-
columns-order自定义列排序数组, 子项可选值为
yearmonthdayhourminute
string[]-
item-height选项高度,支持 px vw vh rem 单位,默认 pxnumber | string44
visible-item-count可见的选项个数number | string6
swipe-duration快速滑动时惯性滚动的时长,单位msnumber | string1000

DatePicker Props

当时间选择器类型为 date 或 datetime 时,支持以下 props:

参数说明类型默认值
min-date可选的最小时间,精确到分钟Date十年前
max-date可选的最大时间,精确到分钟Date十年后

TimePicker Props

当时间选择器类型为 time 时,支持以下 props:

参数说明类型默认值
min-hour可选的最小小时number | string0
max-hour可选的最大小时number | string23
min-minute可选的最小分钟number | string0
max-minute可选的最大分钟number | string59

Events

事件名说明回调参数
change当值变化时触发的事件value: 当前选中的时间
confirm点击完成按钮时触发的事件value: 当前选中的时间
cancel点击取消按钮时触发的事件-

Slots

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

方法

通过 ref 可以获取到 DatetimePicker 实例并调用实例方法,详见组件实例方法

方法名说明参数返回值
getPicker获取 Picker 实例,用于调用 Picker 的实例方法--

类型定义

组件导出以下类型定义:

  1. import type {
  2. DatetimePickerType,
  3. DatetimePickerProps,
  4. DatetimePickerInstance,
  5. } from 'vant';

DatetimePickerInstance 是组件实例的类型,用法如下:

  1. import { ref } from 'vue';
  2. import type { DatetimePickerInstance } from 'vant';
  3. const datetimePickerRef = ref<DatetimePickerInstance>();
  4. datetimePickerRef.value?.getPicker();

常见问题

设置 min-date 或 max-date 后出现页面卡死的情况?

请注意不要在模板中直接使用类似min-date="new Date()"的写法,这样会导致每次渲染组件时传入一个新的 Date 对象,而传入新的数据会触发下一次渲染,从而陷入死循环。

正确的做法是将min-date作为一个数据定义在data函数中。

在 iOS 系统上初始化组件失败?

如果你遇到了在 iOS 上无法渲染组件的问题,请确认在创建 Date 对象时没有使用new Date('2020-01-01')这样的写法,iOS 不支持以中划线分隔的日期格式,正确写法是new Date('2020/01/01')

对此问题的详细解释:stackoverflow

在桌面端无法操作组件?

参见桌面端适配

是否有年份或月份选择器?

如果仅需要选择年份或者月份,建议直接使用 Picker 选择器 组件。

你也可以升级到 Vant 4,并使用 DatePicker 日期选择 组件。

是否支持选择秒?

Vant 3 中的 DatetimePicker 组件不支持选择秒。

请升级到 Vant 4,并使用 TimePicker 时间选择 组件。

DatetimePicker 时间选择 - 图1