Skip to main content
Extension.js 无需任何配置即可支持纯 CSS 以及 Sass、Less 预处理器。对页面上下文(popup、options、side panel)和 content script 上下文,它会采用不同的样式路由方式。 页面样式会作为关联的资源发布。Extension.js 会把 content script 的样式注入到网页的 document 中,使其作用于当前活动标签页。

模板示例

content-sass

content-sass template screenshot 带有 Sass 样式的 content script,注入到网页中。
仓库:extension-js/examples/content-sass

content-custom-font

content-custom-font template screenshot 演示通过 CSS 加载自定义字体的 content script。
仓库:extension-js/examples/content-custom-font

CSS 能力

在哪里引用 CSS

  • manifest.jsoncontent_scripts[].css
  • HTML 文件(<link rel="stylesheet" href="...">
  • 脚本导入(import "./styles.css",启用时也包括 Sass/Less)

CSS 支持

Manifest CSS 入口:

示例:manifest.json 中的 CSS

示例:扩展页面脚本中的 CSS

内容脚本中的网页字体

把界面渲染到 shadow root 的内容脚本,无法只靠 CSS 加载网页字体。有两条平台规则会挡住它,而且都是静默的。 shadow root 内部的 @font-face 永远不会生效。 字体(font face)解析的是文档的字体集,而不是 shadow 树,所以 Chrome 会忽略该规则并静默回退。修复前在 content-custom-font 模板上实测:document.fonts 为空,没有发出任何字体请求,用 "Momo Signature", cursive 排版的文本宽度与纯 cursive 完全相同。 注入样式表里的根绝对 url() 会相对宿主页面解析。 注入到 example.com 的样式表中的 url(/fonts/Momo.woff2) 请求的是 https://example.com/fonts/Momo.woff2,而不是扩展自己的那份文件。 改为把字体注册到页面自身的字体集上,URL 指向扩展,并在内容脚本卸载时移除它:
该字体文件必须能被页面访问,所以要在 web_accessible_resources 中声明:
字体一旦进入 document.fonts,shadow 树就可以在普通的 font-family 规则里按名称使用它。可运行的版本见 content-custom-font

按上下文的输出行为

Extension.js 会根据哪个入口导入了 CSS 自动拆分上下文。

开发期行为

  • Content script 的 CSS 导入会参与 content script 的 HMR/重新挂载流程。
  • Extension.js 会为只有 CSS 的 content script 入口添加一个开发期辅助脚本,使更新得以传播。
  • 页面 CSS 遵循常规的页面 HMR 管线行为。
  • 结构性的 manifest/content script 变更仍可能需要扩展完整重载或重启。

模块化与预处理器

  • CSS 模块在扩展页面上下文中表现最好。
  • 当你安装相关依赖时,Extension.js 会启用 Sass/Less 支持。
  • 如果项目引用了 .scss/.less 文件但没有安装预处理器,构建不会失败,而是发出警告并把源文件原样拷贝过去(不编译)。浏览器会把这份未编译的源码当作坏掉的 CSS,于是相关界面会完全没有样式,因此请安装预处理器以获得真正的编译。
  • 当 Extension.js 检测到项目中存在 PostCSS 配置,或者你显式配置时,会自动运行 PostCSS。

最佳实践

  • 把 content script 样式有意识地限定作用范围,减少与宿主页面的冲突。
  • 对扩展页面 UI,优先使用组件级的模块样式。
  • 显式地维护预处理器和 PostCSS 配置,避免随时间发生非预期的构建行为变化。
  • 在持续集成(CI)中校验 manifest 字段所引用的 CSS 路径。

下一步

视频讲解