将Angular Material M2主题转换为M3的技术咨询

问题背景 #

现有基于 Angular Material M2 的自定义主题，包含自定义调色板、主题定义，以及大量前景/背景色的自定义配置。需要将其迁移至 M3 主题，同时保留原有颜色匹配，明确原自定义前景/背景色在 M3 中的配置方式。

迁移步骤 #

1. 迁移自定义调色板至 M3 #

M3 的调色板定义逻辑与 M2 类似，可直接复用原有 M2 的色值，仅需调整函数调用（M3 移除了 m2- 前缀）。对比色可沿用原有配置，或根据 M3 的对比度标准微调。

示例（绿色调色板）：

$green-palette: mat.define-palette(
  (
    50: #e7f7eb,
    100: #c5eace,
    200: #a0dcb0,
    300: #77d090,
    400: #57c578,
    500: #33ba60, // 主色
    600: #2aaa56,
    700: #1f984a,
    800: #13873f,
    900: #00672b,
    contrast: (
      50: #000000,
      100: #000000,
      200: #000000,
      300: #000000,
      400: #000000,
      500: #ffffff,
      600: #ffffff,
      700: #ffffff,
      800: #ffffff,
      900: #ffffff,
    ),
  ),
  500, // 主色索引
  300, // 浅色索引
  700  // 深色索引
);

// 其他调色板按相同逻辑迁移
$orange-palette: mat.define-palette(/* 原有橙色色值集合 */, 300, 200, 500);
$red-palette: mat.define-palette(/* 原有红色色值集合 */, 400, 300, 600);
$blue-palette: mat.define-palette(/* 原有蓝色色值集合 */, 700, 400, 800);

2. 定义 M3 主题 #

M3 使用 mat.define-light-theme/mat.define-dark-theme 定义主题，颜色配置中 secondary 对应 M2 的 accent，其余逻辑与 M2 一致。

示例：

// 定义 M3 浅色主题
$theme: mat.define-light-theme((
  color: (
    primary: $green-palette,
    secondary: $orange-palette, // 替代 M2 的 accent
    warn: $red-palette,
  ),
  typography: mat.define-typography-config(), // 可复用原有排版配置或使用 M3 默认
  density: 0,
));

3. 映射原自定义前景/背景色至 M3 Token 系统 #

M3 不再使用 M2 中的 foreground/background 调色板，而是通过系统级 Token和组件级 Token来配置颜色。需将原有自定义值映射到对应的 M3 Token。

系统级前景/背景 Token 配置

通过修改主题的颜色配置，覆盖系统级 Token：

// 获取当前主题的颜色配置
$color-config: mat.get-color-config($theme);

// 覆盖背景类 Token（对应原 M2 的 background 调色板）
$color-config: map.merge($color-config, (
  tokens: (
    md-sys-color-background: #f6f6f6,       // 原 M2 background
    md-sys-color-surface: #ffffff,          // 原 M2 card/dialog
    md-sys-color-surface-container: #f5f5f5,// 原 M2 app-bar
    md-sys-color-surface-dim: #e0e0e0,      // 原 M2 status-bar
    md-sys-color-inverse-surface: #000000,  // 原 M2 tooltip 背景
  )
));

// 覆盖前景类 Token（对应原 M2 的 foreground 调色板）
$color-config: map.merge($color-config, (
  tokens: (
    md-sys-color-on-surface: #000000,                  // 原 M2 base/text
    md-sys-color-outline: rgba(0, 0, 0, 0.12),        // 原 M2 divider/dividers
    md-sys-color-on-surface-variant: rgba(0, 0, 0, 0.38), // 原 M2 disabled/hint-text
    md-sys-color-on-secondary-container: #424242,     // 原 M2 secondary-text/icon
  )
));

// 更新主题
$theme: mat.update-theme($theme, (color: $color-config));

组件级状态颜色配置

对于组件特定的状态（如按钮 hover、选中，芯片未选中状态等），需针对组件的 Token 进行配置：

// 自定义按钮状态颜色
$button-config: mat.get-component-config($theme, button);
$button-config: map.merge($button-config, (
  tokens: (
    md-sys-color-hover-state-layer: rgba(0, 0, 0, 0.04), // 原 M2 hover
    md-sys-color-selected-state-layer: #e0e0e0,         // 原 M2 selected-button
    md-sys-color-disabled-container: rgba(0, 0, 0, 0.12),// 原 M2 disabled-button
  )
));
$theme: mat.update-theme($theme, (button: $button-config));

// 自定义芯片未选中状态
$chip-config: mat.get-component-config($theme, chip);
$chip-config: map.merge($chip-config, (
  tokens: (
    md-sys-color-unselected-container: #e0e0e0, // 原 M2 unselected-chip
  )
));
$theme: mat.update-theme($theme, (chip: $chip-config));

关键注意事项 #

• M3 的 Token 系统遵循 Material Design 3 的设计规范，优先使用系统级 Token 保证全局一致性，组件级 Token 用于特殊定制
• 若原有自定义颜色无法直接对应系统 Token，可通过自定义 CSS 变量或组件样式直接覆盖
• 迁移后需验证组件的对比度和视觉效果，确保符合 M3 的设计要求

内容的提问来源于stack exchange，提问作者Kees de Bruin