Skip to content

日期选择器 DatePicker
11.0.2

输入或选择日期的控件

何时使用

  • 当用户需要选择或输入一个日期,弹出日期面板进行选择

参考文档

基本使用

Show Code
vue
<script setup lang="ts">
import { ref, watchEffect } from 'vue'
import { format } from 'date-fns'
const dateValue = ref(format(new Date(), 'yyyy-MM-dd'))
watchEffect(() => {
  console.log('dateValue', dateValue.value)
})
</script>
<template>
  <DatePicker v-model="dateValue" format="yyyy-MM-dd" placeholder="请选择日期" />
</template>

三种大小

small
middle
large
Show Code
vue
<script setup lang="ts">
import { ref, watchEffect } from 'vue'
import { format } from 'date-fns'
const sizeOptions = [
  {
    label: 'small',
    value: 'small'
  },
  {
    label: 'middle',
    value: 'middle'
  },
  {
    label: 'large',
    value: 'large'
  }
]
const size = ref('middle')
const dateValue = ref(format(new Date(), 'yyyy-MM-dd'))
watchEffect(() => {
  console.log('dateValue', dateValue.value)
})
</script>
<template>
  <Space vertical>
    <Radio :options="sizeOptions" v-model:value="size" button button-style="solid" />
    <DatePicker :size="size" v-model="dateValue" format="yyyy-MM-dd" placeholder="请选择日期" />
  </Space>
</template>

禁用

Show Code
vue
<script setup lang="ts">
import { ref } from 'vue'
import { format } from 'date-fns'
const dateValue = ref(format(new Date(), 'yyyy-MM-dd'))
</script>
<template>
  <DatePicker disabled v-model="dateValue" format="yyyy-MM-dd" />
</template>

禁用日期

不可选择过去日期,min-date 支持:Date | string 类型


Show Code
vue
<script setup lang="ts">
import { ref, watchEffect } from 'vue'
import { format } from 'date-fns'
const dateValue = ref(format(new Date(), 'yyyy-MM-dd'))
watchEffect(() => {
  console.log('dateValue', dateValue.value)
})
</script>
<template>
  <DatePicker v-model="dateValue" :min-date="new Date()" format="yyyy-MM-dd" placeholder="请选择日期" />
</template>

不可选择未来日期,max-date 支持:Date | string 类型


Show Code
vue
<script setup lang="ts">
import { ref, watchEffect } from 'vue'
import { format } from 'date-fns'
const dateValue = ref(format(new Date(), 'yyyy-MM-dd'))
watchEffect(() => {
  console.log('dateValue', dateValue.value)
})
</script>
<template>
  <DatePicker
    v-model="dateValue"
    :max-date="format(new Date(), 'yyyy-MM-dd')"
    format="yyyy-MM-dd"
    placeholder="请选择日期"
  />
</template>

只能选择未来七天内的日期,disabled-dates 支持:Date[] | string[] | (date: Date) => boolean 类型


Show Code
vue
<script setup lang="ts">
import { ref, watchEffect } from 'vue'
import { format, endOfDay, addDays } from 'date-fns'
const dateValue = ref(format(new Date(), 'yyyy-MM-dd'))
watchEffect(() => {
  console.log('dateValue', dateValue.value)
})
function disabledDates(date: Date): boolean {
  const current = date.getTime()
  if (endOfDay(new Date()).getTime() < current && current <= endOfDay(addDays(new Date(), 7)).getTime()) {
    return false
  }
  return true
}
</script>
<template>
  <DatePicker v-model="dateValue" :disabled-dates="disabledDates" format="yyyy-MM-dd" placeholder="请选择日期" />
</template>

不可选择未来七天的日期


Show Code
vue
<script setup lang="ts">
import { ref, watchEffect } from 'vue'
import { format, endOfDay, addDays } from 'date-fns'
const dateValue = ref(format(new Date(), 'yyyy-MM-dd'))
watchEffect(() => {
  console.log('dateValue', dateValue.value)
})
function disabledDatesNextWeek(date: Date): boolean {
  const current = date.getTime()
  if (endOfDay(new Date()).getTime() < current && current <= endOfDay(addDays(new Date(), 7)).getTime()) {
    return true
  }
  return false
}
</script>
<template>
  <DatePicker
    v-model="dateValue"
    :disabled-dates="disabledDatesNextWeek"
    format="yyyy-MM-dd"
    placeholder="请选择日期"
  />
