• DatePicker日期选择框
    • 何时使用
    • 单独引入此组件
    • 代码演示
    • API
      • 共同的 API
      • nz-date-pickercomponent
      • nz-year-pickercomponent
      • nz-month-pickercomponent
      • nz-week-pickercomponent
      • nz-range-pickercomponent
      • nzFormat特别说明

    DatePicker日期选择框

    输入或选择日期的控件。

    何时使用

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

    单独引入此组件

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

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

    代码演示

    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/i18n';
    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)"></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 工具库获得你需要的数据。

    共同的 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进行日期格式化)。