用 Angular Material 主题机制修改 mat-toolbar 背景色示例

在定制 Angular Material 主题时，一个常见需求是通过 Theme 配置调整 mat-toolbar 的背景色，而非在组件中硬编码颜色值。经过深入研究和实践，我成功理清了这一机制，现分享解决方案，帮助遇到同样问题的开发者快速解决。

问题显现

首先分析 mat-toolbar（简称 toolbar）的源码。在 _toolbar-theme.scss 文件中，其背景色直接引用自 Theme 的 background palette 中的 app-bar 字段：

background: theming.get-color-from-palette($background, app-bar);

于是直接修改 app-bar 的颜色值，理所当然写下以下 SCSS：

$app-bar-background: map-get(mat.$grey-palette, 900);
$background-palette: map-get($theme, background);
$background-palette: map-merge($background-palette, (app-bar: $app-bar-background));
$theme: map-merge($theme, (background: $background-palette));

提示：第一行代码即为期望的背景色值。

然而实际修改后发现 toolbar 背景色并未改变。有趣的是，使用以下代码读取修改后的背景色却能正确返回新值：

$background-palette: map-get($theme, background);
background-color: mat.get-color-from-palette($background-palette, app-bar);

这表明 mat-toolbar 并非直接读取主题的 background 调色板。进一步排查发现，问题根源在于 Theme 的版本机制。

根本原因：Legacy Theme 兼容模式

查阅 define-light-theme 的实现源码 _theming.scss，发现如下逻辑：

@if $accent != null {
    @warn $_legacy-theme-warning;
    @return private-create-backwards-compatibility-theme(_mat-validate-theme((
      _is-legacy-theme: true,
      color: _mat-create-light-color-config($primary, $accent, $warn),
    )));
  }

结合警告信息与返回值，可以推断 toolbar 采用的是 Legacy Theme 机制，而非直接读取顶层 background 属性。

进一步验证 _toolbar-theme.scss 中的 theme mixin 如下：

@mixin theme($theme-or-color-config) {
  $theme: theming.private-legacy-get-theme($theme-or-color-config);
  @include theming.private-check-duplicate-theme-styles($theme, 'mat-toolbar') {
    $color: theming.get-color-config($theme);
    $density: theming.get-density-config($theme);
    $typography: theming.get-typography-config($theme);
    // ...
  }
}

果然，入口调用了 private-legacy-get-theme，确认是 Legacy Theme。

最终解决方案

由于 toolbar 遵循 Legacy 路径，它应从 $theme.color.background 嵌套路径获取 app-bar，而非直接读取 $theme.background。因此在修改顶层背景色的基础上，还需补充对 color 嵌套域的修改：

$color-palette: map-get($theme, color);
$color-background-palette: map-get($color-palette, background);
$color-background-palette: map-merge($color-background-palette, (app-bar: $app-bar-background));
$color-palette: map-merge($color-palette, (background: $color-background-palette));
$theme: map-merge($theme, (color: $color-palette));

至此逻辑闭环——修改顶层 background 只是第一步；实际颜色值隐藏在 color 下的 background 调色板中。两处均修改后，toolbar 的背景色即可稳定变为所需的 $app-bar-background。

此外，以下是解决过程中参考的关键资源，供遇到类似问题的开发者查阅：

• Changing the background color in an Angular Material theme
• How to get the current angular theme's color of a specific component
• Allow overriding of theme background and foreground colors

透彻理解原理远比机械复制代码高效。希望本文能帮助你避开这个常见陷阱。