angular-material-developer

Angular Material 開発者向けガイドライン

angular-developer と併用します。このスキルでは Angular の基礎（シグナル、DI、ルーティング、フォーム、SSR、アクセシビリティ）を扱います。このスキルでは Angular Material 固有の内容に焦点を当てます。最適な環境にするには、両方をインストールしてください。

互換性

• 対象: @angular/[email protected]（Angular v22）。@angular/[email protected] と組み合わせてください（Material は 完全一致する cdk バージョンをピア依存関係として要求するため、両方を同じバージョンに固定してください）。v21 に対応する系列は、レガシープロジェクト向けに 21.2.x のままです。
• アニメーションのピア依存関係を削除（v21.2 以降）: Material は @angular/animations をピア依存関係として宣言しなくなり、ネイティブ CSS でアニメーションを実行します。21.2 以降または 22 で ng add @angular/material を実行しても、provideAnimationsAsync() は設定されず、@angular/animations も不要です。新規の Material 22 アプリには、どちらも追加しないでください。（以前の v21.x とすべての v18～20 アプリでは引き続きプロバイダーが必要です。setup.md を参照してください。）
• 対応対象: Material v19～v22 のプロジェクト（M3 テーマシステムは v19 で導入されました。それ以前のメジャーバージョンでは、現在レガシーとなっている mat.define-light-theme／mat.define-dark-theme API を使った M2 が使用されていました）。
• Angular: v19 以降が必要です。v22 には Node 22 または 26 と TypeScript 6 が必要です。このスキルでは、スタンドアロンコンポーネント、制御フロー（@if／@for）、シグナルベースの API を前提としています。
• Sass: テーマ設定に必要です。ビルドパイプラインが .scss に対応している必要があります（Angular CLI はデフォルトで対応しています）。Material のテーマエンジンでは、スタンドアロンの CSS のみを使ったテーマ設定はサポートされていません。
• サポート対象外: Material v18 以前（M2 のみで、mat.define-*-theme() API を使用）、Angular v18 以前（NgModule パターンと古いアニメーション API を使用）。

v22.2 の主な変更点（22.1 から）

追加機能のみのマイナーバージョンで、破壊的変更はありません。ピア依存関係に変更はありません（@angular/core、forms、common、platform-browser は ^22.0.0 || ^23.0.0）。

• MatIcon の Material Symbols クラス自動設定（22.2.0）: Material Symbols フォントのみが読み込まれている場合、<mat-icon> が material-symbols-* クラスを自動的に追加するため、単一フォントの場合は setDefaultFontSetClass(...) が不要になりました。従来の Material Icons と Symbols の両方が読み込まれている場合は、以前の動作が適用されます。
• MatMenuItem の disabledInteractive（22.2.0）: フォーカス可能かつホバー可能な状態を維持したまま、無効時のスタイルを適用します。これにより、項目が無効な理由をツールチップで説明できます。
• **MatFormFieldControl が Signal Forms に対応（22.2.0）**し、datepicker は Signal Forms で解析エラーを報告します（22.2.4）。
• CDK オーバーレイの disposeOnNavigation: 'url-change'（22.2.1）: 戻る／進む操作だけでなく、URL が変更されるたびに閉じる設定を有効にできます。
• 知っておくとよいパッチ修正: CDK a11y が inert 要素をフォーカス不可として扱うようになりました（22.2.3）。chips にタッチターゲットが追加されました（22.2.3）。mat-icon がイベント属性をコピーしなくなりました（22.2.2）。

v22 の破壊的変更（v21 から）

v21 から v22 への移行では、Angular のバージョン更新だけでなく、実際に API が変更されています。次の点に注意してください。

