11. Vite 配置文件中 CSS 配置(Modules 模块化篇)
由于课程讲的是 vite2 版本,所以我阅读了 vite6 中的文档,下面将结合 css.modules 的接口进行讲解
CSSModulesOptions 接口文档
interface CSSModulesOptions {
/**
* 用户可以自定义一个回调函数,来处理生成的 JSON 文件。
* 该回调函数接受三个参数:
* - cssFileName: 当前处理的 CSS 文件名
* - json: 生成的类名与哈希值的映射对象
* - outputFileName: 生成的 CSS 文件的输出路径
*/
getJSON?: (
cssFileName: string,
json: Record<string, string>,
outputFileName: string,
) => void;
/**
* 定义 CSS Modules 的作用域行为
* - 'local':启用 CSS Modules,生成的类名会进行哈希化并作用于当前模块。
* - 'global':禁用 CSS Modules,所有类名都将是全局的,不会进行哈希化。
*/
scopeBehaviour?: 'global' | 'local';
/**
* 定义哪些 CSS 文件路径需要被视为全局样式,不应用 CSS Modules。
* 可以传入一个正则表达式数组,匹配路径中符合规则的文件。
*/
globalModulePaths?: RegExp[];
/**
* 如果为 `true`,会导出所有的全局类名,即使在使用 CSS Modules 时,也会把它们暴露为全局类。
* 默认为 `false`,不会导出全局类名。
*/
exportGlobals?: boolean;
/**
* 定义生成的 CSS 类名的格式,可以是一个字符串模板,也可以是一个函数。
* 字符串模板的格式通常为 `[name]__[local]___[hash:base64:5]`,其中:
* - `[name]` 是文件名(不含扩展名)
* - `[local]` 是原始的 CSS 类名
* - `[hash:base64:5]` 是文件内容的哈希值,长度为 5
*
* 如果传入函数,它接受三个参数,允许你根据文件名、类名及 CSS 内容来生成类名。
*/
generateScopedName?:
| string
| ((name: string, filename: string, css: string) => string);
/**
* 为生成的类名哈希值添加一个前缀,用于避免不同项目之间的哈希冲突。
*/
hashPrefix?: string;
/**
* 控制类名在 JS 对象中的转换方式:
* - 'camelCase':将 CSS 类名转为 camelCase 格式(例如 `my-class` 转为 `myClass`)
* - 'camelCaseOnly':与 'camelCase' 类似,但如果类名原本就是 camelCase 格式,则保持不变。
* - 'dashes':将 CSS 类名保持为短横线分隔格式(例如 `my-class` 转为 `my-class`)
* - 'dashesOnly':与 'dashes' 类似,但如果类名已经是短横线格式,则保持不变。
*
* 还可以传入一个函数,允许你自定义转换规则,函数接收三个参数:
* - `originalClassName`: 原始 CSS 类名
* - `generatedClassName`: 生成的类名
* - `inputFile`: 当前处理的文件路径
*/
localsConvention?:
| 'camelCase'
| 'camelCaseOnly'
| 'dashes'
| 'dashesOnly'
| (
originalClassName: string,
generatedClassName: string,
inputFile: string,
) => string;
}
完整配置示例:
export default {
css: {
modules: {
getJSON(cssFileName, json, outputFileName) {
console.log('Generated CSS JSON:', json)
},
scopeBehaviour: 'local', // 使用 CSS Modules
globalModulePaths: [/\.global\.css$/], // 匹配全局 CSS 文件
exportGlobals: true, // 导出全局类名
generateScopedName: '[name]__[local]__[hash:base64:5]', // 类名格式
hashPrefix: 'viteApp_', // 哈希前缀
localsConvention: 'camelCase' // 驼峰命名类名
}
}
}
vite6 中 css modules 最新配置共享选项
11.1.1. 总结
Vite 提供了灵活的 CSS 模块化配置选项,可以帮助开发者在处理 CSS 时避免样式冲突,并根据项目的需求定制类名生成规则。同时,Vite 还支持对外部库(如 node_modules
)的样式进行处理,确保项目中的样式兼容性和可维护性。