Pro 日期选择器

用于选择或输入日期（不含时刻）。需要同时选日期与时间请使用 DateTimePicker Pro；仅选时刻请使用 TimePicker Pro。

组件选型

组件	适用场景
DatePicker Pro（本文档）	日 / 周 / 月 / 年、多选、各类日期范围
DateTimePicker Pro	日期 + 时刻、日期时间范围
TimePicker Pro	仅时刻、时刻范围
DatePickerPanel Pro	无输入框，单独嵌入面板

通过 type 切换展示类型。Pro 版范围选择均为单面板 + 顶部 Tab（长滚动月历 / 年表），与经典 DatePicker 双面板不同。

WARNING

Pro 版面板通过虚拟滚动展示年/月列表，年份范围由 calendar-range 控制（默认当前年前后各 10 年）。若业务需要选择超出该范围的年份（如历史数据录入、出生日期），必须通过 calendar-range 显式指定 [startYear, endYear]，否则超出范围的年份不可见也不可选。

单点选择

日期 `date`

默认 type="date"。可用 shortcuts 配置快捷项，disabledDate 禁用部分日期。

largedefaultsmallmini

默认

带快捷选项

🎉 点击尾部

🎉 轻量化

禁用

vue

<template>
  <w-radio-group v-model="size" aria-label="size control">
    <w-radio-button value="large">large</w-radio-button>
    <w-radio-button value="default">default</w-radio-button>
    <w-radio-button value="small">small</w-radio-button>
    <w-radio-button value="mini">mini</w-radio-button>
  </w-radio-group>
  <div class="flex flex-wrap gap-4">
    <div class="block">
      <span class="demonstration">默认</span>
      <w-date-picker-pro
        v-model="value1"
        type="date"
        placeholder="请选择日期"
        :size="size"
      />
    </div>
    <div class="block">
      <span class="demonstration">带快捷选项</span>
      <w-date-picker-pro
        v-model="value2"
        type="date"
        format="MM-DD"
        placeholder="请选择日期"
        :disabled-date="disabledDate"
        :shortcuts="shortcuts"
        :size="size"
      />
    </div>
    <div class="block">
      <span class="demonstration">🎉 点击尾部</span>
      <w-date-picker-pro
        v-model="value3"
        type="date"
        format="YYYY-MM"
        placeholder="请选择日期"
        trigger-suffix
        :size="size"
      />
    </div>
    <div class="block">
      <span class="demonstration">🎉 轻量化</span>
      <w-date-picker-pro
        v-model="value3"
        type="date"
        placeholder="请选择日期"
        plain
        :size="size"
      />
    </div>
    <div class="block">
      <span class="demonstration">禁用</span>
      <w-date-picker-pro
        v-model="value3"
        disabled
        type="date"
        placeholder="请选择日期"
        :size="size"
      />
    </div>
    <div class="block">
      <span class="demonstration">禁用</span>
      <w-date-picker-pro
        v-model="value1"
        disabled
        type="date"
        placeholder="请选择日期"
        :size="size"
      />
    </div>
  </div>
</template>

<script lang="ts" setup>
import { ref } from 'vue'

const size = ref<'default' | 'large' | 'small'>('default')

const value1 = ref('')
const value2 = ref('')
const value3 = ref('2025-07-21')

const shortcuts = [
  {
    text: '今天',
    value: new Date(),
  },
  {
    text: '昨天',
    value: () => {
      const date = new Date()
      date.setTime(date.getTime() - 3600 * 1000 * 24)
      return date
    },
  },
  {
    text: '一周前',
    value: () => {
      const date = new Date()
      date.setTime(date.getTime() - 3600 * 1000 * 24 * 7)
      return date
    },
  },
]

const disabledDate = (time: Date) => {
  return time.getTime() > Date.now()
}
</script>

<style scoped>
.block {
  padding-top: 20px;
  text-align: center;
}

.demonstration {
  display: block;
  color: var(--w3-font-color-second);
  font-size: 14px;
  margin-bottom: 16px;
}
</style>

禁用日期 `disabled-date`

