DatePicker日期选择框

输入或选择日期的控件。

何时使用

当用户需要输入一个日期，可以点击标准输入框，弹出日期面板进行选择。

  1. import { NzDatePickerModule } from 'ng-zorro-antd/date-picker';

代码演示

DatePicker日期选择框 - 图1

基本

最简单的用法，在浮层中可以选择或者输入日期。

  1. import { Component } from '@angular/core';
  2. import getISOWeek from 'date-fns/getISOWeek';
  3. import { en_US, NzI18nService, zh_CN } from 'ng-zorro-antd/i18n';
  5. @Component({
  6.   selector: 'nz-demo-date-picker-basic',
  7.   template: `
  8.     <nz-date-picker [(ngModel)]="date" (ngModelChange)="onChange($event)"></nz-date-picker>
  9.     <br />
  10.     <nz-date-picker nzMode="week" [(ngModel)]="date" (ngModelChange)="getWeek($event)"></nz-date-picker>
  11.     <br />
  12.     <nz-date-picker nzMode="month" [(ngModel)]="date" (ngModelChange)="onChange($event)"></nz-date-picker>
  13.     <br />
  14.     <nz-date-picker nzMode="year" [(ngModel)]="date" (ngModelChange)="onChange($event)"></nz-date-picker>
  15.     <br />
  16.     <button nz-button nzType="default" (click)="changeLanguage()">Switch language for all pickers</button>
  17.   `,
  18.   styles: [
  19.     `
  20.       nz-date-picker {
  21.         margin: 0 8px 12px 0;
  22.       }
  23.     `
  24.   ]
  25. })
  26. export class NzDemoDatePickerBasicComponent {
  27.   date = null;
  28.   isEnglish = false;
  30.   constructor(private i18n: NzI18nService) {}
  32.   onChange(result: Date): void {
  33.     console.log('onChange: ', result);
  34.   }
  36.   getWeek(result: Date): void {
  37.     console.log('week: ', getISOWeek(result));
  38.   }
  40.   changeLanguage(): void {
  41.     this.i18n.setLocale(this.isEnglish ? zh_CN : en_US);
  42.     this.isEnglish = !this.isEnglish;
  43.   }
  44. }

DatePicker日期选择框 - 图2

日期格式

使用 nzFormat 属性，可以自定义日期显示格式。

  1. import { Component } from '@angular/core';
  3. @Component({
  4.   selector: 'nz-demo-date-picker-format',
  5.   template: `
  6.     <nz-date-picker [nzFormat]="dateFormat"></nz-date-picker>
  7.     <br />
  8.     <nz-date-picker nzMode="month" [nzFormat]="monthFormat"></nz-date-picker>
  9.     <br />
  10.     <nz-range-picker [nzFormat]="dateFormat"></nz-range-picker>
  11.   `,
  12.   styles: [
  13.     `
  14.       nz-date-picker,
  15.       nz-range-picker {
  16.         margin: 0 8px 12px 0;
  17.       }
  18.     `
  19.   ]
  20. })
  21. export class NzDemoDatePickerFormatComponent {
  22.   dateFormat = 'yyyy/MM/dd';
  23.   monthFormat = 'yyyy/MM';
  24. }

DatePicker日期选择框 - 图3

日期时间选择

增加选择时间功能，当 nzShowTime 为一个对象时，其属性会传递给内建的 TimePicker。

  1. import { Component } from '@angular/core';
  3. @Component({
  4.   selector: 'nz-demo-date-picker-time',
  5.   template: `
  6.     <nz-date-picker
  7.       nzShowTime
  8.       nzFormat="yyyy-MM-dd HH:mm:ss"
  9.       ngModel
  10.       (ngModelChange)="onChange($event)"
  11.       (nzOnOk)="onOk($event)"
  12.     ></nz-date-picker>
  13.     <br />
  14.     <nz-range-picker
  15.       [nzShowTime]="{ nzFormat: 'HH:mm' }"
  16.       nzFormat="yyyy-MM-dd HH:mm"
  17.       ngModel
  18.       (ngModelChange)="onChange($event)"
  19.       (nzOnCalendarChange)="onCalendarChange($event)"
  20.       (nzOnOk)="onOk($event)"
  21.     ></nz-range-picker>
  22.   `,
  23.   styles: [
  24.     `
  25.       nz-date-picker,
  26.       nz-range-picker {
  27.         margin: 0 8px 12px 0;
  28.       }
  29.     `
  30.   ]
  31. })
  32. export class NzDemoDatePickerTimeComponent {
  33.   onChange(result: Date): void {
  34.     console.log('Selected Time: ', result);
  35.   }
  37.   onOk(result: Date | Date[] | null): void {
  38.     console.log('onOk', result);
  39.   }
  41.   onCalendarChange(result: Array<Date | null>): void {
  42.     console.log('onCalendarChange', result);
  43.   }
  44. }

