Angular Material Experimental：在 Angular 项目中使用实验性 Material 组件（安装、Sass 配置与 MDC 主题实践）

Angular Material Experimental：在 Angular 项目中使用实验性 Material 组件（安装、Sass 配置与 MDC 主题实践）

【免费下载链接】componentsComponent infrastructure and Material Design components for Angular项目地址: https://gitcode.com/GitHub_Trending/co/components

导读

@angular/material-experimental是 Angular Material 官方仓库中用于承载原型组件与实验功能的独立 npm 包，它与 Angular Material 同步发布，但其中任何内容都不视为稳定或生产就绪。本文基于 src/material-experimental/README.md 及其仓库源码，完整讲解该包的安装步骤、angular.json中 Sass include path 的必要配置、组件的导入与模板用法，以及带-mdc后缀的主题与排版 mixin 的正确组合方式；读完本文，你将能够在已有 Angular Material 应用上以最小成本接入实验性组件，并理解其背后的包结构与源码实现。

注意：本文所述实验性 API 可能在任何版本中发生破坏性变更（breaking changes），升级前请查阅当前版本的 CHANGELOG.md。

一、什么是 Angular Material Experimental

从仓库目录结构可以看出，该包位于 src/material-experimental，其 package.json 声明的包名为@angular/material-experimental，描述为 "Experimental components for Angular Material"，许可证为 MIT。

它的定位非常明确：存放正在开发中的原型（prototypes）与实验（experiments）。包随 Angular Material 一起发布，但：

• 不保证 API 稳定，任何发布都可能包含破坏性变更；
• 不被推荐直接用于生产环境；
• 部分实验组件可能尚未被纳入预构建 CSS 中，需要显式引入对应主题 mixin（README 第 5 步特别提示了这一点）。

1.1 仓库中的实验性组件

从 src/material-experimental 目录看，当前包内包含四个实验性功能模块：

其中 menubar/menubar.ts 是一个典型例子：MatMenuBar组件通过selector: 'mat-menubar'暴露，exportAs: 'matMenubar'，并在providers中注册CdkMenuGroup、CdkMenuBar、CDK_MENU与MENU_STACK，即完全基于@angular/cdk/menu的CdkMenuBar能力进行 Material 样式封装。由此可见，实验包普遍遵循“CDK 提供行为逻辑、Material 提供视觉样式”的分层设计。

二、安装与项目配置（完整步骤）

2.1 安装包

在已运行 Angular Material 的应用中，执行：

npm i @angular/material-experimental

该包的 package.json 声明了严格的 peerDependencies，安装前请确保版本匹配：

• @angular/cdk（与包同版本占位符）
• @angular/core、@angular/common、@angular/forms、@angular/platform-browser
• @angular/material
• @angular/cdk-experimental

也就是说，@angular/material-experimental同时依赖@angular/material与@angular/cdk-experimental，使用前需要这两个包都存在。

2.2 配置 Sass include path（关键一步）

实验组件基于 MDC Web 构建，其 Sass 文件中会引用 MDC Web 的 Sass 文件。为了让 Sass 编译器能够找到这些文件，必须在项目的angular.json中把node_modules/加入stylePreprocessorOptions.includePaths：

{ ... "styles": [ "src/styles.scss" ], "stylePreprocessorOptions": { "includePaths": [ "node_modules/" ] }, ... }

如果跳过这一步，编译主题 Sass 时会因无法解析 MDC Web 的@use/@import路径而报错。

2.3 导入组件

以复选框为例，在组件中直接导入MatCheckbox（新版独立组件风格）：

