ng-zorro-antd DatePicker 完整指南：日期/范围选择器的 API、国际化配置与源码实现

• UI组件
• 前端

本篇指南围绕 ng-zorro-antd 官方日期选择框文档（components/date-picker/doc/index.zh-CN.md）展开，系统讲解nz-date-picker与nz-range-picker的完整 API、国际化与日期适配器配置、表单集成方式，并结合仓库源码（如 date-picker.component.ts）还原默认值、格式推导、弹层控制与全局配置等实现细节，帮助你在 Angular 项目中正确落地日期录入场景并理解其底层行为。

何时使用

官方文档给出的使用场景非常明确：当用户需要输入一个日期，可以点击标准输入框，弹出日期面板进行选择。日期选择框属于「数据录入」类组件，适合表单中的日期字段、预约/排期、报表时间范围筛选等场景。

仓库内的示例组件展示了它的两种基本形态（demo/basic.ts、demo/range-picker.ts）：

• nz-date-picker：单值选择，通过nzMode切换date/week/month/quarter/year五种粒度；
• nz-range-picker：范围选择，值为[开始, 结束]的日期数组，同样支持上述模式。

前置配置：国际化与日期适配器

官方文档在 API 章节开头给出两条关键注意事项，二者共同构成了使用 DatePicker 的前置条件。

1. Angular 自身的语言包

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

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

这一步决定 Angular 框架层（如内置管线的日期格式）使用的语言规则，与 NG-ZORRO 组件自身通过NzI18nService加载的 locale 是两套配置，缺一不可。

2. 日期适配器（v22 起必须显式提供）

结合仓库内 日期适配器文档 可以确认：从 v22 开始，NG-ZORRO 不再默认提供日期引擎适配器，应用需要在根配置中显式提供 adapter，否则 DatePicker、Calendar、TimePicker 会因缺少NzDateAdapterprovider 而无法工作。若希望与之前版本保持一致，可使用内置的date-fns适配器：

import { ApplicationConfig } from '@angular/core'; import { zhCN } from 'date-fns/locale'; import { provideNzDateFnsAdapter } from 'ng-zorro-antd/core/time'; export const appConfig: ApplicationConfig = { providers: [provideNzDateFnsAdapter({ locale: zhCN, firstDayOfWeek: 1 })] };

也可以使用provideNzNativeDateAdapter({ locale: 'zh-CN', firstDayOfWeek: 1 })让日期能力走原生Date与Intl.DateTimeFormat语义。需要注意：NZ_I18N控制 NG-ZORRO 组件文案，adapter 的locale控制日期库的格式化与周规则（月份名、星期名、周起始日）；nzFormat及默认格式字符串都由当前 adapter 解释，切换日期库时要确认 token 语法一致。

3. 输入输出均为Date

文档明确：所有输入输出日期对象均为原生Date，你可以通过 date-fns 等工具库获得你需要的数据。这一条在源码中得到印证：date-picker.component.ts 中，组件在通过表单控制回调onChangeFn上报值时，统一取内部CandyDate的nativeDate（即原生Date）；范围选择器则上报[start, end]两个Date。因此在业务层拿到的值始终是Date或Date[]，组件内部只是用CandyDate做了封装。

快速上手

以下示例摘自 demo/basic.ts 与 demo/range-picker.ts：

import { Component, signal } from '@angular/core'; import { FormsModule } from '@angular/forms'; import { NzDatePickerModule } from 'ng-zorro-antd/date-picker'; @Component({ selector: 'nz-demo-date-picker-basic', imports: [FormsModule, NzDatePickerModule], template: ` <nz-date-picker [(ngModel)]="date" (ngModelChange)="onChange($event)" /> <br /> <nz-date-picker nzMode="week" [(ngModel)]="date" /> <br /> <nz-date-picker nzMode="month" [(ngModel)]="date" /> <br /> <nz-date-picker nzMode="quarter" [(ngModel)]="date" /> <br /> <nz-date-picker nzMode="year" [(ngModel)]="date" /> ` }) export class NzDemoDatePickerBasicComponent { readonly date = signal<Date | null>(null); onChange(result: Date): void { console.log('onChange: ', result); } }

@Component({ selector: 'nz-demo-date-picker-range-picker', imports: [FormsModule, NzDatePickerModule], template: ` <nz-range-picker [(ngModel)]="date" (ngModelChange)="onChange($event)" /> <br /> <nz-range-picker [nzShowTime]="true" [(ngModel)]="date" /> <br /> <nz-range-picker nzMode="month" [(ngModel)]="date" /> ` }) export class NzDemoDatePickerRangePickerComponent { readonly date = signal<Date[] | null>(null); onChange(result: Date[]): void { console.log('onChange: ', result); } }

组件通过NzDatePickerModule引入（模块导出见 public-api.ts）。启用时间选择时，nzShowTime既可以传true，也可以传一个对象用于自定义时间面板（见 demo/time.ts）：

<nz-date-picker nzShowTime nzFormat="yyyy-MM-dd HH:mm:ss" ngModel (nzOnOk)="onOk($event)" /> <nz-range-picker [nzShowTime]="{ nzFormat: 'HH:mm' }" nzFormat="yyyy-MM-dd HH:mm" ngModel />

共同的 API

以下 API 为nz-date-picker、nz-range-picker共享，完整继承自官方文档的 API 表：

nzFormat 特别说明：官方文档将该参数与 TimePicker 的 API 关联，即nzFormat的 token 语法由当前日期适配器解释，时间格式（HH:mm:ss）等写法与 time-picker 共享同一套格式约定。