DatePicker日期选择框 - 图4

不可选择日期和时间

可用 nzDisabledDate 和 nzDisabledTime 分别禁止选择部分日期和时间。

  1. import { Component } from '@angular/core';
  2. import differenceInCalendarDays from 'date-fns/differenceInCalendarDays';
  3. import setHours from 'date-fns/setHours';
  4. import { DisabledTimeFn, DisabledTimePartial } from 'ng-zorro-antd/date-picker';
  6. @Component({
  7.   selector: 'nz-demo-date-picker-disabled-date',
  8.   template: `
  9.     <nz-date-picker
  10.       nzFormat="yyyy-MM-dd HH:mm:ss"
  11.       [nzDisabledDate]="disabledDate"
  12.       [nzDisabledTime]="disabledDateTime"
  13.       [nzShowTime]="{ nzDefaultOpenValue: timeDefaultValue }"
  14.     ></nz-date-picker>
  15.     <br />
  16.     <nz-date-picker nzMode="month" [nzDisabledDate]="disabledDate"></nz-date-picker>
  17.     <br />
  18.     <nz-date-picker nzMode="year" [nzDisabledDate]="disabledDate"></nz-date-picker>
  19.     <br />
  20.     <nz-range-picker
  21.       [nzDisabledDate]="disabledDate"
  22.       [nzDisabledTime]="disabledRangeTime"
  23.       [nzShowTime]="{ nzHideDisabledOptions: true, nzDefaultOpenValue: timeDefaultValue }"
  24.       nzFormat="yyyy-MM-dd HH:mm:ss"
  25.     ></nz-range-picker>
  26.   `,
  27.   styles: [
  28.     `
  29.       nz-date-picker,
  30.       nz-range-picker {
  31.         margin: 0 8px 12px 0;
  32.       }
  33.     `
  34.   ]
  35. })
  36. export class NzDemoDatePickerDisabledDateComponent {
  37.   today = new Date();
  38.   timeDefaultValue = setHours(new Date(), 0);
  40.   range(start: number, end: number): number[] {
  41.     const result: number[] = [];
  42.     for (let i = start; i < end; i++) {
  43.       result.push(i);
  44.     }
  45.     return result;
  46.   }
  48.   disabledDate = (current: Date): boolean => {
  49.     // Can not select days before today and today
  50.     return differenceInCalendarDays(current, this.today) > 0;
  51.   };
  53.   disabledDateTime: DisabledTimeFn = () => {
  54.     return {
  55.       nzDisabledHours: () => this.range(0, 24).splice(4, 20),
  56.       nzDisabledMinutes: () => this.range(30, 60),
  57.       nzDisabledSeconds: () => [55, 56]
  58.     };
  59.   };
  61.   disabledRangeTime: DisabledTimeFn = (_value, type?: DisabledTimePartial) => {
  62.     if (type === 'start') {
  63.       return {
  64.         nzDisabledHours: () => this.range(0, 60).splice(4, 20),
  65.         nzDisabledMinutes: () => this.range(30, 60),
  66.         nzDisabledSeconds: () => [55, 56]
  67.       };
  68.     }
  69.     return {
  70.       nzDisabledHours: () => this.range(0, 60).splice(20, 4),
  71.       nzDisabledMinutes: () => this.range(0, 31),
  72.       nzDisabledSeconds: () => [55, 56]
  73.     };
  74.   };
  75. }

DatePicker日期选择框 - 图5

预设范围

