DatePicker日期选择框

输入或选择日期的控件。

何时使用

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

代码演示

DatePicker日期选择框 - 图1

基本

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

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

DatePicker日期选择框 - 图2

三种大小

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

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

DatePicker日期选择框 - 图3

禁用

选择框的不可用状态。

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

DatePicker日期选择框 - 图4

自定义日期范围选择

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

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

DatePicker日期选择框 - 图5

额外的页脚

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

  1. import { Component } from '@angular/core';
  2. @Component({
  3. selector: 'nz-demo-date-picker-extra-footer',
  4. template: `
  5. <nz-date-picker [nzRenderExtraFooter]="footerRender"></nz-date-picker>
  6. <nz-date-picker [nzRenderExtraFooter]="plainFooter" nzShowTime></nz-date-picker>
  7. <nz-range-picker [nzRenderExtraFooter]="footerRender"></nz-range-picker>
  8. <nz-range-picker [nzRenderExtraFooter]="plainFooter" nzShowTime></nz-range-picker>
  9. <nz-month-picker [nzRenderExtraFooter]="footerRender" nzPlaceHolder="Select month"></nz-month-picker>
  10. `,
  11. styles: [
  12. `
  13. nz-date-picker,
  14. nz-month-picker,
  15. nz-range-picker,
  16. nz-week-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. }

DatePicker日期选择框 - 图6

定制日期单元格

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

  1. import { Component } from '@angular/core';
  2. @Component({
  3. selector: 'nz-demo-date-picker-date-render',
  4. template: `
  5. <nz-date-picker [nzDateRender]="tplRender"></nz-date-picker>
  6. <nz-range-picker [nzDateRender]="tplRender"></nz-range-picker>
  7. <ng-template #tplRender let-current>
  8. <div class="ant-calendar-date" [class.border]="current.getDate() === 1">
  9. {{ current.getDate() }}
  10. </div>
  11. </ng-template>
  12. `,
  13. styles: [
  14. `
  15. nz-date-picker,
  16. nz-month-picker,
  17. nz-range-picker,
  18. nz-week-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

日期格式

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

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

DatePicker日期选择框 - 图8

日期时间选择

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

  1. import { Component } from '@angular/core';
  2. @Component({
  3. selector: 'nz-demo-date-picker-time',
  4. template: `
  5. <nz-date-picker
  6. nzShowTime
  7. nzFormat="yyyy-MM-dd HH:mm:ss"
  8. nzPlaceHolder="Select Time"
  9. (ngModelChange)="onChange($event)"
  10. (nzOnOk)="onOk($event)"
  11. ></nz-date-picker>
  12. <br />
  13. <nz-range-picker
  14. [nzShowTime]="{ nzFormat: 'HH:mm' }"
  15. nzFormat="yyyy-MM-dd HH:mm"
  16. [nzPlaceHolder]="['Start Time', 'End Time']"
  17. (ngModelChange)="onChange($event)"
  18. (nzOnOk)="onOk($event)"
  19. ></nz-range-picker>
  20. `,
  21. styles: [
  22. `
  23. nz-date-picker,
  24. nz-month-picker,
  25. nz-range-picker,
  26. nz-week-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. }
  36. onOk(result: Date): void {
  37. console.log('onOk', result);
  38. }
  39. }

DatePicker日期选择框 - 图9

不可选择日期和时间

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

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

DatePicker日期选择框 - 图10

预设范围

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

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

DatePicker日期选择框 - 图11

受控面板

通过组合 nzModenzOnPanelChange 控制要展示的面板。

  1. import { Component } from '@angular/core';
  2. @Component({
  3. selector: 'nz-demo-date-picker-mode',
  4. template: `
  5. <nz-date-picker
  6. [nzMode]="dateMode"
  7. nzShowTime
  8. (nzOnOpenChange)="handleDateOpenChange($event)"
  9. (nzOnPanelChange)="handleDatePanelChange($event)"
  10. >
  11. </nz-date-picker>
  12. `,
  13. styles: [
  14. `
  15. nz-date-picker,
  16. nz-month-picker,
  17. nz-range-picker,
  18. nz-week-picker {
  19. margin: 0 8px 12px 0;
  20. }
  21. `
  22. ]
  23. })
  24. export class NzDemoDatePickerModeComponent {
  25. dateMode = 'time';
  26. handleDateOpenChange(open: boolean): void {
  27. if (open) {
  28. this.dateMode = 'time';
  29. }
  30. }
  31. handleDatePanelChange(mode: string): void {
  32. console.log('handleDatePanelChange: ', mode);
  33. }
  34. }

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);

日期类组件包括以下四种形式。

  • nz-date-picker
  • nz-month-picker
  • nz-range-picker
  • nz-week-picker
    注意: 所有输入输出日期对象均为 Date,你可以通过 date-fns 工具库获得你需要的数据。

单独引入此组件

想要了解更多关于单独引入组件的内容,可以在快速上手页面进行查看。

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

共同的 API

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

参数说明类型默认值
[nzAllowClear]是否显示清除按钮booleantrue
[nzAutoFocus]自动获取焦点booleanfalse
[nzClassName]选择器 classNamestring''
[nzDateRender]自定义日期单元格的内容(month-picker/year-picker不支持)TemplateRef<Date>|string|((d: Date) => TemplateRef<Date>|string)-
[nzDisabled]禁用booleanfalse
[nzDisabledDate]不可选择的日期(current: Date) => boolean-
[nzLocale]国际化配置object默认配置
[nzOpen]控制弹层是否展开boolean-
[nzPopupStyle]额外的弹出日历样式object{}
[nzDropdownClassName]额外的弹出日历 classNamestring-
[nzSize]输入框大小,large 高度为 40px,small 为 24px,默认是 32px'large'|'small'-
[nzStyle]自定义输入框样式object{}
(nzOnOpenChange)弹出日历和关闭日历的回调EventEmitter<boolean>-

nz-date-pickercomponent

参数说明类型默认值
[ngModel]日期Date-
[nzDisabledTime]不可选择的时间(current: Date) => { nzDisabledHours, nzDisabledMinutes, nzDisabledSeconds }-
[nzFormat]展示的日期格式,见nzFormat特别说明string"yyyy-MM-dd"
[nzRenderExtraFooter]在面板中添加额外的页脚TemplateRef|string|(() => TemplateRef|string)-
[nzShowTime]增加时间选择功能object|booleanTimePicker Options
[nzShowToday]是否展示“今天”按钮booleantrue
[nzPlaceHolder]输入框提示文字string-
(nzOnOk)点击确定按钮的回调EventEmitter<Date>-
(ngModelChange)时间发生变化的回调EventEmitter<Date>-

nz-year-pickercomponent

参数说明类型默认值
[ngModel]日期Date-
[nzFormat]展示的日期格式,见nzFormat特别说明string"yyyy"
[nzRenderExtraFooter]在面板中添加额外的页脚TemplateRef|string|(() => TemplateRef|string)-
[nzPlaceHolder]输入框提示文字string-
(ngModelChange)时间发生变化的回调EventEmitter<Date>-

nz-month-pickercomponent

参数说明类型默认值
[ngModel]日期Date-
[nzFormat]展示的日期格式,见nzFormat特别说明string"yyyy-MM"
[nzRenderExtraFooter]在面板中添加额外的页脚TemplateRef|string|(() => TemplateRef|string)-
[nzPlaceHolder]输入框提示文字string-
(ngModelChange)时间发生变化的回调EventEmitter<Date>-

nz-week-pickercomponent

参数说明类型默认值
[ngModel]日期Date-
[nzFormat]展示的日期格式,见nzFormat特别说明string"yyyy-ww"
[nzPlaceHolder]输入框提示文字string-
(ngModelChange)时间发生变化的回调EventEmitter<Date>-

nz-range-pickercomponent

参数说明类型默认值
[ngModel]日期Date[]-
[nzDisabledTime]不可选择的时间(current: Date, partial: 'start'|'end') => { nzDisabledHours, nzDisabledMinutes, nzDisabledSeconds }-
[nzFormat]展示的日期格式,见nzFormat特别说明string"yyyy-MM-dd"
[nzRanges]预设时间范围快捷选择{ [ key: string ]: Date[] } | { [ key: string ]: () => Date[] }-
[nzRenderExtraFooter]在面板中添加额外的页脚TemplateRef|string|(() => TemplateRef|string)-
[nzShowTime]增加时间选择功能object|booleanTimePicker Options
[nzPlaceHolder]输入框提示文字string[]-
(nzOnOk)点击确定按钮的回调EventEmitter<Date[]>-
(ngModelChange)时间发生变化的回调EventEmitter<Date[]>-
(nzOnCalendarChange)待选日期发生变化的回调EventEmitter<Date[]>-

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

nzFormat特别说明

日期格式化目前同时支持两种方式:DatePipe(默认,语法参考) 和 Date-fns语法参考,见如何使用Date-fns进行日期格式化)。