LollipopCSS JavaScript API参考:compile()、compileAsync()、load()、apply()、download()完全用法
LollipopCSS JavaScript API参考:compile()、compileAsync()、load()、apply()、download()完全用法
LollipopCSS 是一款极简的 CSS 预处理器,允许你用自定义词汇(values、shortcuts、snippets)少写代码、编译出标准 CSS。本文完整讲解它的 5 个核心 JavaScript API——compile()、compileAsync()、load()、apply()、download(),外加浏览器自动加载模式,帮你快速上手这套懒人友好的样式编译方案。
一、API 总览:5 个方法各管一摊
LollipopCSS 当前版本为 0.2.0(见 package.json),全部功能集中在一个类里,源码仅约 500 行,无任何依赖。核心 API 一览:
| API | 类型 | 作用 | 适用场景 |
|---|---|---|---|
compile(source) |
实例方法 | 同步编译 LollipopCSS 字符串 | 手写源码字符串,立即得到 CSS |
compileAsync(source, options) |
实例方法 | 异步编译,支持 @importlollipop 引入 |
多文件拆分、按需加载导入 |
load(url, options) |
静态方法 | 拉取 .lcss 文件 → 编译 → 注入/下载/返回文本 |
浏览器中最常用的一键方案 |
apply(css, target) |
静态方法 | 把编译好的 CSS 注入 <style> 标签 |
手动接管注入过程 |
download(content, options) |
静态方法 | 把 CSS 存成文件下载到本地 | 生成构建产物、样式导出 |
所有 API 都定义在 src/lollipop-css.js 的 LollipopCSS 类中,加载后会挂到 globalThis.LollipopCSS,浏览器和 Node.js 都能用。
如何引入 LollipopCSS
浏览器里直接引入脚本即可,文件是 src/lollipop-css.js:
<script src="lollipop-css.js" defer></script>
Node.js 中则通过 CommonJS 引入(见 src/lollipop-css.js 末尾的 module.exports 逻辑):
const LollipopCSS = require("lollipop-css");
💡 如果页面里已按规范写好了
<link rel="lollipop-stylesheet">和<style type="text/lollipop">,脚本会自动完成加载与编译,一行 API 都不用写——细节见文末"自动模式"。
二、compile():同步编译,最基础的一步
compile(source) 接收一段 LollipopCSS 字符串,同步返回编译后的标准 CSS(实现见 src/lollipop-css.js)。它会自动:
- 提取
@lollipop { ... }配置块,解析出 values、shortcuts 和 snippets; - 把正文中写成的快捷词(如
colorRed)展开为完整声明(如color: #FF0000;); - 把
...snippetName展开为整段样式块; - 不认识的普通 CSS 原样保留,绝不破坏你的既有样式。
const compiler = new LollipopCSS();
const css = compiler.compile(`
@lollipop {
red #FF0000
colorRed color red
}
.title {
colorRed
}`);
console.log(css); // .title { color: #FF0000; }
⚠️ 两个重要限制:
- 遇到
@importlollipop会直接抛错:@importlollipop requires compileAsync() or LollipopCSS.load(),因为导入涉及异步网络请求; @lollipop块缺少右括号时会报@lollipop block is missing a closing }(错误处理逻辑见 src/lollipop-css.js)。
三、compileAsync():编译带导入的多文件项目
compileAsync(source, options) 是 compile() 的异步增强版(实现见 src/lollipop-css.js),专门解决 @importlollipop "./var.lcss" 这类跨文件引用。它会先递归展开所有导入,再执行同步编译。
options 参数说明
| 参数 | 类型 | 说明 |
|---|---|---|
baseUrl |
字符串 | 当前文件的地址,用于解析相对导入路径 |
loadImport |
函数 | 自定义导入加载器,签名为 async (specifier, baseUrl) => { source, baseUrl } |
不提供 loadImport 时,默认使用内置的 fetch 加载器(src/lollipop-css.js)自动按 URL 拉取文件。
最小用法:
const css = await new LollipopCSS().compileAsync(source, {
baseUrl: "./style.lcss"
});
项目示例 examples/index_import.html 就是真实演示:手动 fetch 到 examples/style.lcss 的源码后调用 compileAsync(),它成功展开了对 examples/var.lcss(定义色板、间距等词汇)和 examples/basic.lcss 的两条 @importlollipop 导入。
🛡️ 内置安全防护:
- 循环导入检测:A 引入 B、B 又引入 A 时,会报
Circular @importlollipop detected(检测逻辑见 src/lollipop-css.js 的importStack); - 加载失败报错:网络 404 等会报
Failed to load <url>: <status>,方便定位是哪个文件出问题; - 导入结果校验:加载器没返回源码时会明确提示
Import loader returned no source for ...。
测试用例中对循环导入的断言可参考 tests/lollipop-css.test.js。
四、load():一键拉取、编译、注入
LollipopCSS.load(url, options) 是浏览器场景下的"懒人一键流"(实现见 src/lollipop-css.js):fetch 拉取 .lcss 文件 → 调用 compileAsync() 编译(自动带上正确 baseUrl)→ 按 output 模式处理结果。
output 三种输出模式
| 模式 | 行为 | 返回值 |
|---|---|---|
style(默认) |
编译结果注入 <style> 标签 |
该 style 元素,并带 data-lollipop-source 属性记录来源 |
text |
只返回编译后的 CSS 文本 | CSS 字符串 |
download |
编译后触发浏览器下载 | 下载的文件名 |
// 注入页面(默认)
await LollipopCSS.load("./style.lcss");
// 只要编译后的文本
const css = await LollipopCSS.load("./style.lcss", { output: "text" });
// 直接下载为 css 文件
await LollipopCSS.load("./style.lcss", {
output: "download",
filename: "bundle.css"
});
可选参数 filename(下载文件名,默认 style.css)和 target(注入目标容器,默认 document.head)可按需传入。传入非法的 output 值会报 Unsupported output mode: xxx,帮助排查拼写问题。
五、apply():手动注入编译好的 CSS
LollipopCSS.apply(css, target = document.head) 是 load() 内部用的底层注入工具(实现见 src/lollipop-css.js):新建一个 <style> 标签、写入 CSS 文本、追加到目标节点,并返回该元素。
当你想自己控制何时、加到哪时最有用,典型组合是"先 compile 再 apply":
const css = new LollipopCSS().compile(source);
const style = LollipopCSS.apply(css); // 默认注入 document.head
LollipopCSS.apply(css, someContainer); // 或注入指定容器
examples/index_import.html 中的完整套路就是:fetch 源码 → compileAsync() 编译 → apply() 注入 → 在返回的 style 上记录来源 URL。
六、download():把 CSS 存成文件
LollipopCSS.download(content, options) 在浏览器里生成一个 Blob 并模拟点击下载(实现见 src/lollipop-css.js),适合"在线编辑器编译后导出成品"这类场景。
options.filename:文件名,默认style.css;- 扩展名智能识别:
.scss文件会以text/x-scss类型下载,其余一律按text/css处理; - 返回值就是最终文件名,方便你在界面上提示用户。
LollipopCSS.download(compiledCss, { filename: "style.css" });
七、进阶:loadLinks()、compileInline() 与 auto() 自动模式
除了手动调 API,LollipopCSS 还内置了三种"声明式"用法(均在 src/lollipop-css.js):
| 方法 | 识别标记 | 行为 |
|---|---|---|
loadLinks(root) |
<link rel="lollipop-stylesheet"> |
逐个拉取、编译、替换为 <style> |
compileInline(root) |
<style type="text/lollipop"> |
原地编译内联 LollipopCSS |
auto(root) |
上面两者都处理 | 编译内联 + 加载外部,一次全搞定 |
关键细节:脚本检测到 document 存在时会自动挂上 DOMContentLoaded 监听并调用 auto()(见 src/lollipop-css.js)。所以 examples/index.html 只需声明:
<script src="../src/lollipop-css.js" defer></script>
<link rel="lollipop-stylesheet" href="./style.lcss">
页面加载完就会自动把 examples/style.lcss 连同它导入的 examples/var.lcss 一起编译注入,全程零 JS。自动加载失败时会在控制台输出 LollipopCSS auto-load failed: 加具体错误,便于排查。
八、常见报错速查表
| 错误信息 | 原因 | 解决方式 |
|---|---|---|
@importlollipop requires compileAsync() or LollipopCSS.load() |
对含导入的源码用了同步 compile() |
改用 compileAsync() 或 load() |
@lollipop block is missing a closing } |
@lollipop 配置块没写右括号 |
补全括号(报错位置) |
Circular @importlollipop detected: xxx |
两个 .lcss 文件互相导入 |
打破循环引用 |
Failed to load <url>: 404 |
文件路径不存在 | 检查 URL 或 baseUrl 是否正确 |
Snippet "name" is missing a closing } |
snippet 块没闭合 | 补全 snippet 括号 |
九、相关文件索引
- 核心源码(全部 API 所在):src/lollipop-css.js
- 完整用法文档与语法示例:README.md
- 示例项目(外部样式 + 导入演示):examples/ 目录,含 style.lcss、var.lcss、basic.lcss
- 浏览器 Demo(外链加载方式):examples/index.html
- 手动导入演示(
compileAsync()+apply()组合):examples/index_import.html - 行为验证用例:tests/lollipop-css.test.js,运行
npm test即可执行
小结 🍭
记住一条主线就够用:写字符串 → compile();有导入 → compileAsync();有现成 .lcss 文件 → load();拿到 CSS 后 → apply() 注入或 download() 导出。LollipopCSS 的目标不是取代 SCSS,而是让你用最少的手敲下最多的复用——Define once. Type less everywhere else.