通过 disabled-date 函数控制哪些日期不可选，函数接收 Date 参数，返回 true 表示禁用。

禁用今天之后的日期

禁用今天之前的日期

禁用周末

周、月、年、多个日期

type 可选 week、month、year、dates 等。

周

多个日期

年

多个年

月

多个月

vue

<template>
  <div class="demo-date-picker">
    <div class="container">
      <div class="block">
        <span class="demonstration">周</span>
        <w-date-picker-pro
          v-model="value1"
          type="week"
          format="ww [周]"
          placeholder="选择周"
        />
      </div>
      <div class="block">
        <span class="demonstration">多个日期</span>
        <w-date-picker-pro
          v-model="value2"
          type="dates"
          placeholder="选择多个日期"
        />
      </div>
    </div>
    <div class="container">
      <div class="block">
        <span class="demonstration">年</span>
        <w-date-picker-pro v-model="value3" type="year" placeholder="选择年" />
      </div>
      <div class="block">
        <span class="demonstration">多个年</span>
        <w-date-picker-pro
          v-model="value4"
          type="years"
          placeholder="选择多个年"
        />
      </div>
    </div>
    <div class="container">
      <div class="block">
        <span class="demonstration">月</span>
        <w-date-picker-pro v-model="value5" type="month" placeholder="选择月" />
      </div>
      <div class="block">
        <span class="demonstration">多个月</span>
        <w-date-picker-pro
          v-model="value6"
          type="months"
          placeholder="选择多个月"
        />
      </div>
    </div>
  </div>
</template>

<script lang="ts" setup>
import { ref } from 'vue'

const value1 = ref('')
const value2 = ref('')
const value3 = ref('')
const value4 = ref('')
const value5 = ref('')
const value6 = ref('')
</script>

<style scoped>
.demo-date-picker {
  display: flex;
  width: 100%;
  padding: 0;
  flex-wrap: wrap;
}

.demo-date-picker .block {
  padding: 30px 0;
  text-align: center;
  flex: 1;
}

.demo-date-picker .container {
  flex: 1;
}

.demo-date-picker .demonstration {
  display: block;
  color: var(--w3-font-color-third);
  font-size: 14px;
  margin-bottom: 16px;
}
</style>

范围选择

以下类型的面板交互一致：无值时只能先选开始侧；选满开始、结束后形成范围；仅选开始未选结束就关闭时，输入框会恢复打开前状态。daterange 选完开始日期后会自动切到结束 Tab；详见各 demo 说明。

`type`	说明
`daterange`	日期范围
`monthrange`	月份范围
`yearrange`	年份范围

日期范围 `daterange`

单面板长滚动月历，Tab 切换开始/结束日期。选开始后开始框立即有值并自动进入结束侧；智能录入（默认开启）在开始日期录满后聚焦结束输入框。

largedefaultsmallmini

默认

快捷选项

🎉 轻量化

vue

<template>
  <w-radio-group v-model="size" aria-label="size control">
    <w-radio-button value="large">large</w-radio-button>
    <w-radio-button value="default">default</w-radio-button>
    <w-radio-button value="small">small</w-radio-button>
    <w-radio-button value="mini">mini</w-radio-button>
  </w-radio-group>
  <w-space class="flex">
    <div class="block">
      <span class="demonstration">默认</span>
      <w-date-picker-pro
        v-model="value1"
        type="daterange"
        range-separator="-"
        start-placeholder="开始日期"
        end-placeholder="结束日期"
        :size="size"
      />
    </div>
    <div class="block">
      <span class="demonstration">快捷选项</span>
      <w-date-picker-pro
        v-model="value2"
        type="daterange"
        range-separator="-"
        start-placeholder="开始日期"
        end-placeholder="结束日期"
        :shortcuts="shortcuts"
        :size="size"
      />
    </div>
  </w-space>
  <w-space class="flex">
    <div class="block">
      <span class="demonstration">🎉 轻量化</span>
      <w-date-picker-pro
        v-model="value3"
        plain
        type="daterange"
        range-separator="-"
        start-placeholder="开始日期"
        end-placeholder="结束日期"
        :shortcuts="shortcuts"
        :size="size"
      />
    </div>
  </w-space>
