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

UI组件前端【免费下载链接】ng-zorro-antdAngular UI Component Library based on Ant Design项目地址https://gitcode.com/gh_mirrors/ng/ng-zorro-antd点击查看免费下载本篇指南围绕 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.tsnz-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.tsimport { 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 nzModeweek [(ngModel)]date / br / nz-date-picker nzModemonth [(ngModel)]date / br / nz-date-picker nzModequarter [(ngModel)]date / br / nz-date-picker nzModeyear [(ngModel)]date / }) export class NzDemoDatePickerBasicComponent { readonly date signalDate | 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 nzModemonth [(ngModel)]date / }) export class NzDemoDatePickerRangePickerComponent { readonly date signalDate[] | null(null); onChange(result: Date[]): void { console.log(onChange: , result); } }组件通过NzDatePickerModule引入模块导出见 public-api.ts。启用时间选择时nzShowTime既可以传true也可以传一个对象用于自定义时间面板见 demo/time.tsnz-date-picker nzShowTime nzFormatyyyy-MM-dd HH:mm:ss ngModel (nzOnOk)onOk($event) / nz-range-picker [nzShowTime]{ nzFormat: HH:mm } nzFormatyyyy-MM-dd HH:mm ngModel /共同的 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默认配置Ant Design locale 示例结构--[nzMode]选择模式date \| week \| month \| quarter \| yeardate--[nzPlaceHolder]输入框提示文字string \| string[]---[nzPopupStyle]额外的弹出日历样式object{}--[nzRenderExtraFooter]在面板中添加额外的页脚TemplateRef \| string \| (() TemplateRef \| string)---[nzSize]输入框大小large高度为 40pxsmall为 24px默认是 32pxlarge \| small---[nzStatus]设置校验状态error \| warning---[nzPlacement]选择框弹出的位置bottomLeft \| bottomRight \| topLeft \| topRightbottomLeft--[nzSuffixIcon]自定义的后缀图标string \| TemplateRef-✅-[nzVariant]形态变体outlined \| borderless \| filled \| underlinedoutlined✅20.0.0[nzInline]内联模式booleanfalse--(nzOnOpenChange)弹出日历和关闭日历的回调EventEmitterboolean---(nzOnPanelChange)改变模式或日期的回调EventEmitterNzPanelChangeType---nzFormat 特别说明官方文档将该参数与 TimePicker 的 API 关联即nzFormat的 token 语法由当前日期适配器解释时间格式HH:mm:ss等写法与 time-picker 共享同一套格式约定。共同的方法组件以exportAs: nzDatePicker导出可通过模板引用调用以下方法名称描述open()打开日历弹层close()关闭日历弹层源码级解读选择器、默认值与全局配置结合 date-picker.component.ts 可以进一步理解上表的实现五种粒度 范围选择器共用一个基座。组件的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 })判断当前是否为范围选择器进而渲染左右两个输入框、分隔符与激活指示条。默认值与文档一致。源码中nzAllowClear true、nzShowToday true、nzShowNow true、nzMode date、nzPlacement bottomLeft、nzShowWeekNumber false、nzInline false与文档表格完全对应nzPopupStyle的初始值为POPUP_STYLE_PATCH { position: relative }第 96 行目的是覆盖 antd 样式以保证浮层定位策略生效因此实际传入的nzPopupStyle会被自动合入该补丁见ngOnChanges。「全局配置」列对应WithConfig()装饰器。带 ✅ 的nzSuffixIcon、nzVariant以及范围选择器的nzSeparator、nzBackdrop都标注了WithConfig()组件通过readonly _nzModuleName: NzConfigKey datePicker声明模块名意味着这些输入可以在应用级通过NzConfigService对datePicker做全局默认值配置。默认格式按模式自动推导。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计算。弹出位置映射。nzPlacement经setPlacement()通过DATE_PICKER_POSITION_MAP映射为 CDK Overlay 的ConnectionPositionPair并将其置于候选位置列表首位默认候选为DEFAULT_DATE_PICKER_POSITIONS从而实现四角弹出与自动翻转。nz-date-picker 专属 API值绑定参数说明类型默认值[(ngModel)]日期Date-组件实现了ControlValueAccessor第 275 行因此除ngModel外同样支持formControl等模板/响应式表单绑定writeValue、setDisabledState等回调均已实现表单校验状态nzStatus会联动NzFormStatusService渲染反馈图标。nz-date-picker[nzModedate]参数说明类型默认值[nzDateRender]自定义日期单元格的内容month-picker/year-picker 不支持TemplateRefDate \| string \| ((d: Date) TemplateRefDate \| string)-[nzDisabledTime]不可选择的时间(current: Date) { nzDisabledHours, nzDisabledMinutes, nzDisabledSeconds }-[nzShowTime]增加时间选择功能object \| booleanTimePicker Options[nzShowToday]是否展示“今天”按钮booleantrue[nzShowNow]当设定了nzShowTime的时候面板是否显示“此刻”按钮booleantrue[nzShowWeekNumber]是否在每一行显示周数仅日期选择器支持。周选择器始终显示周数booleanfalse(nzOnOk)点击确定按钮的回调EventEmitterDate-关于(nzOnOk)源码中的onResultOk()第 929-944 行区分了两种情况单日期选择器上报单个Date或null范围选择器上报[start, end]数组——与上表及下文 range-picker 的EventEmitterDate[]声明一致。nz-range-picker 专属 API值绑定与范围参数参数说明类型默认值[(ngModel)]日期Date[]-[nzRanges]预设时间范围快捷选择{ [ key: string ]: Date[] } \| { [ key: string ]: () Date[] }-[nzSeparator]分隔符string \| TemplateRef~(nzOnCalendarChange)待选日期发生变化的回调EventEmitterDate[]-其中nzRanges支持静态数组或函数两种形式类型定义PresetRanges见 standard-types.ts函数形式适合「最近 7 天」「本月」这类相对时间范围。分隔符的渲染逻辑在基类模板中当nzSeparator有值时按字符串或TemplateRef输出否则回退为内置的swap-right图标模板第 133-143 行。nz-range-picker[nzModedate]参数说明类型默认值[nzShowTime]增加时间选择功能object \| booleanTimePicker Options[nzDisabledTime]不可选择的时间(current: Date, partial: start \| end) { nzDisabledHours, nzDisabledMinutes, nzDisabledSeconds }-[nzShowWeekNumber]是否在每一行显示周数仅日期选择器支持。周选择器始终显示周数booleanfalse(nzOnOk)点击确定按钮的回调EventEmitterDate[]-注意范围选择器的nzDisabledTime比单日期多一个partial: start | end参数用于分别限制起止两个端点可选的小时/分钟/秒。nzShowTime中当前支持的nz-time-picker参数有nzFormat、nzHourStep、nzMinuteStep、nzSecondStep、nzDisabledHours、nzDisabledMinutes、nzDisabledSeconds、nzHideDisabledOptions、nzDefaultOpenValue、nzAddOn。从源码看nzShowTime的完整对象类型是SupportTimeOptionsstandard-types.ts组件的 setter 会将布尔值转成boolean、对象原样保留该接口中额外还定义了nzUse12Hours可作为 12 小时制的扩展能力参考。FAQ如何在 Date-Picker 中使用自定义日期库参考 日期适配器文档。其核心做法是自定义 adapter 继承NzDateAdapterTDate, 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.tsNzPanelChangeType、DisabledTimeFn等类型定义可对照(nzOnPanelChange)的联合类型结构日期适配器配置docs/date-adapter.zh-CN.mdv22 起使用 DatePicker 前必须完成 adapter 注册。赞分享UI组件前端【免费下载链接】ng-zorro-antdAngular UI Component Library based on Ant Design项目地址https://gitcode.com/gh_mirrors/ng/ng-zorro-antd点击查看免费下载相关推荐NG-ZORRO DatePicker 日期选择组件完整 API、源码机制与实战指南NG ZORRO DatePicker 日期选择组件完整 API、源码机制与实战指南 NG ZORROAngular UI Component LibrarUI组件前端ng-zorro-antd 日期范围选择器实战nzMode 六种粒度、双面板选择与源码细节ng zorro antd 日期范围选择器实战nzMode 六种粒度、双面板选择与源码细节 本文以 范围选择器示例 https://link.gitcode.UI组件前端ng-zorro-antd 自定义日期范围选择用两个 DatePicker 构建联动的起止时间区间ng zorro antd 自定义日期范围选择用两个 DatePicker 构建联动的起止时间区间 当 nz range picker 无法覆盖业务需求时例UI组件前端上一篇3步精通鸣潮智能助手零门槛自动化游戏全攻略下一篇抖音下载神器5分钟掌握无水印批量下载完整指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考