ng-zorro-developer

NG-ZORRO 开发指南

与 angular-developer 配套使用，该技能提供 Angular 基础知识（信号、DI、路由、表单、SSR、无障碍访问）。本技能专注于 NG-ZORRO 的具体内容。建议同时安装两者，以获得最佳体验。

兼容性

• 跟踪版本： [email protected]，与 Angular ^22.0.0 对齐。NG-ZORRO 遵循 Angular 的主版本号，ng-zorro-antd 的主版本号始终与 @angular/core 一致。
• v21 → v22（实际破坏性变更）： v22 移除了长期弃用的输入项，并更改了日期组件的配置方式。主要变更包括：日期相关组件不再提供默认日期适配器（需显式调用 provideNzDateFnsAdapter()，且 date-fns 现已升级至 v4）；所有组件均改为 OnPush；此外还移除了一批已弃用的 API（nz-button 的 nzSearch、nz-cascader 的 nzDisplayWith、nz-input 的 nzAutosize + nz-input-group 插槽 + nzStepperless、nz-modal 中 nzOnOk/nzOnCancel 的输入用法、nz-upload 的 nzTransformFile、nz-tooltip 的 cdkConnectedOverlayPush，以及 dropdown/collapse/message/transfer 中的部分 API）。请参阅 migration.md。
• v22.1 亮点： 移除了独立的 style/rtl.less 文件（LTR 和 RTL 现已共用 CSS 逻辑属性），重命名了少量 LESS 变量（@anchor-link-*、@tabs-horizontal-*），修复了 input、date range picker 和 slider 的 Signal Forms 问题，nz-avatar 支持响应式尺寸，nz-cron-expression 支持 nzStatus，且 nz-auto-complete 新增了 nzDropdownMatchSelectWidth。22.1.2 将内部 ngModel 控件隔离，以避免 NG01354 错误。请参阅 migration.md。
• 适用项目： NG-ZORRO v17 → v22 项目。本技能基于 v21/v22 API；migration.md 介绍了从模块迁移到独立组件、i18n 提供者变更、v22 移除的 API，以及各版本中的弃用项。
• Angular： v17 或更高版本（独立组件和新控制流）；使用 ng-zorro-antd@22 需搭配 v22。v22 是最匹配的版本。
• 无 Zone / OnPush： NG-ZORRO 官方支持无 Zone 变更检测和 ChangeDetectionStrategy.OnPush；组件能够感知信号，并会在需要时于内部使用 markForCheck()。
• SSR： 一流支持，可在 Angular Universal / @angular/ssr 下运行。
• 国际化： 在根级调用 provideNzI18n(en_US)，并通过 NzI18nService 在运行时切换区域设置。
• 不支持： NG-ZORRO v16 及以下版本（Angular v16 及以下版本、仅使用 NgModule 的模式、不支持信号）。

如果项目的 ng-zorro-antd 主版本与 @angular/core 不一致，安装时 npm 对等依赖检查会失败。请告知用户先升级 Angular，再同步升级 NG-ZORRO，参见 migration.md。

1. 回答前先检查项目的 NG-ZORRO 版本。 主版本与 Angular 同步，并会带来实际变更；i18n 提供者在 v17 中改为 provideNzI18n，v18 引入了完整的独立类导出，动态主题在 v21 中仍属实验性功能。package.json 是准确信息的来源。

2. 预先确认导入方式。 v18 之前的代码会导入 Nz*Module，并在 @NgModule.imports 中注册。v18+ 会将每个组件导出为独立类（例如 NzButtonComponent），并提供精简的指令集（例如用于 nz-button 属性的 NzButtonDirective）。在 v18+ 项目中编写新代码时应使用独立导入，不要使用 Nz*Module。两种方式仍可使用，也可以在同一个模板中混用。请参阅 setup.md。

3. 确认主题模式。 如果 src/styles.less 导入 ng-zorro-antd/ng-zorro-antd.less → LESS 变量模式（默认）。如果项目使用 ng-zorro-antd/style/dynamic-theme/dynamic-theme.less 和 NzConfigService 在运行时切换 CSS 变量 → 动态主题（实验性）。两种方式使用相同的变量名，但自定义所在的层级截然不同。请参阅 theming.md。