</template>

<script lang="ts" setup>
import { ref } from 'vue'

const size = ref<'default' | 'large' | 'small'>('default')

const value1 = ref('')
const value2 = ref('')
const value3 = ref('')

const shortcuts = [
  {
    text: '最近一周',
    value: () => {
      const end = new Date()
      const start = new Date()
      start.setTime(start.getTime() - 3600 * 1000 * 24 * 7)
      return [start, end]
    },
  },
  {
    text: '最近一个月',
    value: () => {
      const end = new Date()
      const start = new Date()
      start.setTime(start.getTime() - 3600 * 1000 * 24 * 30)
      return [start, end]
    },
  },
  {
    text: '最近三个月',
    value: () => {
      const end = new Date()
      const start = new Date()
      start.setTime(start.getTime() - 3600 * 1000 * 24 * 90)
      return [start, end]
    },
  },
]
</script>

<style scoped>
.block {
  padding-top: 20px;
  text-align: center;
  flex: 1;
}

.demonstration {
  display: block;
  color: var(--w3-font-color-second);
  font-size: 14px;
  margin-bottom: 16px;
}
</style>

月份范围 `monthrange`

单面板长滚动月历，Tab 切换开始/结束月份。

默认

快捷选项

年份范围 `yearrange`

单面板虚拟滚动年表，Tab 切换开始/结束年份。

默认

快捷选项

格式与绑定值

显示格式与 `value-format`

使用 format 指定输入框展示格式，使用 value-format 指定绑定值格式；不设置 value-format 时绑定值为 Date 对象。

Day.js 格式说明

格式	输出	描述
`YY`	18	两位数的年份
`YYYY`	2018	四位数的年份
`M`	1-12	月份，从 1 开始
`MM`	01-12	月份，两位数
`MMM`	Jan-Dec	简写的月份名称
`MMMM`	January-December	完整的月份名称
`D`	1-31	月份里的一天
`DD`	01-31	月份里的一天，两位数
`d`	0-6	一周中的一天，星期天是 0
`dd`	Su-Sa	最简写的一周中一天的名称
`ddd`	Sun-Sat	简写的一周中一天的名称
`dddd`	Sunday-Saturday	一周中一天的名称
`H`	0-23	小时
`HH`	00-23	小时，两位数
`h`	1-12	小时, 12 小时制
`hh`	01-12	Hours, 12 小时制, 两位数
`m`	0-59	分钟
`mm`	00-59	分钟，两位数
`s`	0-59	秒
`ss`	00-59	秒两位数
`SSS`	000-999	毫秒三位数
`Z`	+5:00	UTC 的偏移量
`ZZ`	+0500	UTC 的偏移量，数字前面加上 0
`A`	AM PM
`a`	am pm

WARNING

请一定要注意传入参数的大小写是否正确

Date object

value-format

Timestamp

`change` 附带格式化字符串 `emit-formatted-value`

开启后，change 事件的第二个参数为格式化字符串；v-model 仍为 Date 或 Date[]（未设置 value-format 时）。

日期选择器

周选择器

时间选择器

范围选择器

vue

<template>
  <w-space class="flex mb-8">
    <div class="block">
      <span class="demonstration">日期选择器</span>
      <w-date-picker-pro
        v-model="value1"
        type="date"
        format="YYYY-MM-DD"
        emit-formatted-value
        placeholder="请选择日期"
        @change="handleCurrentChange1"
      />
    </div>
    <div class="block">
      <span class="demonstration">周选择器</span>
      <w-date-picker-pro
        v-model="value2"
        type="week"
        format="ww [周]"
        emit-formatted-value
        placeholder="请选择周"
        @change="handleCurrentChange2"
      />
    </div>
    <div class="block">
      <span class="demonstration">时间选择器</span>
      <w-time-picker-pro
        v-model="value3"
        emit-formatted-value
        format="HH:mm:ss"
        placeholder="请选择时间"
        @change="handleCurrentChange3"
      />
    </div>
  </w-space>
  <w-space class="flex">
    <div class="block">
      <span class="demonstration">范围选择器</span>
      <w-date-picker-pro
        v-model="value4"
        type="daterange"
        range-separator="-"
        start-placeholder="开始日期"
        end-placeholder="结束日期"
        emit-formatted-value
        format="YYYY/MM/DD"
        @change="handleCurrentChange4"
      />
    </div>
  </w-space>
