全新 UI 震撼来袭！ng-matero v18 正式发布！

前言

断断续续折腾了近两周，ng-matero v18 终于发布了。其中最大的亮点是启用 Material 3 主题以及全新的 UI 设计。特别说明，这是 ng-matero 发布五年以来首次 UI 大改版！本文重点聊一下 Material 3 的使用方式以及 v18 的几个小变化。

仓库：https://github.com/ng-matero/ng-matero
预览：https://ng-matero.github.io/ng-matero/

如何使用 Material 3 主题

为了适配 M3，Angular Material 从 v16 开始对主题系统进行了大刀阔斧的改动。v16 将所有主题样式全部拆分到 CSS token 中；v17 在 Material 实验库中增加 M3 的 CSS token，提供实验性支持；v18 正式发布 M3 主题，所有 M2 主题配置都增加 m2- 前缀。

这些变化在用户层面是无感知的，使用 ng update 自动升级时，原有配置都会自动添加 m2- 前缀。使用 M3 主题的方式如下：

@use '@angular/material' as mat;

@include mat.core();

$my-theme: mat.define-theme((
  color: (
    theme-type: light,
    primary: mat.$violet-palette,
  ),
));

html {
  @include mat.all-component-themes($my-theme);
}

如果使用了 Material 的扩展组件库，则必须使用 mat.private-deep-merge-all 额外处理一下主题配置的合并。

@use '@angular/material' as mat;
@use '@ng-matero/extensions' as mtx;

...

$my-theme: mat.private-deep-merge-all(
  mat.define-theme($my-config),
  mtx.define-theme($my-config)
);

html {
  @include mat.all-component-themes($my-theme);
  @include mtx.all-component-themes($my-theme);
}

讲几句题外话，增加 M3 主题之后，Angular Material 的主题系统变得更加复杂，想要扩展 Material 的组件的难度也加大了。通过 define-theme 生成的配置项结构如下：

$theme: (
  _mat-theming-internals-do-not-access: (
    theme-version: 1,
    theme-type: light,
    palettes: (...),
    color-tokens: (...),
    typography-tokens: (...)
    ...
  )
)

所以，Material 扩展库的主题配置也必须使用 _mat-theming-internals-do-not-access 作为 key 才能融合到已有的主题系统中。如果有时间的话，我会专门写文章介绍 Angular Material 的主题系统。

如何自定义 Material 3 主题

在 Material 3 中，增加了一个 color roles 的概念（什么是 color roles?），主题定制就是更改这些颜色变量。

在 Angular Material 中，所有 color roles 都有对应的 CSS token，但是默认情况下，Angular Material 的组件都是从主题配置的调色盘中取色的，这些 CSS token 并不会暴露出来。如果想使用自定义主题，必须用下面的方式开启：

$my-material-app-theme: mat.define-theme(
  (
    color: (
      theme-type: light,
      primary: mat.$azure-palette,
      tertiary: mat.$blue-palette,
      use-system-variables: true, // 👈 Added
    ),
    typography: (
      use-system-variables: true, // 👈 Added
    ),
    density: (
      scale: 0,
    ),
  )
);

请注意：打开上面的配置之后，所有的颜色都消失了，你必须手动添加 color roles 才可以。有关自定义主题的更多内容，请阅读下面的文章。

• 使用 CSS 变量更改 Angular Material 主题
• Angular Material 的主题生成器

Material 3 的颜色助手

在 ng-matero v18 中，颜色助手的调色盘已经更新到 Material 3。所谓的颜色助手就是一些辅助类，你可以使用比如 bg-red-50、text-red-50、border-red-50 这样的 class 去设置 CSS 的颜色属性。

M2 和 M3 的调色盘最大的区别就是颜色的 hue，另外 M3 的预设颜色数减少了。其实 M3 的调色盘是 Angular Material 单独定义的，在 Material Design 的官方网站中，我并没有找到具体的介绍，不过 M2 的调色盘是有明确定义的，请查看 2014 Material Design color palettes。

M2 的调色盘（19 色）

M3 的调色盘（12 色）

优化侧边栏的收窄效果

侧边栏的收窄效果是一个很久远的遗留问题，详情可以查看这个 issue。该问题本身其实并不复杂，最简单的修复方式就是在侧边栏收窄的时候把子菜单收起来，而且大部分 admin 模板也是这么处理的。但是我个人觉得这种处理方式并不理想，由于迟迟没找到理想的解决方案，所以就一直拖着（其实用户也可以自行修复）。

在 ng-matero v18 中，经过一整天的思想斗争，这个问题终于圆满解决。在侧边栏收窄的时候显示子菜单的图标，展开的时候隐藏，如果没有设置子菜单的图标，则显示第一个文本字符。

新的资源文件夹

如果你创建一个 Angular 18 的新项目，你会发现原来的 assets 文件夹不见了，而根目录多了一个 public 文件夹。这个变化使得 src 目录再次精简（只剩一个 app 目录），另一方面，就是项目内静态文件的地址不需要再加 /assets 前缀。不过对于想升级的朋友来说也不用惊慌，这个变化并不是一个 break change，因为之前的项目并不会受影响，这种引用变化主要是在 angular.json 中调整的。

{
  "projects": {
    "ng-matero": {
      "architect": {
        "build": {
-         "assets": [
-           "src/favicon.ico",
-           "src/assets"
-         ],
+         "assets": [
+           {
+             "glob": "**/*",
+             "input": "public"
+           }
+         ],
...

总结

升级 ng-matero v18 最大的难点是 UI 设计的部分，本人虽有一定的审美基础，但在修改的过程中还是遇到很大挑战。一方面想要融合 Material 3 的设计风格，给人耳目一新的感受；另一方面又不想改动太大，以免失去产品固有的一些特点。这种变与不变之间的分寸是最难拿捏的。那么你喜欢最新的 UI 设计吗？