</template>

不可选择明天/后天


Show Code
vue
<script setup lang="ts">
import { ref, watchEffect } from 'vue'
import { format, addDays } from 'date-fns'
const dateValue = ref(format(new Date(), 'yyyy-MM-dd'))
watchEffect(() => {
  console.log('dateValue', dateValue.value)
})
</script>
<template>
  <DatePicker
    v-model="dateValue"
    :disabled-dates="[addDays(new Date(), 1), addDays(new Date(), 2)]"
    format="yyyy-MM-dd"
    placeholder="请选择日期"
  />
</template>

不可选择周六和周日,disabled-week-days 支持:string[] | number[] 类型;0-6, 0是周日, 6是周六


Show Code
vue
<script setup lang="ts">
import { ref, watchEffect } from 'vue'
import { format } from 'date-fns'
const dateValue = ref(format(new Date(), 'yyyy-MM-dd'))
watchEffect(() => {
  console.log('dateValue', dateValue.value)
})
</script>
<template>
  <DatePicker v-model="dateValue" :disabled-week-days="[0, 6]" format="yyyy-MM-dd" placeholder="请选择日期" />
</template>

不可选择未来三个月,filters 支持:Filters 类型


Show Code
vue
<script setup lang="ts">
import { ref, watchEffect, computed } from 'vue'
import { format, getMonth, addMonths } from 'date-fns'
const dateValue = ref(format(new Date(), 'yyyy-MM-dd'))
watchEffect(() => {
  console.log('dateValue', dateValue.value)
})
interface Filters {
  months?: number[] // 0 = Jan, 11 - Dec
  years?: number[] // Array of years to disable
  times?: {
    hours?: number[] // disable specific hours
    minutes?: number[] // disable sepcific minutes
    seconds?: number[] // disable specific seconds
  }
}
const filters = computed<Filters>(() => {
  return {
    months: [0, 1, 2].map((index: number) => getMonth(addMonths(new Date(), index + 1)))
  }
})
</script>
<template>
  <DatePicker v-model="dateValue" :filters="filters" format="yyyy-MM-dd" placeholder="请选择日期" />
</template>

日期时间选择器

Show Code
vue
<script setup lang="ts">
import { ref, watchEffect } from 'vue'
import { format } from 'date-fns'
const dateTimeValue = ref(format(new Date(), 'yyyy-MM-dd HH:mm:ss'))
watchEffect(() => {
  console.log('dateTimeValue', dateTimeValue.value)
})
</script>
<template>
  <DatePicker
    :width="210"
    v-model="dateTimeValue"
    format="yyyy-MM-dd HH:mm:ss"
    show-time
    enable-seconds
    placeholder="请选择日期时间"
  />
</template>

日期范围选择器

Show Code
vue
<script setup lang="ts">
import { ref, watchEffect } from 'vue'
import { format, addDays } from 'date-fns'
const rangeValue = ref<string[]>([format(new Date(), 'yyyy-MM-dd'), format(addDays(new Date(), 3), 'yyyy-MM-dd')])
watchEffect(() => {
  console.log('rangeValue', rangeValue.value)
})
</script>
<template>
  <DatePicker :width="240" v-model="rangeValue" range format="yyyy-MM-dd" placeholder="请选择日期范围" />
</template>

双日期面板

Show Code
vue
<script setup lang="ts">
import { ref, watchEffect } from 'vue'
import { format, addDays } from 'date-fns'
const rangeValue = ref<string[]>([format(new Date(), 'yyyy-MM-dd'), format(addDays(new Date(), 3), 'yyyy-MM-dd')])
watchEffect(() => {
  console.log('rangeValue', rangeValue.value)
})
</script>
<template>
  <DatePicker
    :width="240"
    v-model="rangeValue"
    format="yyyy-MM-dd"
    range
    multi-calendars
    placeholder="请选择日期范围"
  />