RangePicker 可以设置常用的 预设范围 提高用户体验。

  1. import { Component } from '@angular/core';
  2. import endOfMonth from 'date-fns/endOfMonth';
  4. @Component({
  5.   selector: 'nz-demo-date-picker-presetted-ranges',
  6.   template: `
  7.     <nz-range-picker [nzRanges]="ranges" ngModel (ngModelChange)="onChange($event)"></nz-range-picker>
  8.     <br />
  9.     <nz-range-picker
  10.       [nzRanges]="ranges"
  11.       nzShowTime
  12.       nzFormat="yyyy/MM/dd HH:mm:ss"
  13.       ngModel
  14.       (ngModelChange)="onChange($event)"
  15.     ></nz-range-picker>
  16.   `,
  17.   styles: [
  18.     `
  19.       nz-date-picker,
  20.       nz-range-picker {
  21.         margin: 0 8px 12px 0;
  22.       }
  23.     `
  24.   ]
  25. })
  26. export class NzDemoDatePickerPresettedRangesComponent {
  27.   ranges = { Today: [new Date(), new Date()], 'This Month': [new Date(), endOfMonth(new Date())] };
  29.   onChange(result: Date[]): void {
  30.     console.log('From: ', result[0], ', to: ', result[1]);
  31.   }
  32. }

DatePicker日期选择框 - 图6

定制日期单元格

使用 nzDateRender 可以自定义日期单元格的内容和样式。

  1. import { Component } from '@angular/core';
  3. @Component({
  4.   selector: 'nz-demo-date-picker-date-render',
  5.   template: `
  6.     <nz-date-picker [nzDateRender]="tplRender"></nz-date-picker>
  7.     <nz-range-picker [nzDateRender]="tplRender"></nz-range-picker>
  9.     <ng-template #tplRender let-current>
  10.       <div class="ant-picker-cell-inner" [class.border]="current.getDate() === 1">
  11.         {{ current.getDate() }}
  12.       </div>
  13.     </ng-template>
  14.   `,
  15.   styles: [
  16.     `
  17.       nz-date-picker,
  18.       nz-range-picker {
  19.         margin: 0 8px 12px 0;
  20.       }
  21.       .border {
  22.         border: 1px solid #1890ff;
  23.         border-radius: 50%;
  24.       }
  25.     `
  26.   ]
  27. })
  28. export class NzDemoDatePickerDateRenderComponent {}

DatePicker日期选择框 - 图7

范围选择器

通过设置 nzMode 属性，指定范围选择器类型。

  1. import { Component } from '@angular/core';
  2. import getISOWeek from 'date-fns/getISOWeek';
  4. @Component({
  5.   selector: 'nz-demo-date-picker-range-picker',
  6.   template: `
  7.     <nz-range-picker [(ngModel)]="date" (ngModelChange)="onChange($event)"></nz-range-picker>
  8.     <br />
  9.     <nz-range-picker [nzShowTime]="true" [(ngModel)]="date" (ngModelChange)="onChange($event)"></nz-range-picker>
  10.     <br />
  11.     <nz-range-picker nzMode="week" [(ngModel)]="date" (ngModelChange)="getWeek($event)"></nz-range-picker>
  12.     <br />
  13.     <nz-range-picker nzMode="month" [(ngModel)]="date" (ngModelChange)="onChange($event)"></nz-range-picker>
  14.     <br />
  15.     <nz-range-picker nzMode="year" [(ngModel)]="date" (ngModelChange)="onChange($event)"></nz-range-picker>
  16.   `,
  17.   styles: [
  18.     `
  19.       nz-range-picker {
  20.         margin: 0 8px 12px 0;
  21.       }
  22.     `
  23.   ]
  24. })
  25. export class NzDemoDatePickerRangePickerComponent {
  26.   date = null;
  28.   onChange(result: Date[]): void {
  29.     console.log('onChange: ', result);
  30.   }
  32.   getWeek(result: Date[]): void {
  33.     console.log('week: ', result.map(getISOWeek));
  34.   }
  35. }

DatePicker日期选择框 - 图8

三种大小

三种大小的输入框，若不设置，则为 default。

  1. import { Component } from '@angular/core';
  3. @Component({
  4.   selector: 'nz-demo-date-picker-size',
  5.   template: `
  6.     <nz-radio-group [(ngModel)]="size">
  7.       <label nz-radio-button nzValue="large">large</label>
  8.       <label nz-radio-button nzValue="default">default</label>
  9.       <label nz-radio-button nzValue="small">small</label>
  10.     </nz-radio-group>
  11.     <br />
  12.     <br />
  13.     <nz-date-picker [nzSize]="size"></nz-date-picker>
  14.     <br />
  15.     <nz-date-picker nzMode="week" [nzSize]="size"></nz-date-picker>
  16.     <br />
  17.     <nz-date-picker nzMode="month" [nzSize]="size"></nz-date-picker>
  18.     <br />
  19.     <nz-range-picker [nzSize]="size"></nz-range-picker>
  20.   `,
  21.   styles: [
  22.     `
  23.       nz-date-picker,
  24.       nz-range-picker {
  25.         margin: 0 8px 12px 0;
  26.       }
  27.     `
  28.   ]
  29. })
  30. export class NzDemoDatePickerSizeComponent {
  31.   size: 'large' | 'small' | 'default' = 'default';
  32. }

