Vue 3 CSS Modules在Vue中的使用

1. CSS Modules简介

1.1 什么是CSS Modules

CSS Modules是一种CSS文件的处理方式，它将CSS类名局部化，避免了全局命名冲突。在Vue中，CSS Modules通过在<style>标签上添加module属性来启用。

1.2 CSS Modules的核心特性

• 局部作用域：默认情况下，所有类名都是局部的
• 唯一类名生成：自动生成唯一的类名，避免命名冲突
• JavaScript访问：可以通过JS访问CSS类名
• 类型安全：与TypeScript结合提供类型检查
• 预处理器支持：支持SCSS、LESS等预处理器

2. CSS Modules的基本使用

2.1 基本语法

<template>
  <div :class="styles.container">
    <h1 :class="styles.title">CSS Modules Demo</h1>
    <p :class="styles.description">This is a demonstration of CSS Modules in Vue.</p>
  </div>
</template>

<style module>
.container {
  max-width: 800px;
  margin: 0 auto;
  padding: 20px;
  background-color: #f5f5f5;
  border-radius: 8px;
}

.title {
  color: #42b983;
  font-size: 28px;
  margin-bottom: 16px;
}

.description {
  color: #666;
  line-height: 1.6;
}
</style>

2.2 类名生成规则

CSS Modules会将类名转换为唯一的标识符，默认格式为：

文件名_类名_hash值

例如：

HomeContainer_container_1a2b3c

3. CSS Modules的高级特性

3.1 多个类名

<template>
  <div :class="[styles.base, styles.active]">
    Multiple Classes
  </div>
</template>

<style module>
.base {
  padding: 10px;
  border: 1px solid #ddd;
}

.active {
  background-color: #42b983;
  color: white;
}
</style>

3.2 条件类名

<template>
  <div :class="[styles.button, isPrimary && styles.primary]">
    {{ buttonText }}
  </div>
</template>

<script>
export default {
  data() {
    return {
      isPrimary: true,
      buttonText: 'Primary Button'
    }
  }
}
</script>

<style module>
.button {
  padding: 8px 16px;
  border: none;
  border-radius: 4px;
  cursor: pointer;
}

.primary {
  background-color: #42b983;
  color: white;
}
</style>

3.3 动态类名

<template>
  <div :class="styles[`status-${status}`]">
    Current Status: {{ status }}
  </div>
</template>

<script>
export default {
  data() {
    return {
      status: 'success' // 可以是 'success', 'warning', 'error'
    }
  }
}
</script>

<style module>
.status-success {
  color: #42b983;
  background-color: #e8f5e8;
}

.status-warning {
  color: #ff9800;
  background-color: #fff3e0;
}

.status-error {
  color: #f44336;
  background-color: #ffebee;
}
</style>

4. CSS Modules与预处理器

4.1 SCSS示例

<template>
  <div :class="styles.card">
    <h2 :class="styles.cardTitle">{{ title }}</h2>
    <div :class="styles.cardContent">
      <slot></slot>
    </div>
  </div>
</template>

<script>
export default {
  props: {
    title: {
      type: String,
      required: true
    }
  }
}
</script>

<style module lang="scss">
$primary-color: #42b983;
$border-radius: 8px;

.card {
  border: 1px solid #e0e0e0;
  border-radius: $border-radius;
  overflow: hidden;
  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
  transition: transform 0.2s ease;
  
  &:hover {
    transform: translateY(-2px);
    box-shadow: 0 4px 12px rgba(0, 0, 0, 0.15);
  }
  
  .cardTitle {
    background-color: $primary-color;
    color: white;
    padding: 16px;
    margin: 0;
    font-size: 20px;
  }
  
  .cardContent {
    padding: 16px;
    color: #333;
  }
}
</style>

4.2 LESS示例

<template>
  <div :class="styles.box">
    <h3 :class="styles.boxTitle">{{ title }}</h3>
    <div :class="styles.boxBody">
      <slot></slot>
    </div>
  </div>
</template>

<script>
export default {
  props: {
    title: String
  }
}
</script>

<style module lang="less">
@border-color: #ddd;
@spacing: 16px;

.box {
  border: 1px solid @border-color;
  margin: @spacing 0;
  
  .boxTitle {
    background-color: #f0f0f0;
    padding: @spacing;
    margin: 0;
    font-size: 18px;
    border-bottom: 1px solid @border-color;
  }
  
  .boxBody {
    padding: @spacing;
  }
}
</style>

5. 自定义模块名

5.1 使用自定义模块名

默认情况下，CSS Modules通过styles对象访问类名。我们可以通过module="自定义名称"来指定自定义的模块名：

<template>
  <div :class="myStyles.container">
    <h1 :class="myStyles.title">Custom Module Name</h1>
  </div>