</template>

日期时间范围选择器

Show Code
vue
<script setup lang="ts">
import { ref, watchEffect } from 'vue'
import { format, addDays } from 'date-fns'
const rangeTimeValue = ref<string[]>([
  format(new Date(), 'yyyy-MM-dd HH:mm:ss'),
  format(addDays(new Date(), 3), 'yyyy-MM-dd HH:mm:ss')
])
watchEffect(() => {
  console.log('rangeTimeValue', rangeTimeValue.value)
})
</script>
<template>
  <DatePicker
    :width="350"
    v-model="rangeTimeValue"
    range
    show-time
    enable-seconds
    multi-calendars
    format="yyyy-MM-dd HH:mm:ss"
    placeholder="请选择日期时间范围"
  />
</template>

预设范围

预设常用的日期范围以提高用户体验


Show Code
vue
<script setup lang="ts">
import { ref, watchEffect } from 'vue'
import { format, addDays, startOfMonth, endOfMonth, subMonths, startOfYear, endOfYear } from 'date-fns'
const rangeValue = ref<string[]>([format(new Date(), 'yyyy-MM-dd'), format(addDays(new Date(), 3), 'yyyy-MM-dd')])
const presetDates = ref([
  { label: 'Today', value: [new Date(), new Date()] },
  { label: 'This month', value: [startOfMonth(new Date()), endOfMonth(new Date())] },
  {
    label: 'Last month',
    value: [startOfMonth(subMonths(new Date(), 1)), endOfMonth(subMonths(new Date(), 1))],
  },
  { label: 'This year', value: [startOfYear(new Date()).getTime(), endOfYear(new Date()).getTime()] }
])
watchEffect(() => {
  console.log('rangeValue', rangeValue.value)
})
</script>
<template>
  <DatePicker
    :width="240"
    v-model="rangeValue"
    format="yyyy-MM-dd"
    range
    :preset-dates="presetDates"
    multi-calendars
    placeholder="请选择日期范围"
  />
</template>

自定义最长日期可选择范围

最长日期可选范围不超过七天


Show Code
vue
<script setup lang="ts">
import { ref, watchEffect } from 'vue'
import { format, addDays } from 'date-fns'
const maxRangeValue = ref<string[]>([format(new Date(), 'yyyy-MM-dd'), format(addDays(new Date(), 6), 'yyyy-MM-dd')])
watchEffect(() => {
  console.log('maxRangeValue', maxRangeValue.value)
})
</script>
<template>
  <DatePicker
    :width="240"
    v-model="maxRangeValue"
    format="yyyy-MM-dd"
    range
    :max-range="7"
    placeholder="请选择日期范围"
  />
</template>

时分选择器

Show Code
vue
<script setup lang="ts">
import { ref, watchEffect } from 'vue'
const timeValue = ref({
  hours: new Date().getHours(),
  minutes: new Date().getMinutes()
})
watchEffect(() => {
  console.log('timeValue', timeValue.value)
})
</script>
<template>
  <DatePicker
    :width="110"
    v-model="timeValue"
    mode="time"
    show-time
    mode-height="120"
    format="HH:mm"
    placeholder="请选择时间"
  />
</template>

时分秒选择器

Show Code
vue
<script setup lang="ts">
import { ref, watchEffect } from 'vue'
const secondsValue = ref({
  hours: new Date().getHours(),
  minutes: new Date().getMinutes(),
  seconds: new Date().getSeconds()
})
watchEffect(() => {
  console.log('secondsValue', secondsValue.value)
})
</script>
<template>
  <DatePicker
    :width="130"
    v-model="secondsValue"
    mode="time"
    format="HH:mm:ss"
    show-time
    enable-seconds
    mode-height="120"
    placeholder="请选择时间"
  />
</template>

时分秒范围选择器