DatePicker日期选择框 - 图9

禁用

选择框的不可用状态。

  1. import { Component } from '@angular/core';
  3. @Component({
  4.   selector: 'nz-demo-date-picker-disabled',
  5.   template: `
  6.     <nz-date-picker nzDisabled></nz-date-picker>
  7.     <br />
  8.     <nz-date-picker nzMode="month" nzDisabled></nz-date-picker>
  9.     <br />
  10.     <nz-range-picker nzDisabled></nz-range-picker>
  11.   `,
  12.   styles: [
  13.     `
  14.       nz-date-picker,
  15.       nz-range-picker {
  16.         margin: 0 8px 12px 0;
  17.       }
  18.     `
  19.   ]
  20. })
  21. export class NzDemoDatePickerDisabledComponent {}

DatePicker日期选择框 - 图10

自定义日期范围选择

当 RangePicker 无法满足业务需求时，可以使用两个 DatePicker 实现类似的功能。

  • 通过设置 nzDisabledDate 方法，来约束开始和结束日期。
  • 通过 open() 来优化交互。
  1. import { Component, ViewChild } from '@angular/core';
  2. import { NzDatePickerComponent } from 'ng-zorro-antd/date-picker';
  4. @Component({
  5.   selector: 'nz-demo-date-picker-start-end',
  6.   template: `
  7.     <nz-date-picker
  8.       [nzDisabledDate]="disabledStartDate"
  9.       nzShowTime
  10.       nzFormat="yyyy-MM-dd HH:mm:ss"
  11.       [(ngModel)]="startValue"
  12.       nzPlaceHolder="Start"
  13.       (nzOnOpenChange)="handleStartOpenChange($event)"
  14.     ></nz-date-picker>
  15.     <nz-date-picker
  16.       #endDatePicker
  17.       [nzDisabledDate]="disabledEndDate"
  18.       nzShowTime
  19.       nzFormat="yyyy-MM-dd HH:mm:ss"
  20.       [(ngModel)]="endValue"
  21.       nzPlaceHolder="End"
  22.       (nzOnOpenChange)="handleEndOpenChange($event)"
  23.     ></nz-date-picker>
  24.   `,
  25.   styles: [
  26.     `
  27.       nz-date-picker {
  28.         margin: 0 8px 12px 0;
  29.       }
  30.     `
  31.   ]
  32. })
  33. export class NzDemoDatePickerStartEndComponent {
  34.   startValue: Date | null = null;
  35.   endValue: Date | null = null;
  36.   @ViewChild('endDatePicker') endDatePicker!: NzDatePickerComponent;
  38.   disabledStartDate = (startValue: Date): boolean => {
  39.     if (!startValue || !this.endValue) {
  40.       return false;
  41.     }
  42.     return startValue.getTime() > this.endValue.getTime();
  43.   };
  45.   disabledEndDate = (endValue: Date): boolean => {
  46.     if (!endValue || !this.startValue) {
  47.       return false;
  48.     }
  49.     return endValue.getTime() <= this.startValue.getTime();
  50.   };
  52.   handleStartOpenChange(open: boolean): void {
  53.     if (!open) {
  54.       this.endDatePicker.open();
  55.     }
  56.     console.log('handleStartOpenChange', open);
  57.   }
  59.   handleEndOpenChange(open: boolean): void {
  60.     console.log('handleEndOpenChange', open);
  61.   }
  62. }

DatePicker日期选择框 - 图11

额外的页脚

在浮层中加入额外的页脚，以满足某些定制信息的需求。

  1. import { Component } from '@angular/core';
  3. @Component({
  4.   selector: 'nz-demo-date-picker-extra-footer',
  5.   template: `
  6.     <nz-date-picker [nzRenderExtraFooter]="footerRender"></nz-date-picker>
  7.     <br />
  8.     <nz-date-picker [nzRenderExtraFooter]="plainFooter" nzShowTime></nz-date-picker>
  9.     <nz-range-picker [nzRenderExtraFooter]="footerRender"></nz-range-picker>
  10.     <nz-range-picker [nzRenderExtraFooter]="plainFooter" nzShowTime></nz-range-picker>
  11.     <nz-date-picker nzMode="month" [nzRenderExtraFooter]="footerRender"></nz-date-picker>
  12.   `,
  13.   styles: [
  14.     `
  15.       nz-date-picker,
  16.       nz-range-picker {
  17.         margin: 0 8px 12px 0;
  18.       }
  19.     `
  20.   ]
  21. })
  22. export class NzDemoDatePickerExtraFooterComponent {
  23.   plainFooter = 'plain extra footer';
  24.   footerRender = () => 'extra footer';
  25. }