4. 生成 NG-ZORRO 代码后，运行 ng build。 AI 最常见的错误包括：(a) 在独立组件中导入 Nz*Module（虽然可用，但这是过时的模式，建议优先使用独立类）；(b) 忘记注册区域设置（provideNzI18n(en_US)），导致 DatePicker / Pagination 在运行时抛出错误；(c) 使用 v15 时代通过 APP_INITIALIZER 初始化 nzI18nService 的方式，该方式已在 v17 中由 provider 取代；(d) 使用 <nz-icon>，却没有调用 provideNzIconsPatch / 通过 provideNzIcons 注册图标。请参阅 setup.md 和 migration.md。

NG-ZORRO 架构：指令、组件和服务

NG-ZORRO 混合了三种模式。了解组件使用哪种模式，会影响其接入方式：

• 原生元素上的属性指令，例如 <button nz-button nzType="primary">Save</button>。该指令会增强原生控件。大多数通用组件（Button、Tooltip、Popover、Dropdown 触发器）都采用这种形式。
• 独立组件，例如 <nz-table>、<nz-form-item>、<nz-date-picker>。它们会渲染自己的 DOM，用于具有内部布局或模板投影的组件。
• 用于命令式 UI 的可注入服务，如 NzModalService、NzMessageService、NzNotificationService、NzDrawerService。在 app.config.ts 中通过 provideNzModal() / provideNzMessage() 等导入。

两种形式都存在时，默认使用指令形式（例如，优先使用 nz-button，而不是包装组件）。只有在确实需要命令式交互时，才使用服务形式（如 toast、临时确认、以编程方式打开对话框）。

安装与主题

• 安装设置：ng add ng-zorro-antd（原理图会处理 i18n、样式、动画和图标注册）。手动安装、provideNzI18n、provideNzIcons、动画设置及常见问题。请参阅 setup.md
• 主题：LESS 变量覆盖（@primary-color、@border-radius-base 等）、随附的四种预设主题（default、dark、compact、aliyun）、实验性的 CSS 变量动态主题、运行时主题切换。请参阅 theming.md

组件

NG-ZORRO 在 ng.ant.design/components/overview 按类别记录了 70 多个组件。以下每个类别文件都介绍相关组件、关键输入项、常见模式和注意事项。

• 通用：Button、FloatButton、Icon、Typography。请参阅 general.md
• 布局：Divider、Flex、Grid、Layout（Header / Sider / Content / Footer）、Space、Splitter。请参阅 layout.md
• 导航：Anchor、Breadcrumb、Dropdown、Menu、PageHeader、Pagination、Steps、Tabs。请参阅 navigation.md
• 数据录入（表单控件）：AutoComplete、Cascader、Checkbox、ColorPicker、DatePicker、Form、Input、InputNumber、Mention、Radio、Rate、Select、Slider、Switch、TimePicker、Transfer、TreeSelect、Upload。请参阅 form-controls.md
• 数据展示：Avatar、Badge、Calendar、Card、Carousel、Collapse、Comment、Descriptions、Empty、Image、List、QRCode、Segmented、Statistic、Table、Tag、Timeline、Tree、TreeView。请参阅 data-display.md
• 反馈（浮层）：Alert、Drawer、Message、Modal、Notification、Popconfirm、Popover、Progress、Result、Skeleton、Spin、Tooltip。请参阅 overlays.md
• 其他：Affix、Watermark。详见 layout.md。

表单集成

• 表单：将 nz-form 接入 ReactiveForms（v17+ 中的默认方式）和 Signal Forms（Angular v22+）、nz-form-item / nz-form-control / nz-form-label 三件套、异步验证器和 nzValidatingTip，以及自定义控件的 ControlValueAccessor 模式。请参阅 forms.md

无障碍

• 无障碍：NG-ZORRO 遵循的 WAI-ARIA 规范、键盘导航（尤其是 Menu / Tree / Table）、Modal 和 Drawer 中的焦点管理，以及通过 nzDirection 支持 RTL。请参阅 accessibility.md

迁移

• 迁移：从模块迁移到独立模式（v18）、provideNzI18n 提供程序（v17）、通过 provideNzIcons 注册 <nz-icon>（v17+）、v18 → v21 组件级重命名和属性弃用，以及即将推出的动态主题路线。请阅读 migration.md