LollipopCSS JavaScript API参考:compile()、compileAsync()、load()、apply()、download()完全用法

原创2026-11-15 23:59:241,618 阅读

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)。它会自动:

  1. 提取 @lollipop { ... } 配置块,解析出 values、shortcuts 和 snippets;
  2. 把正文中写成的快捷词(如 colorRed)展开为完整声明(如 color: #FF0000;);
  3. 把 ...snippetName 展开为整段样式块;
  4. 不认识的普通 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 括号

九、相关文件索引

小结 🍭

记住一条主线就够用:写字符串 → compile();有导入 → compileAsync();有现成 .lcss 文件 → load();拿到 CSS 后 → apply() 注入或 download() 导出。LollipopCSS 的目标不是取代 SCSS,而是让你用最少的手敲下最多的复用——Define once. Type less everywhere else.

登录后查看全文
lollipop-css