前端开发工具【免费下载链接】lightningcssAn extremely fast CSS parser, transformer, bundler, and minifier written in Rust.项目地址https://gitcode.com/gh_mirrors/li/lightningcss点击查看免费下载CSS 默认是全局命名空间不同文件里同名类、id、自定义属性或keyframes会互相覆盖这在大型项目中极易引发样式冲突。Lightning CSS 原生支持 CSS modules 为骨架结合 src/css_modules.rs 等源码深入讲解启用方式、exports数据结构、composes组合、:global例外、局部 CSS 变量、自定义命名 pattern、pure 模式以及 feature scoping 关闭等全部能力。为什么需要 CSS modules全局标识符的冲突问题在默认情况下CSS 中的所有标识符都是全局的。如果两个文件定义了相同的类名、id、自定义属性或keyframes动画名它们就会互相冲突、互相覆盖最终样式取决于加载顺序。CSS modules 的解决思路是把每个文件中定义的类名与标识符视为唯一——每个类名或标识符都会被重命名加入一个唯一的 hash同时导出一份映射表给 JavaScript以便在模板或脚本中引用这些编译后的类名。在 Lightning CSS 的实现中这一机制由 src/css_modules.rs 支撑文件顶部的模块注释明确写道——CSS modules 是“局部作用域 CSS 文件中名字的一种方式”涵盖类名、id、keyframe 动画名以及任何使用CustomIdent类型的位置。启用 CSS modules 后打印样式表时会为声明的名字追加 hash并同步更新对这些名字的引用最终返回原名到编译名的映射。启用 CSS modulesAPI 选项与 CLI 标志启用方式有两种使用 JS API 时传入cssModules选项使用 CLI 时加--css-modules标志。import {transform} from lightningcss; let {code, map, exports} transform({ // ... cssModules: true, code: Buffer.from( .logo { background: skyblue; } ), });在 TypeScript 定义 node/index.d.ts 中cssModules的类型是boolean | CSSModulesConfig——既可以传true直接启用也可以传一个配置对象来细化行为见下文各节。cssModules为true时内部会使用 src/css_modules.rs 中Config::default()其默认值为pattern[hash]_[local]dashed_identsfalseanimation、grid、container、custom_identstruepurefalseCLI 侧的处理在 src/main.rs当传入--css-modules时会读取--css-modules-pattern解析 pattern读取--css-modules-dashed-idents开启局部变量其余字段走默认值。理解exports对象原名字到编译名的映射调用transform后除了编译后的代码和 source map还会额外返回一个exports对象。exports中的每个属性把源码 CSS 中的原始名字映射到编译后已 hash 的名字。你可以在 JavaScript 或模板文件中利用这份映射来引用编译后的类名与标识符。针对上面示例exports对象大致如下{ logo: { name: 8h19c6_logo, isReferenced: false, composes: [] } }这个结构对应 Rust 侧的 CssModuleExportname编译后的局部名字composes该导出组合compose的其他名字列表is_referenced该导出在当前文件中是否被引用。CssModuleExport在开启serde/nodejsfeature 时会序列化为 camelCase见 src/css_modules.rs 的serde(rename_all camelCase)因此 JS 侧字段就是name、isReferenced、composes。TypeScript 侧的类型定义在 node/index.d.ts。值得注意的细节默认 pattern[hash]_[local]下hash 由相对项目根目录的文件路径计算得出见 src/css_modules.rs 的注释“Make paths relative to project root so hashes are stable”这样 hash 在不同机器上保持一致便于缓存与长期复用。类组合composes实现样式混入CSS modules 中的样式规则可以通过composes属性引用其他类被引用的类会在组合类被使用的同时一并生效这实际上提供了一种“样式混入”style mixins机制。.bg-indigo { background: indigo; } .indigo-white { composes: bg-indigo; color: white; }上例中只要indigo-white类被应用bg-indigo类也会一并应用。这在 Lightning CSS 返回的exports对象中体现如下{ bg-indigo: { name: 8h19c6_bg-indigo, isReferenced: true, composes: [] }, indigo-white: { name: 8h19c6_indigo-white, isReferenced: false, composes: [{ type: local, name: 8h19c6_bg-indigo }] } }composes引用有三种类型对应 Rust 侧的 CssModuleReference 枚举local本文件内的局部引用name是编译后的名字global引用全局不 hash名字dependency引用其他文件导出的名字带specifier指明依赖文件。多个类可以一次性组合用空格分隔.logo { composes: bg-indigo padding-large; }在解析实现 src/properties/css_modules.rs 中composes的值被解析为一系列CustomIdent遇到from关键字停止然后可选地跟随fromSpecifier。组合的登记逻辑在 src/css_modules.rs 的handle_composes它要求composes只能出现在单一简单类选择器中否则返回InvalidComposesSelector错误对于本地引用编译后的名字会直接写入导出。跨文件依赖composes ... fromcomposes还可以通过from关键字引用另一个 CSS 文件中定义的类名.logo { composes: bg-indigo from ./colors.module.css; }这会输出带有依赖信息的 exports 对象{ logo: { name: 8h19c6_logo, isReferenced: false, composes: [{ type: dependency, name: bg-indigo, specifier: ./colors.module.css }] } }这里有一个重要的分工使用transformAPI 时解析这个依赖并应用目标类名是调用方你的打包器或应用代码的责任而使用bundleAPI 时依赖的解析与内联会自动完成。对应源码中Specifier::SourceIndex(u32)这一变体正是“捆绑过程中用于标记来源索引”的见 src/properties/css_modules.rsbundler 会据此自动展开跨文件组合见 src/bundler.rs 对 css modules 依赖的收集与内联。全局组合composes ... from global没有被 hash 的全局类也可以被组合使用global关键字.search { composes: search-widget from global; }对应Specifier::Global变体src/properties/css_modules.rs生成的引用类型为global。全局例外:global伪类在 CSS module 中默认所有类选择器和 id 选择器都是局部的。你可以用:global伪类为单个选择器退出局部作用域.foo :global(.bar) { color: red; } .foo .bar { color: green; }编译结果为.EgL3uq_foo .bar { color: red; } .EgL3uq_foo .EgL3uq_bar { color: #ff0; }可以看到:global(.bar)中的.bar保持原样而.foo被 hash第二行中两个类都被 hash。#ff0是green的 minify 压缩结果说明 CSS modules 与压缩可以同时工作。局部 CSS 变量dashedIdents选项默认情况下类名、id 选择器、keyframes、counter-style的名字以及 CSS grid 的线名和区域名都会被作用域化到定义它们的模块内。CSS 变量以及其他dashed-ident名字的作用域化则可以通过dashedIdents选项开启JS APICLI 对应--css-modules-dashed-idents标志。let {code, map, exports} transform({ // ... cssModules: { dashedIdents: true, }, });开启后CSS 变量会被重命名避免与其他文件中的同名变量冲突。引用变量仍使用标准var()语法Lightning CSS 会自动把它更新为局部作用域的变量名:root { --accent-color: hotpink; } .button { background: var(--accent-color); }变为:root { --EgL3uq_accent-color: hotpink; } .EgL3uq_button { background: var(--EgL3uq_accent-color); }注意 dashed ident 的重命名同样遵循 pattern前缀会带上--这一点可以从 src/css_modules.rs 的add_dashed看到它把 pattern 应用到去掉--前缀的名字上再补回--。你还可以用from关键字引用其他文件中定义的变量.button { background: var(--accent-color from ./vars.module.css); }以及用from global引用全局变量.button { color: var(--color from global); }同一套语法也适用于其他使用dashed-ident语法的 CSS 值。例如font-palette-values规则和font-palette属性就用dashed-ident来定义与引用自定义字体配色它们会像 CSS 变量一样被作用域化与引用改写。在 Rust 配置中对应的开关是Config.dashed_idents见 src/css_modules.rs。跨文件 dashed ident 引用在 src/css_modules.rs 的reference_dashed中实现对于from file的引用会生成一个基于“源 hash 变量名 specifier”的占位名字并登记到references映射中由 bundler 或调用方解析。自定义命名 pattern默认情况下Lightning CSS 会把文件名的 hash 前缀到每个类名和标识符前。你可以用pattern配置JS API或--css-modules-patternCLI自定义这个命名规则。pattern 是一个包含占位符的字符串Lightning CSS 会按占位符填充从而支持自定义前缀或调整作用域类名的命名约定let {code, map, exports} transform({ // ... cssModules: { pattern: my-company-[name]-[hash]-[local], }, });当前支持的占位符如下占位符含义[name]文件的基础名不含扩展名[hash]完整文件路径的 hash[content-hash]文件内容的 hash[local]原始的类名或标识符这些占位符对应 Rust 侧 Segment 枚举 的Name、Hash、ContentHash、Local四个变体外加字面量Literal。pattern 的解析在 Pattern::parse未知占位符会报UnknownPlaceholder错误未闭合的方括号会报UnclosedBrackets错误。填充逻辑在 Pattern::write其中[name]会取文件 stem并把其中的.替换为-my.module.css的 stem 会变成my-module。需要留意的是[content-hash]只会在打包bundle场景中生效如 src/bundler.rs 所示只有当 pattern 包含 content-hash 时bundler 才会为每个源文件计算内容 hash 并填充。CSS Grid 与 pattern 的注意事项注意CSS grid 的线名可能是歧义的因为浏览器会自动为每个 grid template area 生成以-start和-end结尾的线名。使用 CSS grid 时你的pattern配置必须以[local]占位符结尾这些自动生成的线名才能被正确引用。let { code, map, exports } transform({ // ... cssModules: { // ❌ [local] 必须在末尾否则 // 自动生成的 grid 线名无法工作 pattern: [local]-[hash] // ✅ 应该这样写 pattern: [hash]-[local] } });.grid { grid-template-areas: nav main; } .nav { grid-column-start: nav-start; }Pure 模式和 webpackcss-loader的pure选项一样Lightning CSS 也有pure选项它强制每条规则至少使用一个 id 或类选择器let {code, map, exports} transform({ // ... cssModules: { pure: true, }, });启用后Lightning CSS 会对没有至少一个 id 或类选择器的 CSS 规则比如div直接抛错。这很有用因为像div这样的选择器不会被作用域化会影响页面上的所有元素。对应配置字段是 Config.pure默认关闭false见 src/css_modules.rs。关闭特性作用域animation / grid / customIdents / containergrid、动画和自定义标识符的作用域化可以单独关闭。默认情况下这些全部是开启的let {code, map, exports} transform({ // ... cssModules: { animation: true, grid: true, customIdents: true, }, });此外TypeScript 定义中还包含container选项用于控制container名字的 hash见 node/index.d.tsRust 侧对应的默认配置同样全部为 truesrc/css_modules.rs 中的animation、grid、container、custom_idents均默认为 true。若某个选项设为false对应的名字将保持原样、不做 hash。当前未支持的特性Lightning CSS 目前并未实现其他 CSS modules 实现中的所有特性其中一些未来可能会被加入非函数形式的:local和:global伪类语法即:local .foo这种老式写法value规则——它已被标准 CSS 变量取代:import与:export这两种 ICSS 规则。需要时可以分别通过标准 CSS 变量、var()引用以及导出映射exports来替代上述能力。从 JS 到 Rust 的完整调用链小结把上文串联起来一次 CSS modules 转换的完整链路是JS 侧transform({cssModules: true | config})把配置映射到 Rust 的css_modules::Configsrc/css_modules.rs解析样式表时Composes属性被解析为名字列表 可选的Specifiersrc/properties/css_modules.rs打印阶段CssModule依据 pattern 计算每个名字的编译名登记CssModuleExport并更新var()、composes、grid、keyframes 等引用src/css_modules.rs结果以 camelCase 结构序列化回 JS 的exports对象node/index.d.ts使用bundleAPI 时跨文件的composes from与var(--x from ...)依赖会被 bundler 自动解析与内联src/bundler.rs。若你想在 Parcel 中全局启用 CSS modules而不只针对.module.css文件可以在package.json中配置parcel/transformer-css的cssModules选项或传入一个选项对象参见 website/pages/docs.md。CLI 下则使用--css-modules、--css-modules-pattern、--css-modules-dashed-idents三个标志组合src/main.rs。赞分享前端开发工具【免费下载链接】lightningcssAn extremely fast CSS parser, transformer, bundler, and minifier written in Rust.项目地址https://gitcode.com/gh_mirrors/li/lightningcss点击查看免费下载相关推荐VPS安全维护Instatic服务器定期检查完整指南VPS安全维护Instatic服务器定期检查完整指南 Instatic作为现代化的自托管视觉CMS在VPS环境中部署后需要通过系统化的定期检查来保障服务器安CMS后端前端如何用25美元制作开源AI智能眼镜完整DIY指南如何用25美元制作开源AI智能眼镜完整DIY指南 你是否曾梦想拥有一副智能眼镜却又被数千元的价格标签劝退现在通过OpenGlass开源项目你可以用不到人工智能AI 应用智能硬件本地部署可穿戴AI AgentGatsby 中使用 CSS Modules组件级作用域样式实战指南Gatsby 中使用 CSS Modules组件级作用域样式实战指南 本指南以 docs/docs/how to/styling/css modules.md前端静态站点Web框架上一篇PDF补丁丁一站式PDF处理解决方案轻松解决文档编辑难题下一篇ASP.NET Core中的Blazor模板Razor组件模板使用指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考