naive-ui Date Picker 组件完全指南:11 种类型、格式化绑定与面板定制
naive-ui Date Picker 组件完全指南:11 种类型、格式化绑定与面板定制
本文以 naive-ui 官方 Date Picker 演示文档(src/date-picker/demos/enUS/index.demo-entry.md)为骨架,结合组件源码(props.ts、config.ts)与 27 个可运行演示,系统讲解该组件的时间戳绑定模型、11 种日期/时间类型、格式定制、快捷方式、禁用校验、操作按钮、面板模式与事件体系。读完本文,你将掌握在 Vue 3 + TypeScript 项目中完整驾驭 naive-ui Date Picker 的全部能力。
一、组件定位与核心数据模型
naive-ui 的 NDatePicker 是一个功能全面的日期时间选择器。它最核心的设计决策是:绑定值默认是时间戳(number),而不是字符串。选择单个日期时值为 number,选择区间时值为 [number, number]。
从 date.demo.vue 可以看到最基础用法:
<script lang="ts" setup>
import { ref } from 'vue'
const timestamp = ref(1183135260000)
</script>
<template>
<n-date-picker v-model:value="timestamp" type="date" />
<pre>{{ JSON.stringify(timestamp) }}</pre>
</template>
其中 1183135260000 是 2007-06-30 12:41(UTC)附近的一个毫秒级时间戳。组件通过 v-model:value 双向绑定时间戳,页面上会实时打印当前值。
区间类型(daterange、datetimerange 等)则绑定二元组,见 daterange.demo.vue:
<script lang="ts" setup>
import { ref } from 'vue'
const range = ref<[number, number]>([1183135260000, Date.now()])
</script>
<template>
<n-date-picker v-model:value="range" type="daterange" clearable />
<pre>{{ JSON.stringify(range) }}</pre>
</template>
组件的类型系统定义在 config.ts 中,共 11 种取值:
export type DatePickerType
= | 'date'
| 'datetime'
| 'daterange'
| 'datetimerange'
| 'month'
| 'year'
| 'quarter'
| 'monthrange'
| 'quarterrange'
| 'yearrange'
| 'week'
这 11 种类型分别对应 index.demo-entry.md 中 date、datetime、daterange、datetimerange、month、monthrange、year、yearrange、quarter、quarterrange、week 这 11 个独立演示,覆盖了从"选择某一天"到"选择某周"的几乎所有时间粒度。
二、格式化值绑定:v-model:formatted-value
虽然时间戳是默认绑定值,但真实业务中后端接口常常要求字符串格式的日期。naive-ui 从 2.24.0 起提供 v-model:formatted-value 与 value-format 组合,让绑定值直接是格式化后的字符串。
datetimeformat.demo.vue 中官方演示如下:
<script lang="ts" setup>
import { ref } from 'vue'
const formattedValue = ref('2007-06-30 12:08:55')
</script>
<template>
<pre>{{ formattedValue }}</pre>
<n-date-picker
v-model:formatted-value="formattedValue"
value-format="yyyy-MM-dd HH:mm:ss"
type="datetime"
clearable
/>
</template>
要点:
value-format决定绑定字符串的格式,默认跟随formatprop;on-update:formatted-value回调会同时给出(value: string | null, timestampValue: number | null),即格式化字符串与对应时间戳;- 对应的
on-update:value回调则给出(value: number | null, formattedValue: string | null),即时间戳与格式化字符串。
也就是说,无论你绑定 value 还是 formatted-value,回调里都能同时拿到两种形态的值,方便直接送给后端或展示层。
三、11 种类型逐一拆解
官方为每种类型都准备了独立演示,下面按粒度分组说明。
3.1 日期类:date 与 datetime
type="date":选择单日,默认format为'yyyy-MM-dd',默认placeholder为'Select Date',默认 actions 为['clear', 'now'];type="datetime":在日期基础上追加时分秒,默认format为'yyyy-MM-dd HH:mm:ss',默认placeholder为'Select Date and Time',默认 actions 为['clear', 'now', 'confirm'],并额外支持default-time、is-time-disabled、time-picker-props等时间相关能力。
datetime.demo.vue 展示了最简单形态:
<template>
<n-date-picker v-model:value="timestamp" type="datetime" clearable />
</template>
3.2 区间类:daterange 与 datetimerange
daterange:选择起止日期,默认 placeholder 为'Start Date'/'End Date',actions 为['clear', 'confirm'];datetimerange:选择起止日期时间,placeholder 为'Start Date and Time'/'End Date and Time'。
区间类型额外提供以下 props(详见文档 API 表的 DateRange / DateTimeRange 小节):
| Prop | 默认值 | 说明 |
|---|---|---|
start-placeholder / end-placeholder |
见上 | 起止输入框的提示文案 |
separator |
内置图标 | 起止输入框之间的分隔符,也可用 separator slot 自定义 |
default-calendar-start-time / default-calendar-end-time |
undefined |
面板默认起始/结束月份的时间戳 |
bind-calendar-months |
false |
面板两个日历月份是否连续(2.28.3+) |
close-on-select |
false |
选完区间后是否自动收起面板 |
update-value-on-close |
false |
是否在关闭时才把值写回(配合确认动作) |
3.3 月/年/季度类
type="month":默认format为'yyyy-MM',placeholder 为'Select Month';type="year":默认format为'yyyy',placeholder 为'Select Year';type="quarter":默认format为'yyyy-qqq'(2.22.0 起提供);monthrange、quarterrange、yearrange:对应的区间形态,2.28.3 起提供,默认 placeholder 为'Start Month'/'End Month'等。
month.demo.vue 还展示了面板内项目格式的定制:
<template>
<n-space vertical>
<n-date-picker v-model:value="timestamp" type="month" clearable />
<n-date-picker
v-model:value="timestamp"
type="month"
format="y MMM"
month-format="MMM"
clearable
/>
</n-space>
</template>
这里 format="y MMM" 控制输入框显示,month-format="MMM" 控制面板中月份格子的显示(如 "Jun")。同理,year-format(默认 'y')与 quarter-format(默认 'Q'Q)分别控制面板中年份、季度的显示格式(2.37.0+)。
3.4 周类型:week
type="week"(2.37.0+)用于选择某一周,默认 format 为 'YYYY-w'(en-US,随 locale 变化),placeholder 为 'Select Week'。week 类型同样支持 default-calendar-start-time 与 clear/now actions。
四、格式体系:format、value-format 与面板内格式
naive-ui 的格式统一采用 date-fns v2 的令牌语法(如 yyyy、MM、dd、HH、mm、ss),这套规则贯穿输入框与面板。
4.1 输入框格式 format
format 决定输入框内展示的格式,各类型默认值汇总:
| 类型 | 默认 format |
|---|---|
| date / daterange | 'yyyy-MM-dd' |
| datetime / datetimerange | 'yyyy-MM-dd HH:mm:ss' |
| month / monthrange | 'yyyy-MM' |
| year / yearrange | 'yyyy' |
| quarter / quarterrange | 'yyyy-qqq' |
| week | 'YYYY-w'(locale 相关) |
format.demo.vue 演示了自定义格式 'yyyy/MM/dd - HH:mm':
<script lang="ts" setup>
import { ref } from 'vue'
const timestamp = ref(null)
const timestamp2 = ref(1183135260000)
const format = 'yyyy/MM/dd - HH:mm'
</script>
<template>
<n-space vertical>
<n-date-picker v-model:value="timestamp" type="datetime" clearable :format="format" />
<n-date-picker v-model:value="timestamp2" type="datetime" :format="format" clearable />
</n-space>
</template>
注意 format 只影响显示,不影响绑定值——绑定值仍是时间戳。
4.2 绑定值格式 value-format
value-format(2.24.0+)与 v-model:formatted-value 搭配使用,默认"跟随 format prop"。它决定了你通过 formatted-value 拿到的字符串长什么样,例如 value-format="yyyy-MM-dd HH:mm:ss" 会得到 '2007-06-30 12:08:55' 这样的值。
4.3 面板内格式族(2.40.2+)
文档 API 表开头的 General Props 中有一组 2.40.2 引入的面板格式定制 props:
| Prop | 默认值 | 作用 |
|---|---|---|
calendar-day-format |
undefined |
弹出面板内星期几的显示格式 |
calendar-header-year-format |
undefined |
面板日历头部年份格式 |
calendar-header-month-format |
undefined |
面板日历头部月份格式 |
calendar-header-month-before-year |
undefined |
头部是否"月在前、年在后" |
calendar-header-month-year-separator |
' ' |
头部月与年之间的分隔符 |
date-format |
undefined |
面板内日期输入格式 |
time-picker-format |
undefined |
datetime/datetimerange 面板内时间选择器的绑定值格式(2.38.2+) |
month-format / year-format / quarter-format |
'M' / 'y' / 'Q'Q |
面板内月/年/季度格子格式(2.37.0+) |
4.4 周起始日与年份范围
first-day-of-week:取值0 | 1 | ... | 6,0 表示周一(注意与常见习惯不同,这里 0 是周一),默认跟随 locale;year-range:月份/年份面板中可选的年份范围,默认<a href="https://link.gitcode.com/i/c53b53374af2604a25f92dc7cb752f2c" target="_blank">1901, 2100](2.40.0+),在 [props.ts 中以函数形式给出默认值。
五、快捷方式 shortcuts
shortcuts 允许在面板左侧渲染自定义快捷按钮,值为 Record<string, number | (() => number)>(单值类型)或 Record<string, [number, number] | (() => [number, number])>(区间类型)。既可以直接写死时间戳,也可以传函数动态计算。
shortcuts.demo.vue 给出了完整示例:
<script lang="ts" setup>
import { ref } from 'vue'
const ts1 = ref(null)
const ts2 = ref(1183135260000)
const range1 = ref(null)
const range2 = ref(null)
const shortcuts = {
'Honey birthday': 1631203200000,
Yesterday: () => new Date().getTime() - 24 * 60 * 60 * 1000
}
const rangeShortcuts = {
'Happy holiday': [1629216000000, 1631203200000] as const,
'Last 2 hours': () => {
const cur = new Date().getTime()
return [cur - 2 * 60 * 60 * 1000, cur] as const
}
}
</script>
<template>
<n-space vertical>
<n-date-picker v-model:value="ts1" type="date" :shortcuts="shortcuts" />
<n-date-picker v-model:value="ts2" type="datetime" :shortcuts="shortcuts" />
<n-date-picker v-model:value="range1" type="daterange" :shortcuts="rangeShortcuts" />
<n-date-picker v-model:value="range2" type="datetimerange" :shortcuts="rangeShortcuts" />
</n-space>
</template>
函数形式的快捷方式每次点击都会重新求值,特别适合"昨天""最近 2 小时"这类相对时间;静态时间戳则适合"节日""发薪日"这类固定日期。
六、禁用与校验:disabled、is-date-disabled、is-time-disabled
6.1 整体禁用
disabled(默认 false)直接禁用整个选择器,disabled.demo.vue 展示了各类型下禁用态的外观。
6.2 日期级禁用 is-date-disabled
is-date-disabled 是"某一天/某一月/某一年是否可选"的校验函数。单值类型(date/datetime/month/year/quarter)签名自 2.37.1 起携带 detail 参数:
(current: number, detail: {
type: 'date', year: number, month: number, date: number
} | { type: 'month', year: number, month: number }
| { type: 'year', year: number }
| { type: 'quarter', year: number, quarter: number }
| { type: 'input' }
) => boolean
区间类型(daterange/datetimerange)签名则携带选中阶段:
(current: number, phase: 'start' | 'end', value: [number, number] | null) => boolean
典型用途:禁止选择周末、禁止选择未来日期、禁止早于某个基准日等。disabled.demo.vue 与 disabled-time.demo.vue 分别演示了单值与区间的禁用场景。
6.3 时间级禁用 is-time-disabled
is-time-disabled 用于 datetime / datetimerange 类型,按"小时/分钟/秒"三个粒度分别返回禁用函数:
(current: number) => {
isHourDisabled?: () => boolean
isMinuteDisabled?: () => boolean
isSecondDisabled?: () => boolean
}
区间类型签名额外接收 phase: 'start' | 'end' 与当前 value: [number, number],且禁用函数内收到 null 表示选择器值仍为空。典型用途:只允许选择工作时段、限制开始时间必须早于结束时间等。函数内部拿到的时间戳可以直接用 new Date(current).getHours() 等 API 做判断。
6.4 默认时间 default-time
default-time(2.22.0,2.43.2 起支持函数)为选中日期时"附带"的默认时刻,格式为 HH:mm:ss:
datetime类型:string | (timestamp: number) => string;datetimerange类型:string | Array<string | undefined> | (timestamp: number, position: "start" | "end", value: [number, number] | null) => string,数组形式可分别为起止时间指定默认时刻。
官方演示 default-time.demo.vue 展示了"选日期自动带上 00:00:00 / 23:59:59"之类的常见需求。
七、操作按钮 actions 与底部插槽
actions 决定面板底部的操作按钮,按类型默认值不同:
| 类型 | 默认 actions |
|---|---|
| date / year / week | ['clear', 'now'] |
| datetime / month / quarter | ['clear', 'now', 'confirm'] |
| daterange / datetimerange / monthrange / quarterrange / yearrange | ['clear', 'confirm'] |
传 null 可隐藏所有按钮。actions.demo.vue 演示了 actions 的裁剪效果(例如只保留 confirm)。
2.40.0 起,这些按钮可通过插槽深度定制:
- 单值类型(Date / Year / QuarterRange / Week):
clear(参数{ onClear, text })、now(参数{ onNow, text }); - 区间类型(DateRange / DateTimeRange / MonthRange / YearRange):
clear、confirm(参数{ onConfirm, disabled, text }); - 三按钮类型(DateTime / Month / Quarter):
clear、confirm、now三者齐全。
另外 footer 插槽可向面板底部追加自定义内容(footerslot.demo.vue),date-icon(2.29.0+)、separator(2.29.0+)、next-month / prev-month / next-year / prev-year(2.33.4+)分别定制输入框图标、区间分隔符与面板翻页图标。
八、面板模式、定位与弹层容器
8.1 纯面板模式 panel
panel(2.29.1+)让 DatePicker 脱离输入框,直接以内嵌面板形式渲染,适合放进弹窗或自定义交互中。官方 panel.demo.vue 仅一行:
<template>
<n-date-picker panel type="date" />
</template>
8.2 弹层定位 placement
placement(2.25.0+)控制面板相对输入框的弹出方位,支持全部 12 个方向('top-start' | 'top' | 'top-end' | 'right-start' | 'right' | 'right-end' | 'bottom-start' | 'bottom' | 'bottom-end' | 'left-start' | 'left' | 'left-end'),默认 'bottom-start'。
8.3 弹层容器 to
to 指定面板挂载的容器节点,类型为 string | HTMLElement | false,默认 body;传 false 则面板不脱离原位置渲染(与 panel 模式配合可避免定位问题)。
8.4 受控显隐 show
show(2.28.3+)配合 on-update:show 实现面板展开/收起的受控管理;close-on-select 让"选完即关"(对区间类型尤其重要);update-value-on-close 则把值写入时机推迟到面板关闭时(见 update-on-close.demo.vue)。
九、尺寸、状态与输入行为
size:'small' | 'medium' | 'large',默认'medium'(size.demo.vue);status(2.27.0+):'success' | 'warning' | 'error',用于表单校验态展示,可与 NForm 的校验联动(status.demo.vue);clearable:是否显示清空按钮(默认false);input-readonly:给输入框加readonly属性,移动端可避免弹出软键盘;icon插槽 /date-icon插槽:分别定制整体输入框图标与日期图标(icon.demo.vue);focus/blur方法(2.24.2+):通过模板 ref 调用pickerRef.value.focus()手动聚焦或失焦(focus.demo.vue);to、panel与close-panel-on-select的完整联动见 close-panel-on-select.demo.vue。
十、事件体系一览
事件回调在 props.ts 中统一声明,除 onFocus/onBlur 接收 FocusEvent 外,其余回调签名如下:
| 事件 | 签名 | 版本 |
|---|---|---|
on-update:value |
(value: number | null, formattedValue: string | null) => void |
formattedValue 参数 2.24.0+ |
on-update:formatted-value |
(value: string | null, timestampValue: number | null) => void |
2.24.0+ |
on-confirm |
(value: number | [number, number] | null, formattedValue: string | [string, string] | null) => void |
2.28.3+ |
on-clear |
() => void |
2.28.3+ |
on-update:show |
(show: boolean) => void |
2.28.3+ |
on-next-month / on-prev-month / on-next-year / on-prev-year |
() => void |
2.37.0+ |
on-focus / on-blur |
(e: FocusEvent) => void |
— |
区间类型的 on-update:value 为 (value: <a href="https://link.gitcode.com/i/e2d71e01363295c4cf6f0baaa9b68104" target="_blank">number, number] | null, formattedValue: [string, string] | null) => void。[events.demo.vue 集中演示了这些事件的触发时机。
注意:文档中还存在一个 deprecated 的 onChange,它等价于 on-update:value,新代码请直接使用 v-model:value 或 on-update:value。
十一、源码级实现印证
从源码看,组件的全部 props 定义于 src/date-picker/src/props.ts:其中 fastYearSelect / fastMonthSelect(2.44.0+,选完年份/月份后自动关闭年/月面板)等均为布尔开关;timePickerProps 接受单个 TimePickerProps 或二元组 [TimePickerProps, TimePickerProps](分别作用于 datetimerange 的起止时间选择器);defaultTime 的类型是 [Number, String, Array, Function] 的多态 PropType,与文档中"字符串 / 数组 / 函数"三种形态一一对应。
组件主入口 DatePicker.tsx 与内部面板目录 src/date-picker/src/panel 共同完成了"输入框 + 弹出面板 + 快捷栏 + 操作按钮"的整体组装;MONTH_ITEM_HEIGHT = 40 定义于 config.ts,是月份面板格子高度的实现常量(源码注释也提示未来可能开放自定义)。此外 interface.ts 与 public-types.ts 定义了 Value、FormattedValue、Shortcuts、IsDateDisabled、IsTimeDisabled、DefaultTime 等公共类型,供二次封装或类型推导使用;组件的单元测试位于 src/date-picker/tests,可进一步验证各 props 的实际行为。
十二、实战要点小结
- 默认绑定时间戳:单值
number、区间[number, number];需要字符串时改用v-model:formatted-value+value-format。 - 11 种类型按需选择:
date/datetime/daterange/datetimerange/month/monthrange/year/yearrange/quarter/quarterrange/week,从 config.ts 的类型定义即可确认全部取值。 - 格式分三层:输入框
format、绑定值value-format、面板内month-format/year-format/quarter-format/calendar-*系列,全部遵循 date-fns v2 令牌。 - 禁用分两维:日期粒度用
is-date-disabled(2.37.1 起带detail上下文),时间粒度用is-time-disabled(小时/分钟/秒三函数),全局开关用disabled。 - 快捷方式支持静态与函数:函数形态每次点击动态计算,适合相对时间;区间类型需返回
[number, number]。 - 操作按钮按类型有默认集:
['clear', 'now']、['clear', 'now', 'confirm']或['clear', 'confirm'],传null隐藏,2.40.0 起可通过clear/confirm/now插槽重绘按钮。 - 面板可脱离输入框:
panel纯面板模式、placement控制方位、to控制挂载容器、show+on-update:show控制受控显隐。 - 版本意识:大量能力有版本门槛,如
panel需 2.29.1+、status需 2.27.0+、fast-year-select/fast-month-select需 2.44.0+、面板格式族需 2.40.2+,升级组件时请对照文档 Version 列核验。
所有演示代码均可在仓库 src/date-picker/demos/enUS 目录下直接查阅与运行,是理解每个 props 行为最直观的参考资料。