</template>

<script lang="ts" setup>
import { ref, watch } from 'vue'

const value1 = ref('')
const value2 = ref('')
const value3 = ref('')
const value4 = ref(['2025-07-01', '2025-08-30'])

watch(value4, (val, oldVal) => {
  console.log('数据变化：', val, oldVal)
})

const handleCurrentChange1 = (val: Date, format: string) => {
  console.log(`current date: ${val}, format: ${format}`)
}

const handleCurrentChange2 = (val: Date, format: string) => {
  console.log(`current date: ${val}, format: ${format}`)
}

const handleCurrentChange3 = (val: Date, format: string) => {
  console.log(`current date: ${val}, format: ${format}`)
}

const handleCurrentChange4 = (val: Date, format: string) => {
  console.log(`current date: ${val}, format: ${format}`)
}
</script>

<style scoped>
.block {
  padding-top: 20px;
  text-align: center;
}

.demonstration {
  display: block;
  color: var(--w3-font-color-second);
  font-size: 14px;
  margin-bottom: 16px;
}
</style>

打开时的默认日期 `default-value`

未选值时面板默认展示的日期；daterange 时作用于范围左侧（开始侧）。

设置默认值

日期范围

范围选中日期的默认时刻 `default-time`

仅对含时刻的范围类型生效（如 datetimerange，见 DateTimePicker Pro）。纯日期范围 daterange 一般无需配置。

自定义

前缀 / 后缀图标

后缀：默认显示日历图标（TimePicker 为时钟图标）；可用 suffix-icon 覆盖。有值且悬停时可清除时，清除按钮会暂时替换后缀图标。
前缀：默认无图标；设置 prefix-icon 后显示自定义前缀。

set suffix-icon

单元格内容 `default` 插槽

自定义结构需与默认单元格一致，否则样式可能不一致。

vue

<template>
  <div class="demo-date-picker">
    <w-date-picker-pro
      v-model="value"
      type="date"
      placeholder="请选择日期"
      format="YYYY/MM/DD"
      value-format="YYYY-MM-DD"
    >
      <template #default="cell">
        <div class="cell" :class="{ current: cell.isCurrent }">
          <span class="text">{{ cell.text }}</span>
          <span v-if="isHoliday(cell)" class="holiday" />
        </div>
      </template>
    </w-date-picker-pro>
    <w-date-picker-pro v-model="month" type="month" placeholder="请选择月份">
      <template #default="cell">
        <div
          class="w3-date-table-cell-pro"
          :class="{ current: cell.isCurrent }"
        >
          <span class="w3-date-table-cell-pro__text"
            >{{ cell.text + 1 }}期</span
          >
        </div>
      </template>
    </w-date-picker-pro>
    <w-date-picker-pro v-model="year" type="year" placeholder="请选择年份">
      <template #default="cell">
        <div
          class="w3-date-table-cell-pro"
          :class="{ current: cell.isCurrent }"
        >
          <span class="w3-date-table-cell-pro__text">{{ cell.text + 1 }}y</span>
        </div>
      </template>
    </w-date-picker-pro>
  </div>
</template>

<script lang="ts" setup>
import { ref } from 'vue'

const value = ref('2021-10-29')
const month = ref('')
const year = ref('')
const holidays = [
  '2021-10-01',
  '2021-10-02',
  '2021-10-03',
  '2021-10-04',
  '2021-10-05',
  '2021-10-06',
  '2021-10-07',
]

const isHoliday = ({ dayjs }) => {
  return holidays.includes(dayjs.format('YYYY-MM-DD'))
}
</script>

