MatToolbar 颜色属性在 Angular Material v18 中的失效与解决

问题描述

升级到 Angular Material v18 后，开发人员普遍遇到 mat-toolbar 的 color 属性失效问题。具体表现为以下现象：

• color="primary" 在工具栏组件上不产生任何视觉效果
• 工具栏与背景色（通常是白色）几乎无法区分
• 其他 Material 组件（如按钮、图标）的颜色属性工作正常
• 手动添加 CSS 背景色可生效，但违背 Material 主题规范

<!-- 以下代码在 v18 中失效 -->
<mat-toolbar color="primary">工具栏内容</mat-toolbar>

根本原因

该问题源于 Angular Material v18 过渡到 Material Design 3 (M3) 规范：

1. color 属性是 Material Design 2 (M2) 的遗留功能
2. M3 已弃用此属性且默认不提供向后兼容
3. 工具栏组件在 M3 中使用新的 --mat-toolbar-container-background-color 变量
4. 其他组件（如按钮）因有过渡方案暂不受影响

解决方案

方案一：启用向后兼容样式（快速修复）

在全局样式文件（如 styles.scss）中添加向后兼容支持：

// styles.scss
@use '@angular/material' as mat;

$theme: mat.define-theme((
  color: (
    theme-type: light,
    primary: mat.$rose-palette,  // 使用红玫瑰色板
    tertiary: mat.$red-palette   // 使用红色辅助色板
  )
));

html {
  @include mat.all-component-themes($theme);
  // 启用旧版 color 属性支持 ↓
  @include mat.color-variants-backwards-compatibility($theme);
}

注意事项

此方案会降低 M3 新特性利用率，适合需要短期迁移的项目

方案二：使用 M3 推荐方式（官方推荐）

通过 CSS 变量覆盖工具栏主题：

// styles.scss 或组件样式
@use '@angular/material' as mat;

:root {
  // 使用系统默认主题变量 ↓
  --mat-toolbar-container-background-color: var(--mat-sys-primary-container);
  --mat-toolbar-container-text-color: var(--mat-sys-primary);
}

// 图标按钮颜色修正
.example-icon {
  color: var(--mat-sys-primary);
}

可通过 .dark-theme 等选择器实现深色模式适配：

<!-- HTML 中使用主题类 -->
<div class="light-theme">
  <mat-toolbar>亮色工具栏</mat-toolbar>
</div>
<div class="dark-theme">
  <mat-toolbar>深色工具栏</mat-toolbar>
</div>

方案三：自定义主题覆盖（高阶需求）

创建工具栏专属主题 mixin：

// _custom-toolbar-theme.scss
@mixin toolbar-theme($theme) {
  mat-toolbar {
    --mat-toolbar-container-background-color: #{mat.get-theme-color($theme, primary, 80)};
  }
}

// styles.scss
@use '@angular/material' as mat;

$light-theme: mat.define-theme((color: (theme-type: light, ...)));
$dark-theme: mat.define-theme((color: (theme-type: dark, ...)));

:root {
  @include mat.all-component-themes($light-theme);
  @include toolbar-theme($light-theme);
}

.dark-theme {
  @include mat.all-component-colors($dark-theme);
  @include toolbar-theme($dark-theme);
}

方案对比

方案	复杂度	可维护性	框架兼容性
向后兼容样式	★☆☆☆☆	★★☆☆☆	过渡期方案
M3 变量覆盖	★★★☆☆	★★★★☆	未来友好
自定义主题mixin	★★★★☆	★★★★★	大型项目首选

结论

1. 优先采用方案二使用系统 CSS 变量覆盖，符合 M3 设计规范且无需启用遗留特性
2. 需要快速迁移的项目可使用方案一添加 @include mat.color-variants-backwards-compatibility
3. 复杂应用场景推荐方案三，通过主题 mixin 实现完全自定义
4. 避免直接使用硬编码的背景色，会破坏 Material 主题的一致性

验证步骤

1. 在浏览器开发者工具中检查 mat-toolbar 计算样式
2. 确认 --mat-toolbar-container-background-color 是否应用成功
3. 检查其他主题变量值是否与目标调色板匹配

官方主题系统变量参考 ↗