• Combobox: レガシーの combobox と autocomplete が昇格または削除されました。SimpleCombobox は Combobox に昇格し、すべての simpleCombobox* シンボルが combobox* に名前変更されました。
• List: MatListOption.checkboxPosition が削除されました。代わりに togglePosition を使用してください。MatListOptionCheckboxPosition は MatListOptionTogglePosition に名前変更されました。
• CDK: ConfigurableFocusTrap と FocusTrap のコンストラクターで、injector パラメーターが必須になりました。ConfigurableFocusTrapFactory.create のブール値パラメーターは設定オブジェクトに置き換えられました。DropListRef.drop イベントのパラメーターが必須になりました。ContextMenuTracker は MenuTracker に名前変更されました。次の項目が削除されました：CDK_DESCRIBEDBY_HOST_ATTRIBUTE、CDK_DESCRIBEDBY_ID_PREFIX、MESSAGES_CONTAINER_ID。
• 複数のコンポーネント: Combobox、Listbox、Tree、Menu、Toolbar、Select で、input／model の名前が values から value に変更されました。可変長引数を取るコンストラクターが削除されました（Material または CDK のコンポーネントを拡張するコードに影響します）。
• Dialog／Overlay: ArrowViewState と ArrowViewStateTransition の型が削除されました。

これらの大半には、自動適用される ng update のマイグレーションがあります。判断に迷った場合は、手動で編集する前に ng update @angular/material を実行し、schematic に処理させてください。

v22 の知っておきたい新機能

• Signal Forms が安定版に（v21 では実験的機能でした）。Angular のシグナルベースのフォーム API が、本番環境で安心して使えるようになりました。mat-form-field は ReactiveFormsModule と Signal Forms のどちらとも組み合わせられます。
• Angular Aria が安定版に（プレビュー版でした）。新しいアクセシビリティのプリミティブがフレームワークに組み込まれ、一部のパターンでは CDK の a11y モジュールを利用する必要性が減ります。
• <button> コンポーネント内でボタンの進行状況インジケーターをサポート。
• ComponentPortal でポータルディレクティブをサポート。
• タブごとに個別のアニメーション時間を設定可能（タブごとの入場／退場タイミング）。

1. 回答する前に、プロジェクトの Material のバージョンを確認してください。 Material の M3 テーマエンジンは v19 で導入されました（mat.define-light-theme と mat.define-dark-theme を置き換える mat.theme() ミックスイン）。M3 向けに生成されたコードは、M2 プロジェクトではエラーを出さずに動作しなくなります。正しい情報源は package.json です。

2. styles.scss でテーマの世代を判別してください。

   • @include mat.theme((...)) がある場合 → M3（v19 以降、デフォルト）。mat.theme()、Material の組み込みパレット、CSS 変数のオーバーライドを使用します。
   • mat.define-light-theme(...) または mat.define-dark-theme(...) に加えて @include mat.all-component-themes($theme) がある場合 → M2（レガシー）。移行を推奨します。詳しくは migration.md を参照してください。
   • 2 つのシステムはコンパイル方法も動作も大きく異なります。theming.md を参照してください。

3. コンポーネントは v15 以降スタンドアロンです。 レガシーの MatButtonModule ではなく、スタンドアロンクラス（例：'@angular/material/button' の MatButton）を必ずインポートしてください。モジュールは後方互換性のため引き続きすべてを再エクスポートしますが、新しいコードには追加しないでください。

4. Material のコードを生成した後は、ng build を実行してください。 AI によるよくあるミスは次のとおりです。（a）v19 以降のプロジェクトで v17 時代の mat.define-light-theme 構文を使う（コンパイルは通りますが、CSS 変数が何も出力されません）。（b）v18〜v21.1 で provideAnimationsAsync() を忘れる（リップル、メニューの開閉、ダイアログの背景アニメーションが動作しなくなります。v21.2 以降／v22 では Material がネイティブ CSS でアニメーションするため、追加しないでください）。（c）@angular/cdk のピア依存関係が不足している（Material のインポートは CDK を経由します）。（d）MatSort／MatPaginator との連携なしに MatTable を使う（列ヘッダーにソート UI は表示されますが、機能しません）。

Material のアーキテクチャ：コンポーネント、CDK、テーマ設定

Angular Material には次の 3 つのレイヤーがあります。