Show Code
vue
<script setup lang="ts">
import { ref, watchEffect } from 'vue'
import { addHours, addMinutes, addSeconds } from 'date-fns'
const timeRangeValue = ref([
  {
    hours: new Date().getHours(),
    minutes: new Date().getMinutes(),
    seconds: new Date().getSeconds()
  },
  {
    hours: addHours(Date.now(), 1).getHours(),
    minutes: addMinutes(Date.now(), 10).getMinutes(),
    seconds: addSeconds(Date.now(), 30).getSeconds()
  }
])
watchEffect(() => {
  console.log('timeRangeValue', timeRangeValue.value)
})
</script>
<template>
  <DatePicker
    :width="200"
    v-model="timeRangeValue"
    mode="time"
    format="HH:mm:ss"
    show-time
    range
    enable-seconds
    mode-height="120"
    placeholder="请选择时间"
  />
</template>

周选择器

2025-03-24 ~ 2025-03-30
Show Code
vue
<script setup lang="ts">
import { ref, watchEffect } from 'vue'
import { startOfWeek, endOfWeek } from 'date-fns'
// startOfWeek & endOfWeek 默认以周日作为一周的开始,可以传递一个选项对象,以周一作为一周的开始:{ weekStartsOn: 1 }
const options: any = { weekStartsOn: 1 }
const weekValue = ref([startOfWeek(new Date(), options), endOfWeek(new Date(), options)])
watchEffect(() => {
  console.log('weekValue', weekValue.value)
})
</script>
<template>
  <Space vertical>
    <GradientText
      :size="24"
      :weight="600"
      :gradient="{
        deg: '90deg',
        from: '#09c8ce',
        to: '#eb2f96'
      }"
    >
      {{ format(weekValue[0], 'yyyy-MM-dd') + ' ~ ' + format(weekValue[1], 'yyyy-MM-dd') }}
    </GradientText>
    <DatePicker :width="170" v-model="weekValue" mode="week" format="yyyy年 第ww周" placeholder="请选择周" />
  </Space>
</template>

月选择器

Show Code
vue
<script setup lang="ts">
import { ref, watchEffect } from 'vue'
const monthValue = ref({
  year: new Date().getFullYear(),
  month: new Date().getMonth()
})
watchEffect(() => {
  console.log('monthValue', monthValue.value)
})
</script>
<template>
  <DatePicker :width="130" v-model="monthValue" mode="month" format="yyyy-MM" placeholder="请选择月" />
</template>

年选择器

Show Code
vue
<script setup lang="ts">
import { ref, watchEffect } from 'vue'
const yearValue = ref(new Date().getFullYear())
watchEffect(() => {
  console.log('yearValue', yearValue.value)
})
</script>
<template>
  <DatePicker :width="110" v-model="yearValue" mode="year" format="yyyy" placeholder="请选择年" />
</template>

APIs

DatePicker


更多使用 API 请参考 官方文档

参数说明类型默认值
width日期选择器宽度,单位 pxstring | number150
size日期选择器大小'small' | 'middle' | 'large''middle'
mode选择器模式'time' | 'date' | 'week' | 'month' | 'year''date'
format日期展示格式string | ((date: Date) => string) | ((dates: Date[]) => string)DefaultFormat
showTime是否增加时间选择booleanfalse
showToday是否展示”今天“按钮booleanfalse
range是否使用范围选择器booleanfalse
maxRange范围选择器最长日期可选择范围,单位天,仅当 range: true 时生效numberundefined
modelTypev-model 值类型,可选 timestamp: 时间戳、format: 字符串,modeweekyear 时,该配置不生效'timestamp' | 'format''format'
modelValue
v-model
双向绑定值number | string | object | arraynull

DefaultFormat Value

类型
Single picker'MM/dd/yyyy HH:mm'
Range picker'MM/dd/yyyy HH:mm - MM/dd/yyyy HH:mm'
Month picker'MM/yyyy'
Time picker'HH:mm'
Time picker range'HH:mm - HH:mm'
Week picker'ww-yyyy'

format 支持的格式化占位符列表

标识示例描述
yy23年,两位数
yyyy2023年,四位数
M1-12
MM01-12月,两位数
d1-31
dd01-31日,两位数
H0-23小时
HH00-23小时,两位数
m0-59分钟
mm00-59分钟,两位数
s0-59
ss00-59秒,两位数
w1-52第几周
ww01-52第几周,两位数

Released under the MIT License.