Ember 应用集成 CSS Blocks 完整指南:@css-blocks/ember-app 插件的安装、配置与测试实践
Ember 应用集成 CSS Blocks 完整指南:@css-blocks/ember-app 插件的安装、配置与测试实践
@css-blocks/ember-app 是 CSS Blocks 在 Ember 生态中的"应用侧" ember-cli addon,负责把应用(及 addon、engine)中通过 CSS Blocks 撰写的样式编译、拼接、优化,并生成模板运行所需的运行时数据。读完本文,你将掌握如何接入该 addon、理解全部配置选项的语义与底层实现、以及如何在类名被随机化后依然写出健壮的测试。
addon 的定位:应用侧构建管线的收口
CSS Blocks 在 Ember 中的构建被拆成两个 addon,各自职责清晰:
@css-blocks/ember:面向"撰写 CSS Blocks 的一方",负责在模板编译期分析模板与样式、将中间产物(compiled CSS 与 Definition 文件)输出到编译树中,适用于应用、addon 与 engine;@css-blocks/ember-app(本文主角):面向"最终消费 CSS 的一方",即 Ember 应用本身。它把所有 CSS Blocks 内容汇集起来、拼成最终产物、交给 OptiCSS 优化,并生成一份 JSON 运行时数据(runtime data)与对应的 helper,供重写后的模板在运行时解析出应该给元素加上哪些类名。
任何"撰写"了 CSS Blocks 文件的 addon 或 engine,其所在的应用都必须把
@css-blocks/ember-app作为依赖,否则不会产出任何 CSS 输出。这也是package.json中ember-addon.after声明为<a href="https://link.gitcode.com/i/3b8f9de1db5074716095ea2cd743ecfe" target="_blank">"@css-blocks/ember"]的原因——它必须在@css-blocks/ember完成模板侧编译之后再执行。参见 [packages/@css-blocks/ember-app/package.json。
一个容易忽略的细节是:CSS Blocks 的编译实际发生在模板树而非样式树中。正如 addon 入口 顶部注释所说,CSS Blocks 需要同时理解模板与样式才能完成模板重写,因此 JS/模板树的处理先于 CSS 树,preprocessTree 中特意对 "CSS 树先于 JS 树运行" 的情况抛出明确错误("[css-blocks/ember-app] The CSS tree ran before the JS tree...")。
快速开始:三步接入
按照 官方 README 的 Basic Usage,接入只需要三步:
- 在应用中将
@css-blocks/ember-app添加为依赖; - 如果应用自身也在用 CSS Blocks 撰写样式,同时把
@css-blocks/ember添加为依赖; - 运行
ember build。
构建产物落位规则:
- 若应用存在
app/styles/app.css,CSS Blocks 的编译输出会被自动追加到该文件末尾(由 postprocess 阶段的 broccoli-concat 完成); - 若应用因预处理等原因使用了其他样式文件名,则构建期间会在应用样式目录生成一个名为
app/styles/css-blocks.css的文件,供你的预处理器 import,或与其他文件拼接成最终的 CSS。
另外,如果应用使用 engine,每个用到 @css-blocks/ember 的 engine 都必须把 css-blocks service 作为依赖加入(该 service 位于 runtime/app/services,由 addon 的 treePaths.app 注入,见 runtime 目录)。
开发构建与生产构建的输出差异是刻意设计的:
- 开发构建:产出带开发者友好 BEM 类名的 CSS,方便你理解应用结构;
- 生产构建:产出经过拼接(concatenated)、优化(optimized)、压缩(minified)的 CSS 工件。
从源码看,这一差异由 ember-utils 的 getConfig 落实:optimization.enabled 在未显式设置时默认取 isProduction,即生产构建才默认开启优化;同时 parserOpts.outputMode 被强制设置为 OutputMode.BEM_UNIQUE,保证类名唯一性。
配置选项(Options)详解
所有选项都通过应用 ember-cli-build.js 中的 css-blocks 属性传入。下表汇总了 README 与 ember-utils 的接口定义 中的全部参数:
| 选项 | 类型 | 默认值 | 作用 |
|---|---|---|---|
output |
string |
"css-blocks.css" |
修改 CSS Blocks 样式写入 app/styles 目录时的文件名;一旦设置,不再自动与 app/styles/app.css 拼接 |
aliases |
object |
{} |
导入别名映射,值为指向包含 CSS Block 文件目录的绝对路径 |
analysisOpts |
object |
{} |
模板分析选项,一般无需设置 |
parserOpts |
object |
自动加载 | 传给 CSS Blocks 解析器与编译器的选项;未设置时自动从 css-blocks.config.js 读取 |
optimization |
object |
{ enabled: isProduction } |
传给 OptiCSS 优化器的选项,可选择性开关具体优化,或将 enable 设为 false 整体禁用 |
broccoliConcat |
object | false |
{} |
控制 broccoli-concat 行为;设为 false 则不执行拼接,需自行把编译内容并入最终 CSS |
appClasses |
string[] |
[] |
应用 CSS 中使用、可能与优化器冲突的类名清单;短类名(约 5 字符)应加入此列表 |
output:定制输出文件名
output 决定编译 CSS 的落盘文件名。底层实现见 filepaths.ts:预处理阶段路径为 app/styles/${output}(默认 app/styles/css-blocks.css),postprocess 阶段则出现在 assets/${output}。注意设置该选项后,自动拼接行为会被跳过,你需要自行在样式管线中包含该文件。
aliases:目录级导入别名
aliases 的键作为导入别名,值必须是绝对路径。例如:
// ember-cli-build.js
const path = require('path');
module.exports = function(defaults) {
let app = new EmberApp(defaults, {
'css-blocks': {
aliases: {
myblocks: path.resolve(__dirname, '../blocks')
}
}
});
return app.toTree();
};
配置后,@block foo from 'myblocks/header.block.css'; 即可导入 ../blocks 目录下的 header.block.css。在 ember-utils 的 getConfig 中,aliases 会被注入到默认的 NodeJsImporter:options.parserOpts.importer = options.parserOpts.importer || new NodeJsImporter(options.aliases)——即只有在没有自定义 importer 时才使用别名 importer。
parserOpts 与 css-blocks.config.js
parserOpts 是传给 CSS Blocks 解析器/编译器的选项。若未显式提供,构建时会通过 config.searchSync(root) 自动从 css-blocks.config.js 加载(同样由 ember-utils getConfig 完成)。使用配置文件的好处是:其他工具(如 @css-blocks/cli 命令行)可以加载与 Ember 应用完全一致的选项。
getConfig 还会做几件关键的兜底与校验(options.ts):
parserOpts.rootDir缺省时设为应用根目录(root),这是解析相对导入所必需的;output若非字符串会抛出明确错误:Invalid css-blocks options in 'ember-cli-build.js': Output must be a string.;optimization.enabled未设置时取isProduction。
optimization:OptiCSS 优化器配置
optimization 直接透传给 OptiCSS 的 Optimizer。在 broccoli-plugin.ts 的 CSSBlocksApplicationPlugin.build() 中,优化器会逐一装载应用及其传递依赖的 blocks 分析结果(optimizer.addAnalysis(...))与编译后的样式源(optimizer.addSource(...)),最终调用 optimizer.optimize(cssFileName) 产出优化 CSS,并额外写出 .optimization.log 优化日志与 app/styles/css-blocks-stylelist.json 类名清单。
broccoliConcat:拼接行为控制
postprocess 阶段由 addon 入口 postprocessTree 使用 broccoli-concat 将 assets/css-blocks.css 与 assets/<modulePrefix>.css(即应用自身样式)拼接为最终文件,同时开启 sourcemap(mapCommentType: "block"、extensions: <a href="https://link.gitcode.com/i/b51215383586dcb84dd902ed6dbf0a52" target="_blank">"css"])。如果 broccoliConcat 设为 false,postprocess 会直接跳过拼接,你必须增加额外处理把 CSS Blocks 编译内容并入最终 CSS 工件。默认拼接顺序在 [buildDefaultBroccoliConcatOptions 中可见:inputFiles: [blocksCssPath, appCssPath],即 CSS Blocks 内容在前、应用样式在后。
appClasses:与应用类名冲突的规避
优化器会重写类名,若应用 CSS 中存在短类名(约 5 字符),可能与优化器生成的类名撞车。appClasses 是 optimization.rewriteIdents.omitIdents.class<a href="https://link.gitcode.com/i/de22f789d5eab32ec7e989b36df14075" target="_blank">] 的便捷别名,底层实现在 [broccoli-plugin.ts 的 reserveClassnames:它会解析 rewriteIdents(布尔或对象形态),把 appClasses 并入 omitIdents.class 列表,确保优化器生成类名时避开这些名字。它仅在优化开启时生效。
值得注意的是,即使配置了 appClasses,postprocess 阶段仍会执行一次冲突检测:CSSBlocksStylesPostprocessorPlugin 会扫描应用 CSS(排除 CSS Blocks 自身产物)中的所有 .class 选择器,与优化器生成的类名比对,若发现冲突会直接抛错并提示你将短类名加入 css-blocks.appClasses。检测日志(含出错 CSS 的解析异常)会写入 assets/app-classes.log 供排查。
构建管线源码级拆解
ember build 时 addon 经历两条树管线,均实现在 src/index.ts:
JS/模板树(preprocessTree, type === "js"):针对应用(env.isApp)创建 CSSBlocksApplicationPlugin 实例,输入为应用 addon 树、JS 树以及(若有 lazy engine)收集到的 lazy-tree-output。该插件在 broccoli-plugin.ts 中承担核心工作:
- 扫描输入树中所有
*.block-analysis.json与*.compiledblock.css产物(由@css-blocks/ember在模板编译期生成); - 用
EmberAnalyzer反序列化分析结果,收集全部使用的 blocks; - 对每个 block 编译/复用 CSS,交给 OptiCSS
Optimizer做全局优化; - 写出优化后的 CSS(含 base64 内嵌 sourcemap)、优化日志、类名清单;
- 用
RuntimeDataGenerator生成运行时数据-css-blocks-data.js,开发构建下还会额外生成-css-blocks-test-support-data.js(见 RuntimeDataGenerator.ts 与 TestSupportDataGenerator.ts)。
CSS 树(preprocessTree, type === "css"):CSSBlocksStylesPreprocessorPlugin 把模板树中产出的 CSS Blocks 内容写入样式树的 app/styles/css-blocks.css(路径随 output 变化),并把 css-blocks-stylelist.json 转发给后续管线。
postprocess(type === "css"):若 broccoliConcat 未禁用,先运行冲突检测(优化开启时),再用 broccoli-concat 拼接产物,最后把原 css-blocks.css 从输出树中剔除(见 index.ts 的 mergedTree exclude 逻辑),避免重复出现在最终 CSS 中。
测试支持:setupCSSBlocksTest 的正确姿势
为什么需要它
接入该 addon 后,所有 CSS 类名与你在 block 文件中写下的完全不同——它们是优化器重新生成的结果,且跨构建、跨机器都可能变化;优化后元素上的类名数量也可能与源码中大相径庭。这是刻意设计:逼你不在测试中硬编码任何类名选择器,从而保证测试跨环境稳健。
测试服务的工作原理
addon 在开发构建下会生成 -css-blocks-test-support-data.js,其中 testSupportData 把"用户可读的 block 文件路径 + block 导出名"映射到该 block 的运行时 guid(见 TestSupportData.ts 中的注释示例)。setupCSSBlocksTest() 在 beforeEach 中把应用默认的 css-blocks service 替换为 CSSBlocksTestService(css-blocks-test-support.ts),后者通过 guid 反向解析出人类可读的代理类名(<guid><styleName>),于是你可以用 element.classList.contains() 断言样式是否存在。
注意:testSupportData 只暴露属于应用命名空间(应用、in-repo addon、in-repo engine)的 blocks,因为这些才代表需要测试的样式接口。运行时的类名解析链路(直接样式 → 隐含样式 → 优化后样式)实现在 css-blocks.ts、StyleEvaluator.ts 与 StyleResolver.ts,数据格式定义见 AggregateRewriteData.ts。
测试接入步骤
- 在集成或验收测试中调用
setupCSSBlocksTest(),且必须在setupTest | setupRenderingTest | setupApplicationTest之后调用(否则会抛出 "setupCSSBlocksTest must be called after setupTest|setupRenderingTest|setupApplicationTest")。它同时兼容ember-qunit与ember-mocha; - 该函数挂在应用命名空间的 service 上,需按如下方式导入:
import { setupCSSBlocksTest } from '<appName>/services/css-blocks-test-support'; - 之后通过
this.cssBlocks访问测试 service,其核心 API 是this.cssBlocks.getBlock(<pathToBlock>, <blockName>):pathToBlock以所属应用名、in-repo addon 名或 engine 名开头;blockName可选,缺省返回该 block 文件的默认 block;- 返回的运行时 block 可用
.style(<styleName>)查询样式名,再配合element.classList.contains()断言。
完整示例
import { setupCSSBlocksTest } from 'my-very-fine-app/services/css-blocks-test-support';
module('Acceptance | css blocks test', function (hooks) {
setupApplicationTest(hooks);
setupCSSBlocksTest(hooks);
test('visiting /', async function (assert) {
await visit('/');
let defaultBlock = this.cssBlocks.getBlock("my-very-fine-app/styles/components/application", "default");
let element = find('[data-test-large-hello]');
assert.ok(element.classList.contains(defaultBlock.style(':scope[size="large]')));
});
});
若传入的 block 文件或样式名不存在,测试 service 会给出包含可用选项的明确报错("No block file named ..." / "No style named ..."),便于快速定位。
常见陷阱(Common Gotchas)
截至本文,README 的 Gotchas 章节 内容为空("Nothing yet..."),但结合源码可以归纳出几个实践中容易踩坑的点:
- 忘记添加
@css-blocks/ember:应用若自己撰写 CSS Blocks 却只装了本 addon,将不会生成任何 CSS 输出(addon 依赖模板树中的中间产物); - 忘记给 engine 加
css-blocksservice 依赖:使用 engine 时必须逐引擎声明,否则该引擎的样式不会正常解析; - 应用 CSS 短类名冲突:若构建报出 "Your application CSS contains classes that are also generated by the CSS optimizer" 错误,按提示把相关短类名加入
css-blocks.appClasses即可; - 自定义
output后丢失自动拼接:设置output意味着你需要自行把生成的 CSS 文件纳入最终样式产物; - 禁用
broccoliConcat后产物缺失:broccoliConcat: false会跳过拼接,需要额外处理步骤补上 CSS Blocks 内容。
延伸阅读
- CSS Blocks 根 README:项目整体概览与能力介绍;
- @css-blocks/ember addon 文档:与本文 addon 配对的"撰写侧"插件,理解模板编译期发生了什么;
- addon 入口实现:构建管线的
preprocessTree/postprocessTree全流程; - broccoli-plugin 实现:编译、优化、冲突检测三个插件的源码细节;
- 运行时 service 实现:类名解析与优化表达式求值的运行时逻辑;
- 运行时数据生成测试:以测试用例直观展示
RuntimeDataGenerator产出的 block 接口数据结构。