共同的方法

组件以exportAs: 'nzDatePicker'导出，可通过模板引用调用以下方法：

源码级解读：选择器、默认值与全局配置

结合 date-picker.component.ts 可以进一步理解上表的实现：

1. 五种粒度 + 范围选择器共用一个基座。组件的selector为'nz-date-picker,nz-week-picker,nz-month-picker,nz-quarter-picker,nz-year-picker,nz-range-picker'（第 105 行），所有选择器都由NzDatePickerComponent承载。而 range-picker.component.ts 中的NzRangePickerComponent实际上是一个空指令，仅用于依赖注入探测：基类通过isRange = !!inject(NzRangePickerComponent, { self: true, optional: true })判断当前是否为范围选择器，进而渲染左右两个输入框、分隔符与激活指示条。
2. 默认值与文档一致。源码中nzAllowClear = true、nzShowToday = true、nzShowNow = true、nzMode = 'date'、nzPlacement = 'bottomLeft'、nzShowWeekNumber = false、nzInline = false，与文档表格完全对应；nzPopupStyle的初始值为POPUP_STYLE_PATCH = { position: 'relative' }（第 96 行），目的是覆盖 antd 样式以保证浮层定位策略生效，因此实际传入的nzPopupStyle会被自动合入该补丁（见ngOnChanges）。
3. 「全局配置」列对应@WithConfig()装饰器。带 ✅ 的nzSuffixIcon、nzVariant（以及范围选择器的nzSeparator、nzBackdrop）都标注了@WithConfig()，组件通过readonly _nzModuleName: NzConfigKey = 'datePicker'声明模块名，意味着这些输入可以在应用级通过NzConfigService对datePicker做全局默认值配置。
4. 默认格式按模式自动推导。setModeAndFormat()（第 799-821 行）在未显式设置nzFormat时按模式给出默认格式：year → 'yyyy'、quarter → 'yyyy-[Q]Q'、month → 'yyyy-MM'、week → 'YYYY-ww'、date → 'yyyy-MM-dd'（启用nzShowTime时为'yyyy-MM-dd HH:mm:ss'）；同时输入框宽度按Math.max(10, nzFormat.length) + 2计算。
5. 弹出位置映射。nzPlacement经setPlacement()通过DATE_PICKER_POSITION_MAP映射为 CDK Overlay 的ConnectionPositionPair，并将其置于候选位置列表首位（默认候选为DEFAULT_DATE_PICKER_POSITIONS），从而实现四角弹出与自动翻转。

nz-date-picker 专属 API

值绑定

组件实现了ControlValueAccessor（第 275 行），因此除ngModel外同样支持formControl等模板/响应式表单绑定，writeValue、setDisabledState等回调均已实现；表单校验状态（nzStatus）会联动NzFormStatusService渲染反馈图标。

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

关于(nzOnOk)，源码中的onResultOk()（第 929-944 行）区分了两种情况：单日期选择器上报单个Date或null；范围选择器上报[start, end]数组——与上表及下文 range-picker 的EventEmitter<Date[]>声明一致。

nz-range-picker 专属 API

值绑定与范围参数

其中nzRanges支持静态数组或函数两种形式（类型定义PresetRanges见 standard-types.ts），函数形式适合「最近 7 天」「本月」这类相对时间范围。分隔符的渲染逻辑在基类模板中：当nzSeparator有值时按字符串或TemplateRef输出，否则回退为内置的swap-right图标（模板第 133-143 行）。

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

注意范围选择器的nzDisabledTime比单日期多一个partial: 'start' | 'end'参数，用于分别限制起止两个端点可选的小时/分钟/秒。

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

从源码看，nzShowTime的完整对象类型是SupportTimeOptions（standard-types.ts），组件的 setter 会将布尔值转成boolean、对象原样保留；该接口中额外还定义了nzUse12Hours，可作为 12 小时制的扩展能力参考。

FAQ

如何在 Date-Picker 中使用自定义日期库

参考 日期适配器文档。其核心做法是：自定义 adapter 继承NzDateAdapter<TDate, TLocale>，推荐TDate继续使用Date以保持组件 API 与表单值兼容，只把格式化、解析和日期计算委托给第三方日期库（文档给出了完整的 Day.js 实现示例），然后在应用根配置中通过provideNzDateAdapter(MyAdapter, { locale: 'zh-cn', firstDayOfWeek: 1 })注册。启用时间选择能力时还需实现setTime、getHours、getMinutes、getSeconds、parseTime、addSeconds等时间相关方法。

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

默认情况下，浮层元素使用body作为滚动容器。如果使用了其他滚动容器，在自定义滚动容器元素上添加CdkScrollable指令即可让 CDK Overlay 感知正确的滚动父级，浮层会随之跟随滚动位置更新。注意：需要从@angular/cdk/scrolling导入CdkScrollable指令或ScrollingModule模块。

小结与延伸阅读

• 官方 API 文档：doc/index.zh-CN.md；
• 基座组件实现：date-picker.component.ts，涵盖打开/关闭弹层、输入校验（checkValidDate会同时用parse与format往返验证输入合法性）、失焦回滚（checkAndClose在值不合法时恢复initialValue）、以及 ESC 键重置等交互细节；
• 时间相关工具与类型：util.ts、standard-types.ts（NzPanelChangeType、DisabledTimeFn等类型定义，可对照(nzOnPanelChange)的联合类型结构）；
• 日期适配器配置：docs/date-adapter.zh-CN.md，v22 起使用 DatePicker 前必须完成 adapter 注册。

• UI组件
• 前端