DatePicker
日期选择框

输入或选择日期的控件。
使用
源码 components/date-picker 提交问题 待解决
文档 编辑此页 LLMs.md

何时使用#

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

代码演示#






基本

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

      加载中
Date
切换不同的选择器

提供选择器，自由切换不同类型的日期选择器，常用于日期筛选场合。

      加载中






三种大小

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

      加载中


禁用

选择框的不可用状态。

      加载中
自定义日期范围选择

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

  • 通过设置 nzDisabledDate 方法，来约束开始和结束日期。
  • 通过 open() 来优化交互。
      加载中
形态变体

DatePicker 形态变体，可选 outlinedfilledborderlessunderlined 四种形态。

      加载中
20.0.0
自定义状态

使用 nzStatus 为 DatePicker 添加状态，可选 error 或者 warning。

      加载中



显示周数

使用 nzShowWeekNumber 显示周数

      加载中





范围选择器

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

      加载中



日期格式

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

      加载中

日期时间选择

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

      加载中




不可选择日期和时间

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

      加载中

预设范围

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

      加载中

定制日期单元格

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

      加载中
一 二 三 四 五 六 日
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
1
2
3
4
5
6
7
8
9
10
11
12
今天
内联模式

使用 nzInline 属性，可以渲染为内联模式。

      加载中



自定义位置

可以通过 nzPlacement 手动指定弹出的位置。

      加载中

API#

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

import { registerLocaleData } from '@angular/common';
import zh from '@angular/common/locales/zh';

registerLocaleData(zh);

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

共同的 API#

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

参数说明类型默认值全局配置版本
[nzId]组件内部 input 的 id 值string-
[nzAllowClear]是否显示清除按钮booleantrue-
[nzAutoFocus]自动获取焦点booleanfalse-
[nzBackdrop]浮层是否应带有背景板booleanfalse
[nzDefaultPickerValue]默认面板日期Date | Date[]--
[nzDisabled]禁用booleanfalse-
[nzDisabledDate]不可选择的日期(current: Date) => boolean--
[nzDropdownClassName]额外的弹出日历 classNamestring--
[nzFormat]展示的日期格式，见nzFormat特别说明string-
[nzInputReadOnly]为 input 标签设置只读属性（避免在移动设备上触发小键盘）booleanfalse-
[nzLocale]国际化配置object默认配置-
[nzMode]选择模式'date' | 'week' | 'month' | 'quarter' | 'year''date'
[nzPlaceHolder]输入框提示文字string | string[]--
[nzPopupStyle]额外的弹出日历样式object{}-
[nzRenderExtraFooter]在面板中添加额外的页脚TemplateRef | string | (() => TemplateRef | string)-
[nzSize]输入框大小，large 高度为 40px，small 为 24px，默认是 32px'large' | 'small'--
[nzStatus]设置校验状态'error' | 'warning'-
[nzPlacement]选择框弹出的位置'bottomLeft' | 'bottomRight' | 'topLeft' | 'topRight''bottomLeft'
[nzSuffixIcon]自定义的后缀图标string | TemplateRef-✅
[nzVariant]形态变体'outlined' | 'borderless' | 'filled' | 'underlined''outlined'✅20.0.0
[nzInline]内联模式booleanfalse-
(nzOnOpenChange)弹出日历和关闭日历的回调EventEmitter<boolean>--
(nzOnPanelChange)改变模式或日期的回调EventEmitter<NzPanelChangeType>--

共同的方法#

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

nz-date-picker#

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

nz-date-picker[nzMode="date"]#

参数说明类型默认值
[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
[nzShowNow]当设定了nzShowTime的时候，面板是否显示“此刻”按钮booleantrue
[nzShowWeekNumber]是否在每一行显示周数（仅日期选择器支持。周选择器始终显示周数）booleanfalse
(nzOnOk)点击确定按钮的回调EventEmitter<Date>-

nz-range-picker#

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

nz-range-picker[nzMode="date"]#

参数说明类型默认值
[nzShowTime]增加时间选择功能object | booleanTimePicker Options
[nzDisabledTime]不可选择的时间(current: Date, partial: 'start' | 'end') => { nzDisabledHours, nzDisabledMinutes, nzDisabledSeconds }-
[nzShowWeekNumber]是否在每一行显示周数（仅日期选择器支持。周选择器始终显示周数）booleanfalse
(nzOnOk)点击确定按钮的回调EventEmitter<Date[]>-

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

FAQ#

为何在设置 nzFormat="dd/MM/yyyy" 后手动输入不生效#

需要引入 date-fns 。日期格式化目前同时支持两种方式：DatePipe（默认，语法参考） 和 date-fns（见如何使用 date-fns 进行日期格式化）。当你引入 date-fns 后，NG-ZORRO 会使用它提供的 API 来进行反序列化。

Q：滚动时浮层元素没有跟随滚动位置#

默认情况下，浮层元素使用 body 作为滚动容器，如果使用了其他滚动容器，在自定义滚动容器元素上添加 CdkScrollable 指令。 注意：您需要从 @angular/cdk/scrolling 导入 CdkScrollable 指令或 ScrollingModule 模块。