</template>

<style module="myStyles">
.container {
  background-color: #f0f0f0;
  padding: 20px;
}

.title {
  color: #35495e;
  font-size: 24px;
}
</style>

5.2 多个样式模块

一个组件可以有多个CSS Modules：

<template>
  <div :class="[layoutStyles.container, themeStyles.dark]">
    <h1 :class="[layoutStyles.title, themeStyles.heading]">
      Multiple Style Modules
    </h1>
  </div>
</template>

<style module="layoutStyles">
.container {
  max-width: 900px;
  margin: 0 auto;
  padding: 20px;
}

.title {
  font-size: 28px;
  margin-bottom: 20px;
}
</style>

<style module="themeStyles">
.dark {
  background-color: #2c3e50;
  color: #ecf0f1;
}

.heading {
  color: #3498db;
}
</style>

6. CSS Modules与JavaScript交互

6.1 在JS中访问类名

<template>
  <div ref="element" :class="styles.container">
    <button @click="logClassName">Log Class Name</button>
  </div>
</template>

<script>
export default {
  methods: {
    logClassName() {
      // 访问生成的类名
      console.log('Generated class name:', this.$style.container)
      // 输出类似: "ComponentName_container_1a2b3c"
    }
  }
}
</script>

<style module>
.container {
  padding: 20px;
  background-color: #f5f5f5;
}
</style>

6.2 动态生成样式

<template>
  <div :style="dynamicStyles">
    Dynamic Style Example
  </div>
</template>

<script>
export default {
  data() {
    return {
      fontSize: 20,
      color: '#42b983'
    }
  },
  computed: {
    dynamicStyles() {
      return {
        fontSize: `${this.fontSize}px`,
        color: this.color,
        padding: '10px',
        border: `1px solid ${this.color}`
      }
    }
  }
}
</script>

7. CSS Modules的实现原理

7.1 编译过程

1. 解析CSS文件：提取所有类名
2. 生成唯一标识符：为每个类名生成唯一的哈希值
3. 创建映射表：建立原始类名到生成类名的映射
4. 转换CSS：将原始类名替换为生成的唯一类名
5. 导出映射表：将映射表导出给JavaScript使用

7.2 编译前后对比

编译前CSS：

.container {
  padding: 20px;
}

.title {
  color: red;
}

编译后CSS：

.MyComponent_container_1a2b3c {
  padding: 20px;
}

.MyComponent_title_4d5e6f {
  color: red;
}

导出的映射表：

{
  container: "MyComponent_container_1a2b3c",
  title: "MyComponent_title_4d5e6f"
}

8. CSS Modules与其他样式方案对比

8.1 CSS Modules vs scoped CSS

8.2 CSS Modules vs CSS-in-JS

9. 最佳实践

9.1 命名规范

• 使用驼峰命名：便于在JS中访问（如styles.myClass）
• 语义化命名：类名应反映元素的功能，而非样式
• 避免过度嵌套：保持CSS结构扁平，提高性能
• 使用BEM思想：结合Block-Element-Modifier思想组织类名

9.2 组织方式

• 组件级样式：每个组件对应一个CSS Modules文件
• 共享样式：创建共享的CSS Modules文件，存放通用样式
• 主题样式：使用CSS变量结合CSS Modules实现主题切换
• 工具类：创建工具类CSS Modules，提供通用样式功能

9.3 性能优化

• 避免过度使用动态类名：动态类名会增加运行时计算
• 合理使用预处理器：预处理器的嵌套过深会生成复杂选择器
• 提取公共样式：将重复使用的样式提取到共享模块中
• 使用PurgeCSS：移除未使用的CSS，减少文件体积

9.4 与TypeScript结合

为CSS Modules添加类型支持，提高开发体验和代码质量：

1. 安装类型声明：

   npm install --save-dev typescript-plugin-css-modules

2. 配置tsconfig.json：

   {
     "compilerOptions": {
       "plugins": [
         {
           "name": "typescript-plugin-css-modules"
         }
       ]
     }
   }

3. 使用类型支持：

   <template>
     <div :class="styles.container">
       <!-- TypeScript会检查styles对象的属性 -->
     </div>
   </template>

10. 实际应用场景

10.1 组件库开发

<!-- Button组件 -->
<template>
  <button 
    :class="[styles.button, styles[`variant-${variant}`], styles[`size-${size}`]]"
    :disabled="disabled"
    @click="$emit('click')"
  >
    <slot></slot>
  </button>
</template>

