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，供旧项目使用。
• 动画 peer 依赖已移除（v21.2+）： Material 不再声明 @angular/animations peer 依赖，而是通过原生 CSS 实现动画。在 21.2+/22 上执行 ng add @angular/material 不会配置 provideAnimationsAsync()，也不需要 @angular/animations；新建 Material 22 应用时，两者都不要添加。（更早的 v21.x 和所有 v18-20 应用仍需要该 provider；请参阅 setup.md。）
• 适用项目： Material v19 → v22 项目（M3 主题系统于 v19 引入；更早的主版本使用 M2，以及现已弃用的 mat.define-light-theme / mat.define-dark-theme API）。
• **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）

增量式次要版本更新，没有破坏性变更。peer 依赖不变（@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），且日期选择器会在 Signal Forms 下报告解析错误（22.2.4）。
• **CDK overlay 的 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 的升级带来了实质性的 API 变化，不只是 Angular 版本升级。请留意：

• **组合框：**旧版组合框和自动完成已提升为正式 API / 移除。SimpleCombobox 已提升为 Combobox，所有 simpleCombobox* 符号均重命名为 combobox*。
• **列表：**移除了 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 支持 Portal 指令。
• 支持分别设置标签页动画时长（每个标签页单独设置进入／退出时长）。

1. 回答前先检查项目的 Material 版本。 Material 的 M3 主题引擎于 v19 引入（以 mat.theme() mixin 取代 mat.define-light-theme 和 mat.define-dark-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。
   • 这两套系统的编译结果和行为差异很大。参见 theming.md。

3. 从 v15 起，组件均为独立组件。 始终导入独立类（例如，从 '@angular/material/button' 导入 MatButton），不要导入旧版 MatButtonModule。这些模块仍会重新导出所有内容以保持向后兼容，但新代码中不应使用它们。

4. 生成 Material 代码后，运行 ng build。 最常见的 AI 错误包括：(a) 在 v19+ 项目中使用 v17 时代的 mat.define-light-theme 语法（可以编译，但不会生成任何 CSS 变量）；(b) 在 v18-v21.1 中忘记添加 provideAnimationsAsync()，导致波纹、菜单打开／关闭以及对话框背景遮罩动画失效（在 21.2+/22 中不要添加它，Material 通过原生 CSS 实现动画）；(c) 缺少 @angular/cdk 对等依赖，Material 的导入会连带依赖它；(d) 使用 MatTable 却没有配置 MatSort／MatPaginator，列标题上的排序 UI 会显示，但不起作用。

Material 架构：组件、CDK、主题

Angular Material 提供三个层：

• 组件（@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 mixin（mat.theme()、mat.theme-overrides()）。必须使用 Sass，不支持仅用 CSS 的主题方案。

默认从 @angular/material/<component> 导入（例如，MatButton from '@angular/material/button'）。只有在需要无头原语，或要构建一个组合使用 Material 行为的自定义样式组件时，才使用 @angular/cdk/<primitive>。

安装与主题

• 设置：ng add @angular/material（负责安装并写入默认主题；在 v18-v21.1 中还会配置 provideAnimationsAsync()，在 21.2+/22 中则不会，Material 通过原生 CSS 实现动画），也可以手动安装。阅读 setup.md
• 主题（M3）：mat.theme() mixin、预构建调色板（mat.$violet-palette、mat.$azure-palette 等）、密度和排版选项、light dark 配色方案，以及通过 mat.<component>-overrides() 设置组件级覆盖。阅读 theming.md
• M2 → M3 迁移：v19 ng-update schematic 和手动修复模式。阅读 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）、Drag-Drop、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