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 の削除項目）。詳しくは 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 では、module から standalone への移行、i18n プロバイダーの変更、v22 での削除、各バージョンで非推奨となった項目について説明しています。
• Angular： v17 以降（standalone コンポーネントと新しい制御フローに対応）。ng-zorro-antd@22 には v22 が必要です。v22 が最も適しています。
• Zoneless／OnPush： NG-ZORRO は zoneless の変更検知と ChangeDetectionStrategy.OnPush を正式にサポートしています。コンポーネントはシグナルに対応しており、必要に応じて内部で markForCheck() を使用します。
• SSR： 完全にサポートしています。Angular Universal／@angular/ssr で動作します。
• 国際化： ルートで provideNzI18n(en_US) を設定し、NzI18nService を使って実行時にロケールを切り替えます。
• サポート対象外： NG-ZORRO v16 以前（Angular v16 以前、NgModule のみのパターン、シグナル非対応）。

プロジェクトの ng-zorro-antd のメジャーバージョンが @angular/core と一致しない場合、npm の peer dependency チェックでインストールに失敗します。まず Angular をアップグレードし、その後 NG-ZORRO も同じメジャーバージョンにアップグレードするようユーザーに伝えてください。詳しくは migration.md を参照してください。

1. 回答する前に、プロジェクトの NG-ZORRO のバージョンを確認してください。 メジャーバージョンは Angular に追従し、実際の変更を取り込みます。i18n プロバイダーは v17 で provideNzI18n になり、完全な standalone クラスのエクスポートは v18 で導入されました。動的テーマは v21 でも実験的です。package.json を正としてください。

2. 最初にインポート方式を確認してください。 v18 より前のコードでは Nz*Module をインポートし、@NgModule.imports に登録します。v18 以降では、各コンポーネントが standalone クラス（例：NzButtonComponent）としてエクスポートされ、さらに nz-button 属性用の NzButtonDirective など、スリムなディレクティブ群もエクスポートされます。v18 以降のプロジェクトでは、新しいコードで standalone インポートを使用し、Nz*Module は使用しないでください。どちらの方式も引き続き動作し、1 つのテンプレート内で併用しても問題ありません。詳しくは 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）v17 でプロバイダーに置き換えられた、v15 時代の APP_INITIALIZER による nzI18nService の初期化を使用する。（d）provideNzIconsPatch を使わずに <nz-icon> を使用する、または provideNzIcons でアイコンを登録するのを忘れる。setup.md と migration.md を参照してください。

NG-ZORRO のアーキテクチャ：ディレクティブ、コンポーネント、サービス

NG-ZORRO では、3 つのパターンが使われています。コンポーネントがどのパターンを使うかを把握すると、組み込み方が変わります。

• ネイティブ要素に適用する属性ディレクティブ。例：<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 を優先するなど）。トースト、一時的な確認、プログラムから開くダイアログなど、表現が本質的に命令型の場合はサービス形式を使ってください。

インストールとテーマ設定

• セットアップ：ng add ng-zorro-antd（スケマティクスが i18n、スタイル、アニメーション、アイコン登録を処理します）。手動インストール、provideNzI18n、provideNzIcons、アニメーションの設定、よくある問題については、setup.md を参照してください。
• テーマ設定：LESS 変数のオーバーライド（@primary-color、@border-radius-base など）、同梱されている 4 つのプリセット（default、dark、compact、aliyun）、実験的な CSS 変数を使った動的テーマ、実行時のテーマ切り替えについては、theming.md を参照してください。

コンポーネント

NG-ZORRO では、70 を超えるコンポーネントが ng.ant.design/components/overview にカテゴリ別で記載されています。以下の各カテゴリファイルでは、該当するコンポーネント、その主な入力、一般的なパターン、注意点を説明しています。

• 一般：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 で説明しています。

フォーム連携

• フォーム：ReactiveForms（v17 以降のデフォルト）および Signal Forms（Angular v22 以降）への nz-form の組み込み、nz-form-item ／ nz-form-control ／ nz-form-label の 3 要素、非同期バリデーターと nzValidatingTip、カスタムコントロールの ControlValueAccessor パターンについては、forms.md を参照してください。

アクセシビリティ

• アクセシビリティ：NG-ZORRO が準拠する WAI-ARIA の規約、キーボードナビゲーション（特に Menu ／ Tree ／ Table）、Modal と Drawer のフォーカス管理、nzDirection による RTL サポートについては、accessibility.md を参照してください。

移行

• 移行：Module からスタンドアロンへの移行（v18）、provideNzI18n プロバイダー（v17）、provideNzIcons による <nz-icon> の登録（v17 以降）、v18 から v21 へのコンポーネントレベルの名称変更とプロパティの非推奨化、今後予定されている動的テーマへの道筋。migration.md をお読みください。