import {Component} from '@angular/core'; import {MatCheckbox} from '@angular/material/checkbox'; @Component({ imports: [MatCheckbox], // ... }) export class MyComponent {}

若你的项目仍使用 NgModule 体系，则按 Angular Material 惯例在模块的imports中引入对应模块即可；实验包内各模块均提供*-Module（如 column-resize-module.ts 中的MatColumnResizeModule、menubar-module.ts 等）。

2.4 模板中使用

实验组件与普通 Angular Material 组件的用法完全一致，例如：

<mat-checkbox [checked]="isChecked">Check me</mat-checkbox>

其他实验组件的使用形态可在 dev-app 对应目录中查看真实示例（如 src/dev-app/menubar、src/dev-app/column-resize）。

三、主题与排版：-mdc后缀 mixin 的使用

README 第 5 步是整个接入流程的核心：实验组件的主题 mixin 与常规 Angular Material mixin 对齐，但后缀为-mdc。推荐写法如下：

@use '@angular/material' as mat; @use '@angular/material-experimental' as mat-experimental; $my-primary: mat.define-palette(mat.$indigo-palette); $my-accent: mat.define-palette(mat.$pink-palette, A200, A100, A400); $my-theme: mat.define-light-theme(( color: ( primary: $my-primary, accent: $my-accent ), // 使用 define-mdc-typography-config 而非 define-typography-config， // 会直接根据官方 Material Design 样式生成排版配置， // 并采用规范推荐的 rem 单位（而非 px 单位）。 typography: mat-experimental.define-mdc-typography-config(), // 本主题使用的密度等级，未指定时默认为 0。 density: 0 )); @include mat-experimental.all-mdc-component-themes($my-theme);

要点解读：

1. define-mdc-typography-config()：实验包提供的 MDC 版排版配置函数，生成基于官方 Material Design 样式的 typography config，且使用rem而非px度量，更贴合 Material 规范推荐。
2. all-mdc-component-themes($theme)：一次性为所有 MDC 实验组件应用主题。README 同时提醒：部分实验组件可能尚未被纳入这个预构建的 CSS mixin 中，此时需要显式单独引入对应组件的主题 mixin。

3.1 源码中的主题 mixin 结构

从仓库源码可以印证-mdc主题体系的组织方式。实验包的 Sass 入口 src/material-experimental/_index.scss 通过@forward导出各组件主题：

// Component themes @forward './column-resize/column-resize-theme' as column-resize-* show column-resize-color, column-resize-typography, column-resize-density, column-resize-theme; @forward './popover-edit/popover-edit-theme' as popover-edit-* show popover-edit-color, popover-edit-typography, popover-edit-density, popover-edit-theme;

注意_index.scss中show限定导出的每个组件主题均拆分为color、typography、density、theme四个子 mixin；package.json 的exports字段把"."的sass入口指向./_index.scss，这正是@use '@angular/material-experimental'能够解析到主题 mixin 的原因。

以 column-resize/_column-resize-theme.scss 为例，可以看到：

• colormixin 通过 CSS 自定义属性（--mat-column-resize-outline-color、--mat-column-resize-outline-hover-color、--mat-column-resize-outline-active-color）定义主题色，并在无选择器上下文时自动包裹html根选择器；
• typography与densitymixin 目前为空实现，说明该组件暂未定制排版与密度；
• 完整thememixin 使用mat.theme-has(...)判断主题 map 中是否包含对应维度，再决定是否调用子 mixin，与 Material 主包的主题架构保持一致。

这种"入口转发 + 子 mixin 拆分"的结构，意味着你可以像使用mat.xxx-component-theme一样，对实验组件做细粒度控制，例如只引入 color：

@include mat-experimental.column-resize-color($my-theme);

3.2 版本与许可

version.ts 通过@angular/core的Version类暴露VERSION常量（构建时替换为真实版本号），用法与主包一致：

import {VERSION} from '@angular/material-experimental'; console.log(VERSION.major); // 当前主版本号

四、实验包源码速览：四个模块的实现要点

为便于读者评估是否值得接入，以下结合源码给出四个模块的入口与实现特征（以下描述基于当前仓库源码结构）。

4.1 column-resize：表格列宽拖拽

src/material-experimental/column-resize 提供四种指令：

• MatColumnResize（selector: 'table[mat-table][columnResize]'）与MatColumnResizeFlex（selector: 'mat-table[columnResize]'）：手动开启列宽调整；
• MatDefaultEnabledColumnResize（selector: 'table[mat-table]'）与MatDefaultEnabledColumnResizeFlex（selector: 'mat-table'）：默认开启列宽调整。

其主题中的.mat-column-resize-overlay-thumb拖拽手柄样式、cdk-resizable-resize-disabled禁用态、[dir='rtl']双向布局适配等细节，均可在 column-resize/_column-resize-theme.scss 中查阅。

4.2 menubar：Material 菜单栏

menubar/menubar.ts 中MatMenuBar extends CdkMenuBar，直接复用 CDK 菜单的键盘导航、焦点管理与子菜单触发逻辑，仅补充mat-menubar类与 Material 视觉。配套 menubar-item.ts 提供菜单项，模板见 menubar.html、menubar-item.html。

4.3 popover-edit：单元格弹层编辑

popover-edit 通过 table-directives.ts 将编辑弹层（lens）挂接到表格行/单元格，由 lens-directives.ts 定义弹层形态，适合在表格内实现行内编辑体验。

4.4 selection：行选择能力

selection 提供 row-selection.ts、select-all.ts、selection-toggle.ts 与 selection-column.ts，封装表格行选择、全选及选择列。

五、常见问题与注意事项

1. Sass 编译报错找不到 MDC 文件：请确认angular.json中stylePreprocessorOptions.includePaths已包含node_modules/（见 2.2 节），这是实验包主题可用的前提。
2. 组件样式未生效：确认是否在 Sass 中调用了all-mdc-component-themes（或对应组件单独的主题 mixin）；README 明确指出部分实验组件尚未进入预构建 CSS，需显式 include。
3. 版本同步：实验包与@angular/material、@angular/cdk同版本发布，peerDependencies 要求三者版本一致，混用不同版本可能导致类型或运行时错误。
4. 破坏性变更：包内 API 均视为实验性，任何 release 都可能改变签名或行为，升级前务必阅读 CHANGELOG.md 与 guides 中的迁移文档。
5. 生产使用需谨慎：README 明确 "Nothing in this package is considered stable or production ready"，如需在正式项目使用，应做好充分的测试与锁定版本策略。

六、总结

@angular/material-experimental是 Angular 官方为前沿组件能力提供的一个"预览通道"：通过npm i @angular/material-experimental安装、在angular.json中配置 Sass include path、以与常规 Material 组件一致的 API 使用，并借助-mdc后缀主题 mixin 完成视觉定制。其底层实现遵循"CDK 提供行为、Material 提供样式"的架构（如 menubar.ts 对CdkMenuBar的扩展），主题体系则通过 _index.scss 按组件转发color/typography/density/theme子 mixin。理解这些机制后，你就可以安全、可控地在项目中评估和试用这些实验性组件，并在其成熟后平滑迁移。

【免费下载链接】componentsComponent infrastructure and Material Design components for Angular项目地址: https://gitcode.com/GitHub_Trending/co/components