<style scoped>
.demo-date-picker {
  display: flex;
  justify-content: space-between;
}

.cell {
  height: 30px;
  padding: 3px 0;
  box-sizing: border-box;
}

.cell .text {
  width: 24px;
  height: 24px;
  display: block;
  margin: 0 auto;
  line-height: 24px;
  position: absolute;
  left: 50%;
  transform: translateX(-50%);
  border-radius: 50%;
}

.cell.current .text {
  background: #626aef;
  color: #fff;
}

.cell .holiday {
  position: absolute;
  width: 6px;
  height: 6px;
  background: var(--w3-color-danger);
  border-radius: 50%;
  bottom: 0px;
  left: 50%;
  transform: translateX(-50%);
}
</style>

单元格数据类型：

interface DateCell {
  column: number
  customClass: string
  disabled: boolean
  end: boolean
  inRange: boolean
  row: number
  selected: Dayjs
  isCurrent: boolean
  isSelected: boolean
  start: boolean
  text: number
  timestamp: number
  date: Date
  dayjs: Dayjs
  type: 'normal' | 'today' | 'week' | 'next-month' | 'prev-month'
}

国际化

由于 WinDesign Next 的默认语言为中文，如果你需要设置其它的语言，请参考国际化文档。

要注意的是：日期相关的文字（月份，每一周的第一天等等）也都是通过国际化来配置的。

API

属性

参数	说明	类型	默认值	Version
model-value / v-model	绑定值，如果它是数组，长度应该是 2	`number` / `string` / `Date` / `array`	''
type	显示类型	`enum`	date
readonly	只读	`boolean`	false
disabled	禁用	`boolean`	false
size	输入框尺寸	`enum`	—
editable	文本框可输入	`boolean`	true
clearable	是否显示清除按钮	`boolean`	true
placeholder	非范围选择时的占位内容	`string`	''
start-placeholder	范围选择时开始日期的占位内容	`string`	—
end-placeholder	范围选择时结束日期的占位内容	`string`	—
format	输入框显示格式	参见格式与绑定值	`YYYY-MM-DD`（按 type）
value-format	绑定值格式；不指定则为 `Date`	参见格式与绑定值	—
date-format	面板内日期展示格式	`string`	—
time-format	面板内时间展示格式（`datetime` / `datetimerange`）	`string`	—
default-value	打开面板时默认展示的日期	`object`	—
default-time	范围选中日期使用的当日内时刻（`datetimerange` 等）	`object`	—
range-separator	范围分隔符	`string`	`-`
calendar-range	Pro 面板年份窗口 `[startYear, endYear]`	`array`	当前年 ±10
persistent	Pro 关闭后是否保留下拉 DOM；默认销毁以优化性能	`boolean`	false
manual-input	Pro 是否启用智能分块手动录入	`boolean`	true
automatic-dropdown	聚焦输入框时是否自动展开面板	`boolean`	true
prefix-icon	自定义前缀图标；未设置时不显示	`string` / `object`	—
suffix-icon	自定义后缀图标；未设置时默认为日历/时钟图标	`string` / `object`	—
clear-icon	自定义清除图标	`string` / `object`	`CircleCloseFilled`
disabled-date	判断日期是否禁用	`Function`	—
disabled-hours	禁用小时（`datetime` / `datetimerange`）	`Function`	—
disabled-minutes	禁用分钟（`datetime` / `datetimerange`）	`Function`	—
disabled-seconds	禁用秒（`datetime` / `datetimerange`）	`Function`	—
shortcuts	快捷选项	`array`	`[]`
cell-class-name	单元格自定义类名	`Function`	—
arrow-control	时间列是否使用箭头切换（含时刻的类型）	`boolean`	false
show-week-number	是否显示周数	`boolean`	false
show-footer	是否显示面板页脚	`boolean`	true
show-confirm	是否显示确定按钮	`boolean`	true
show-now	是否显示「此刻」按钮（含时刻的类型）	`boolean`	true
popper-class	下拉层类名	`string`	—
popper-style	下拉层样式	`object`	—
popper-options	popper.js 配置	`object`	`{}`
teleported	是否使用 teleport；为 `true` 时下拉层挂载到 `append-to` 指定位置	`boolean`	true
append-to	下拉层挂载到哪个 DOM 元素	`string`	—
placement	下拉层位置	`Placement`	`bottom-start`
fallback-placements	下拉层备选位置	`array`	见 popper 默认
id	原生 `id`	`string` / `array`	—
name	原生 `name`	`string` / `array`	—
tabindex	输入框 `tabindex`	`string` / `number`	`0`
aria-label	无障碍标签	`string`	—
validate-event	是否触发表单校验	`boolean`	true
empty-values	空值配置，见 Config Provider	`array`	—
value-on-clear	清空时的值，见 Config Provider	`string` / `number` / `boolean` / `Function`	—
trigger-suffix	仅点击后缀图标时打开面板	`boolean`	false	V0.0.8
plain	朴素样式	`boolean`	false	V0.0.8
emit-formatted-value	`change` 是否返回格式化字符串	`boolean`	false	V0.0.8

