ng-zorro-antd 21.3.3 已正式发布。这是 Ant Design 在 Angular 生态中的实现，面向企业级中后台产品，全部代码采用 MIT 协议开源，企业、组织和个人都可以免费使用。本次版本更新规模不大，但覆盖了两个升级时容易影响现有代码和交互的区域：日期范围选择行为，以及 dropdown、menu 重命名导出的兼容处理。
这次更新解决了什么
日期范围选择行为保持一致
date-picker 修复了范围选择行为保持问题。对于使用日期区间筛选、报表查询或时间段配置的中后台页面，这类修复通常比新增一个视觉组件更重要：用户选择开始日期和结束日期时，组件的交互应当符合既有预期，升级后也不应改变业务页面的操作方式。
可以重点回归以下场景：
- 选择完整日期范围后，开始日期和结束日期是否都能正确回填。
- 重新打开日期范围选择器时，已有值是否仍然保持。
- 清空、重新选择和切换月份后，表单值是否符合业务逻辑。
- 日期范围变化后，查询按钮使用的值是否仍是预期格式。
为重命名导出保留废弃别名
dropdown 和 menu 为重命名后的导出添加了废弃别名。这意味着项目在升级过程中，可以继续使用旧名称完成过渡，同时逐步将代码迁移到新的导出名称。
废弃别名的价值在于降低一次性升级成本，但它不应被视为长期方案。新代码应优先采用当前名称；旧别名则应通过 lint、代码搜索或迁移任务逐步清理，避免未来主版本升级时集中暴露问题。
升级前后的实践方式
升级前建议确认 Angular 主版本、ng-zorro-antd 版本以及项目锁文件的状态。下面是一组可以直接改造的命令，适用于使用 npm 的 Angular 项目：
# 在项目根目录执行
npm install ng-zorro-antd@21.3.3 --save
# 检查实际安装版本
npm list ng-zorro-antd
# 执行项目测试和生产构建
npm test -- --watch=false
npm run build
如果项目使用 pnpm 或 yarn，应保持团队现有的包管理器和锁文件，不要在同一次升级中混用多个包管理器。
日期范围选择可以这样接入一个筛选表单。示例假设项目已经完成 ng-zorro-antd 的 Angular 模块或组件导入配置：
import { Component } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { NzDatePickerModule } from 'ng-zorro-antd/date-picker';
@Component({
selector: 'app-report-filter',
standalone: true,
imports: [FormsModule, NzDatePickerModule],
template: `
<nz-range-picker
[(ngModel)]="range"
(ngModelChange)="onRangeChange($event)"
></nz-range-picker>
<button type="button" (click)="search()">查询</button>
<pre>{{ query | json }}</pre>
`,
})
export class ReportFilterComponent {
range: Date[] = [];
query: { startDate?: string; endDate?: string } = {};
onRangeChange(value: Date[] | null): void {
const [start, end] = value ?? [];
this.query = {
startDate: start?.toISOString(),
endDate: end?.toISOString(),
};
}
search(): void {
console.log('query report with:', this.query);
}
}
实际项目中请根据后端约定处理时区和日期格式。toISOString() 返回 UTC 时间，若接口要求本地日期或 yyyy-MM-dd，应在请求层统一转换，避免不同页面各自处理产生偏差。上面的示例用于验证范围值是否稳定回填，不能替代项目自身的日期格式策略。
建议加入的回归测试
如果日期范围选择器位于公共查询组件中，建议在升级后增加一个最小回归用例，验证选择结果能够进入业务查询参数。测试工具和写法取决于项目使用的 Angular 测试方案，核心断言可以围绕这些结果展开：
- 初始值为空时，组件可以完成开始和结束日期的选择。
- 组件重新渲染或打开时，已保存的范围仍然存在。
- 清空范围后，发送给接口的开始和结束日期都被移除。
- 旧的
dropdown、menu导出别名仍能让现有代码编译，但新代码已使用重命名后的导出。
不要只依赖生产构建。日期组件的问题往往出现在交互状态和表单回填过程中，类型检查和构建成功并不能证明用户操作没有变化。
升级清单
ng-zorro-antd 21.3.3 适合以小步方式升级：
- 将依赖锁定到
21.3.3，提交对应锁文件变化。 - 回归所有使用日期范围筛选的页面。
- 检查
dropdown和menu相关导入，优先迁移到当前导出名称。 - 把废弃别名视为过渡兼容层，不要在新业务代码中继续扩散旧写法。
- 在 CI 中同时执行测试和生产构建，确认升级没有影响现有 Angular 配置。
这次版本的重点不是引入新的页面范式，而是让已有中后台应用在日期选择和导出重命名场景下更平稳地演进。对于已经使用 ng-zorro-antd 的项目，先完成依赖升级和针对性回归，再安排旧导入名称的清理，会比一次性重构所有组件更容易控制风险。