• コンポーネント（@angular/material/*）：スタイル設定済みの mat-* コンポーネント本体です。MatButton、MatFormField、MatTable、MatDialog などがあります。それぞれに専用のインポートパスがあります。
• CDK（@angular/cdk/*）：Material がその上に構築する、スタイル設定のないプリミティブです。Overlay、Portal、A11y（FocusTrap、LiveAnnouncer、ListKeyManager）、DragDrop、VirtualScroll、Stepper があります。Material と併せてピア依存関係として必ずインストールします。 Material のスタイル設定は不要で、プリミティブだけが必要な場合に単独で便利です。cdk.md を参照してください。
• テーマエンジン（@angular/material/_index.scss）：各コンポーネントが使用する CSS 変数を出力する Sass ミックスイン（mat.theme()、mat.theme-overrides()）です。Sass が必須で、CSS のみでテーマを設定する方法はありません。

通常は @angular/material/<component> からインポートしてください（例：'@angular/material/button' の MatButton）。ヘッドレスのプリミティブが必要な場合や、Material の動作を組み合わせた独自スタイルのコンポーネントを作成する場合に限り、@angular/cdk/<primitive> を使用してください。

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

• セットアップ：ng add @angular/material を実行します（インストールを行い、デフォルトのテーマを設定します。v18〜v21.1 では provideAnimationsAsync() も設定しますが、21.2 以降／22 では設定しません。Material はネイティブ CSS でアニメーションします）。手動でインストールすることもできます。setup.md をお読みください。
• テーマ設定（M3）：mat.theme() ミックスイン、ビルトインパレット（mat.$violet-palette、mat.$azure-palette など）、密度とタイポグラフィの設定、light dark カラースキーム、mat.<component>-overrides() によるコンポーネントごとのオーバーライド。theming.md をお読みください。
• M2 から M3 への移行：v19 の ng-update スキーマティックと、手動で修正する際のパターン。migration.md をお読みください。

コンポーネント

Angular Material では、40 以上のコンポーネントがカテゴリ別にまとめられています。以下の各カテゴリファイルでは、コンポーネント、主要な入力、一般的なパターン、注意点を解説しています。

• フォームコントロール：Autocomplete、Checkbox、Datepicker、FormField、Input、Radio、Select、Slider、SlideToggle。form-controls.md をお読みください。
• ボタンとインジケーター：Button、ButtonToggle、Badge、Chip、Icon、ProgressBar、ProgressSpinner、Ripple。buttons-indicators.md をお読みください。
• レイアウト：Card、Divider、ExpansionPanel、GridList、List、Stepper、Tabs、Tree。layout.md をお読みください。
• ナビゲーション：Menu、Sidenav、Toolbar。navigation.md をお読みください。
• ポップアップとモーダル：BottomSheet、Dialog、Snackbar、Tooltip。overlays.md をお読みください。
• データテーブル：Table、Paginator、Sort、MatTableDataSource。data-table.md をお読みください。

CDK プリミティブ

• CDK：Overlay、Portal、A11y（FocusTrap、FocusMonitor、LiveAnnouncer、ListKeyManager）、ドラッグ＆ドロップ、VirtualScroll、Stepper、ScrollDispatcher、Layout（Breakpoints）。cdk.md をお読みください。

フォーム連携

• フォーム：mat-form-field、MatInput／MatSelect／MatDatepicker、ErrorStateMatcher のパターン、<mat-error> の表示、カスタムコントロール向けの ControlValueAccessor を使って、Material コンポーネントを ReactiveForms（標準的な方法）および Signal Forms（Angular v22 以降）に接続する方法。forms.md をお読みください。

アクセシビリティ

• アクセシビリティ：Material の WCAG 2.1 AA 準拠目標、キーボードとマウスでフォーカス時のスタイルを切り替える FocusMonitor、一時的なアナウンスに使う LiveAnnouncer、RTL サポート、Material が自動で対応することと、引き続き自分で対応する必要があること。accessibility.md をお読みください。