<script>
export default {
  props: {
    variant: {
      type: String,
      default: 'default',
      validator: (value) => ['default', 'primary', 'secondary', 'danger'].includes(value)
    },
    size: {
      type: String,
      default: 'medium',
      validator: (value) => ['small', 'medium', 'large'].includes(value)
    },
    disabled: {
      type: Boolean,
      default: false
    }
  },
  emits: ['click']
}
</script>

<style module>
.button {
  border: none;
  border-radius: 4px;
  cursor: pointer;
  font-weight: 500;
  transition: all 0.2s ease;
  
  &:disabled {
    opacity: 0.6;
    cursor: not-allowed;
  }
}

/* 变体样式 */
.variant-default {
  background-color: #f0f0f0;
  color: #333;
}

.variant-primary {
  background-color: #42b983;
  color: white;
}

.variant-secondary {
  background-color: #35495e;
  color: white;
}

.variant-danger {
  background-color: #f44336;
  color: white;
}

/* 尺寸样式 */
.size-small {
  padding: 4px 8px;
  font-size: 12px;
}

.size-medium {
  padding: 8px 16px;
  font-size: 14px;
}

.size-large {
  padding: 12px 24px;
  font-size: 16px;
}
</style>

10.2 主题切换

<template>
  <div :class="[styles.app, theme === 'dark' && styles.dark]">
    <h1 :class="styles.title">Theme Switcher</h1>
    <button @click="toggleTheme" :class="styles.themeButton">
      Switch to {{ theme === 'light' ? 'Dark' : 'Light' }} Theme
    </button>
  </div>
</template>

<script>
export default {
  data() {
    return {
      theme: 'light'
    }
  },
  methods: {
    toggleTheme() {
      this.theme = this.theme === 'light' ? 'dark' : 'light'
      localStorage.setItem('theme', this.theme)
    }
  },
  mounted() {
    const savedTheme = localStorage.getItem('theme')
    if (savedTheme) {
      this.theme = savedTheme
    }
  }
}
</script>

<style module>
.app {
  min-height: 100vh;
  padding: 20px;
  transition: all 0.3s ease;
}

.title {
  font-size: 28px;
  margin-bottom: 20px;
}

.themeButton {
  padding: 10px 20px;
  border: none;
  border-radius: 4px;
  cursor: pointer;
  font-size: 16px;
}

/* 亮色主题 */
.app {
  background-color: #ffffff;
  color: #333333;
}

.title {
  color: #42b983;
}

.themeButton {
  background-color: #42b983;
  color: white;
}

/* 暗色主题 */
.dark {
  background-color: #1a1a1a;
  color: #ffffff;
}

.dark .title {
  color: #3498db;
}

.dark .themeButton {
  background-color: #3498db;
  color: white;
}
</style>

11. 常见问题与解决方案

11.1 类名不生效

问题：CSS Modules类名没有正确应用到元素上

解决方案：

• 检查是否正确使用了:class绑定
• 确认是否添加了module属性
• 检查类名拼写是否正确
• 查看浏览器开发者工具，确认生成的类名是否正确

11.2 无法访问$style

问题：在JS中无法访问this.$style

解决方案：

• 确认使用了module属性
• 对于组合式API，使用useCssModule()获取样式对象
• 检查是否使用了自定义模块名

11.3 组合式API中使用CSS Modules

<template>
  <div :class="styles.container">
    <h1 :class="styles.title">Composition API</h1>
  </div>
</template>

<script setup>
import { useCssModule } from 'vue'

// 获取默认样式模块
const styles = useCssModule()

// 获取自定义名称的样式模块
// const myStyles = useCssModule('myStyles')
</script>

<style module>
.container {
  padding: 20px;
  background-color: #f5f5f5;
}

.title {
  color: #42b983;
  font-size: 24px;
}
</style>

12. 总结

CSS Modules是Vue中实现样式隔离的强大工具，具有以下优势：

1. 彻底的样式隔离：避免了全局命名冲突
2. 清晰的依赖关系：明确知道样式的来源
3. 良好的开发体验：接近原生CSS的写法
4. 强大的JS交互能力：可以在JS中访问和操作样式
5. 优秀的性能：编译时处理，运行时开销小
6. 完善的工具支持：支持所有主流构建工具和预处理器

CSS Modules是Vue项目中常用的样式解决方案之一，特别是在大型应用和组件库开发中表现出色。

13. 练习

1. 创建一个使用CSS Modules的Button组件，支持不同的变体和尺寸
2. 实现一个主题切换功能，使用CSS Modules管理不同主题的样式
3. 尝试在组合式API中使用CSS Modules
4. 创建一个包含多个样式模块的组件
5. 结合SCSS和CSS Modules，实现一个复杂的卡片组件

14. 进一步阅读

• CSS Modules官方文档
• Vue CSS Modules文档
• TypeScript与CSS Modules
• CSS Modules最佳实践