API

注意：nz-date-picker 的部分 locale 来自于 Angular 自身的国际化支持，需要在 app.module.ts 文件中 引入相应的 Angular 语言包。 例如：

  1. import { registerLocaleData } from '@angular/common';
  2. import zh from '@angular/common/locales/zh';
  3. registerLocaleData(zh);

注意： 所有输入输出日期对象均为 Date，你可以通过 date-fns 工具库获得你需要的数据。

共同的 API

以下 API 为 nz-date-picker、nz-range-picker 共享的 API。

参数说明类型默认值全局配置
[nzAllowClear]是否显示清除按钮booleantrue-
[nzAutoFocus]自动获取焦点booleanfalse-
[nzDefaultPickerValue]默认面板日期Date | Date[]--
[nzDisabled]禁用booleanfalse-
[nzDisabledDate]不可选择的日期(current: Date) => boolean--
[nzDropdownClassName]额外的弹出日历 classNamestring--
[nzFormat]展示的日期格式，见nzFormat特别说明string-
[nzInputReadOnly]为 input 标签设置只读属性（避免在移动设备上触发小键盘）booleanfalse-
[nzLocale]国际化配置object默认配置-
[nzMode]选择模式‘date’ | ‘week’ | ‘month’ | ‘year’‘date’
[nzPlaceHolder]输入框提示文字string | ‘’-
[nzPopupStyle]额外的弹出日历样式object{}-
[nzRenderExtraFooter]在面板中添加额外的页脚TemplateRef | string | (() => TemplateRef | string)-
[nzSize]输入框大小，large 高度为 40px，small 为 24px，默认是 32px‘large’ | ‘small’--
[nzSuffixIcon]自定义的后缀图标string | TemplateRef-✅
(nzOnOpenChange)弹出日历和关闭日历的回调EventEmitter<boolean>--

共同的方法

名称描述
open()打开日历弹层
close()关闭日历弹层

nz-date-pickercomponent

参数说明类型默认值
[(ngModel)]日期Date-

nz-date-picker[nzMode=”date”]component

参数说明类型默认值
[nzDateRender]自定义日期单元格的内容（month-picker/year-picker不支持）TemplateRef<Date> | string | ((d: Date) => TemplateRef<Date> | string)--
[nzDisabledTime]不可选择的时间(current: Date) => { nzDisabledHours, nzDisabledMinutes, nzDisabledSeconds }-
[nzShowTime]增加时间选择功能object | booleanTimePicker Options
[nzShowToday]是否展示“今天”按钮booleantrue
(nzOnOk)点击确定按钮的回调EventEmitter<Date>-

nz-range-pickercomponent

参数说明类型默认值
[(ngModel)]日期Date[]-
[nzRanges]预设时间范围快捷选择{ [ key: string ]: Date[] } | { [ key: string ]: () => Date[] }-
[nzSeparator]分隔符string‘~’
(nzOnCalendarChange)待选日期发生变化的回调EventEmitter<Date[]>-

nz-range-picker[nzMode=”date”]component

参数说明类型默认值
[nzShowTime]增加时间选择功能object | booleanTimePicker Options
[nzDisabledTime]不可选择的时间(current: Date, partial: ‘start’ | ‘end’) => { nzDisabledHours, nzDisabledMinutes, nzDisabledSeconds }-
(nzOnOk)点击确定按钮的回调EventEmitter<Date[]>-

nzShowTime 中当前支持的 nz-time-picker 参数有：nzFormat, nzHourStep, nzMinuteStep, nzSecondStep, nzDisabledHours, nzDisabledMinutes, nzDisabledSeconds, nzHideDisabledOptions, nzDefaultOpenValue, nzAddOn

nzFormat 特别说明

日期格式化目前同时支持两种方式：DatePipe（默认，语法参考） 和 date-fns（语法参考，见如何使用 date-fns 进行日期格式化）。