经典版有、Pro 版无需使用的属性

属性	说明
`unlink-panels`	经典范围双面板联动；Pro 均为单面板 + Tab，无此属性
`single-panel`	传入无效，Pro 范围布局已固定为单面板
`prev-month` / `next-month` 等插槽	面板导航插槽，Pro 不支持，见下方插槽

事件

事件名	说明	类型
change	用户确认选定的值时触发	`Function`
blur	在组件 Input 失去焦点时触发	`Function`
focus	在组件 Input 获得焦点时触发	`Function`
clear	可清空的模式下用户点击清空按钮时触发	`Function`
calendar-change	在日历所选日期更改时触发	`Function`
panel-change	当日期面板改变时触发。	`Function`
visible-change	当 DatePicker Pro 的下拉列表出现/消失时触发	`Function`

插槽

Pro 版不支持经典版 prev-month / next-month / prev-year / next-year 面板导航插槽；面板导航使用内置图标。输入框图标请用 prefix-icon、suffix-icon。

名称	说明
default	自定义单元格内容
range-separator	自定义范围分割符内容
sidebar	侧边栏快捷选项区域

暴露

方法名	说明	类型
focus	使组件获取焦点	`Function`
blur	使组件失去焦点	`Function`
handleOpen	打开日期选择器弹窗	`Function`
handleClose	关闭日期选择器弹窗	`Function`

类型声明

显示类型声明

import type { Options as PopperOptions } from '@popperjs/core'

type TimeLikeType = 'datetime' | 'datetimerange'

type Placement =
  | 'top'
  | 'top-start'
  | 'top-end'
  | 'bottom'
  | 'bottom-start'
  | 'bottom-end'
  | 'left'
  | 'left-start'
  | 'left-end'
  | 'right'
  | 'right-start'
  | 'right-end'

Pro 日期面板

Pro 日期时间

Pro 日期选择器 ​

单点选择 ​

日期 date ​

禁用日期 disabled-date ​

周、月、年、多个日期 ​

范围选择 ​

日期范围 daterange ​

月份范围 monthrange ​

年份范围 yearrange ​

格式与绑定值 ​

显示格式与 value-format ​

change 附带格式化字符串 emit-formatted-value ​

打开时的默认日期 default-value ​

范围选中日期的默认时刻 default-time ​

自定义 ​

前缀 / 后缀图标 ​

单元格内容 default 插槽 ​

国际化 ​

API ​

属性 ​

事件 ​

插槽 ​

暴露 ​

类型声明 ​

Pro 日期选择器

单点选择

日期 `date`

禁用日期 `disabled-date`

周、月、年、多个日期

范围选择

日期范围 `daterange`

月份范围 `monthrange`

年份范围 `yearrange`

格式与绑定值

显示格式与 `value-format`

`change` 附带格式化字符串 `emit-formatted-value`

打开时的默认日期 `default-value`

范围选中日期的默认时刻 `default-time`

自定义

前缀 / 后缀图标

单元格内容 `default` 插槽

国际化

API

属性

事件

插槽

暴露

类型声明