3. 开发环境搭建：项目初始化、依赖安装、Material 3主题配置

3.1 本章目标与基本原理

本章引导你从零搭建一个支持 Material 3（M3）Slot API 的 Vue 3 + Vite 开发环境。核心原理是：

• 主题系统：M3 使用 Design （设计令牌）定义颜色、字体、形状等语义值，通过 CSS 自定义属性或 JavaScript 注入应用范围。
• Slot API 依赖：组件库（如 @material/web）提供可插拔的插槽（slots），但需要正确配置主题上下文才能激活动态样式。
• 构建链路：Vite 负责模块打包，postcss 配合 sass 处理 M3 的 文件，最终生成响应式 CSS。

3.2 环境搭建完整流程

以下步骤在 Node.js ≥ 18 和 npm ≥ 9 环境下验证。推荐使用 Vue 3 + Vite 脚手架。

1. 项目初始化：npm create vite@latest m3-slot-demo -- --template vue-ts
2. 安装核心依赖：npm install @material/web @material/theme sass
3. 安装辅助类型（可选）：npm install -D @material/web/types
4. 创建主题配置文件：在 src/ 下新建 m3-theme.scss，定义自定义属性。
5. 引入主题并挂载：在 main.ts 中导入 SCSS 并调用 applyTheme()。
6. 验证：使用 MdTextButton 组件测试主题色是否生效。

3.3 依赖与版本对比

3.4 主题配置代码实现

在 src/m3-theme.scss 中定义主题令牌：

// src/m3-theme.scss
@use '@material/theme' with (
  $primary: #6750a4,
  $on-primary: #ffffff,
  $primary-container: #eaddff,
  $on-primary-container: #21005d,
  $secondary: #625b71,
  $on-secondary: #ffffff,
  $secondary-container: #e8def8,
  $on-secondary-container: #1d192b,
  $tertiary: #7d5260,
  $on-tertiary: #ffffff,
  $tertiary-container: #ffd8e4,
  $on-tertiary-container: #31111d,
  $error: #b3261e,
  $on-error: #ffffff,
  $error-container: #f9dedc,
  $on-error-container: #410e0b,
  $background: #fffbfe,
  $on-background: #1c1b1f,
  $surface: #fffbfe,
  $on-surface: #1c1b1f,
  $surface-variant: #e7e0ec,
  $on-surface-variant: #49454f,
  $outline: #79747e,
  $outline-variant: #cac4d0
);

@import '@material/theme/color-scheme';
@import '@material/theme/shape';
@import '@material/theme/typography';

:root {
  @include theme.core-styles;
}

在 main.ts 中引入并应用：

// src/main.ts
import { createApp } from 'vue'
import App from './App.vue'
import './m3-theme.scss' // 导入主题
import { applyTheme } from '@material/web/theme'

// 强制刷新主题变化
applyTheme(document.documentElement)

createApp(App).mount('#app')

3.5 验证环境：使用第一个 Slot 组件

在 App.vue 中引入 MdTextButton，测试 Slot 是否可以被主题着色：

<template>
  <md-text-button>
    <span slot="icon">★</span>
    <span>Hello M3 Theme</span>
  </md-text-button>
</template>

<script setup lang="ts">
import '@material/web/button/text-button.js'
</script>

运行 npm run dev，如果按钮背景色、文字颜色、图标颜色均与 m3-theme.scss 中定义的 $primary 一致，则主题配置成功。

3.6 常见错误与调试

3.7 环境结构概览（SVG 流程图）

3.8 性能与稳定性建议

• 按需导入：只导入用到的组件（如 import '@material/web/button/text-button.js'），避免全量加载。
• tree-shaking：确保 vite.config.ts 启用 build.rollupOptions.treeshake，消除未使用的令牌样式。
• 主题变量预热：将 applyTheme 调用放入 Vue.nextTick 或 onMounted，避免 DOM 未解析时执行。
• 防止主题闪烁：在 index.html 的 <head> 中内联基础主题 CSS，减少首次渲染无色。

3.9 与 Slot API 的衔接