naive-ui Date Picker 组件完全指南:11 种类型、格式化绑定与面板定制

原创2026-09-20 23:41:441,722 阅读
文章标签:前端UI组件设计系统

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 决定绑定字符串的格式,默认跟随 format prop;
  • 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 的实际行为。

十二、实战要点小结

  1. 默认绑定时间戳:单值 number、区间 [number, number];需要字符串时改用 v-model:formatted-value + value-format。
  2. 11 种类型按需选择:date / datetime / daterange / datetimerange / month / monthrange / year / yearrange / quarter / quarterrange / week,从 config.ts 的类型定义即可确认全部取值。
  3. 格式分三层:输入框 format、绑定值 value-format、面板内 month-format / year-format / quarter-format / calendar-* 系列,全部遵循 date-fns v2 令牌。
  4. 禁用分两维:日期粒度用 is-date-disabled(2.37.1 起带 detail 上下文),时间粒度用 is-time-disabled(小时/分钟/秒三函数),全局开关用 disabled。
  5. 快捷方式支持静态与函数:函数形态每次点击动态计算,适合相对时间;区间类型需返回 [number, number]。
  6. 操作按钮按类型有默认集:['clear', 'now']、['clear', 'now', 'confirm'] 或 ['clear', 'confirm'],传 null 隐藏,2.40.0 起可通过 clear / confirm / now 插槽重绘按钮。
  7. 面板可脱离输入框:panel 纯面板模式、placement 控制方位、to 控制挂载容器、show + on-update:show 控制受控显隐。
  8. 版本意识:大量能力有版本门槛,如 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 行为最直观的参考资料。

登录后查看全文
naive-ui