Plasmo CSUI 样式化指南

Plasmo CSUI 的内置 根容器为扩展开发者提供了强大的组件样式化机制。在大多数情况下，它能够确保：

导出的样式不会泄漏到宿主网页中
网页的样式不会影响组件的视觉表现

请参阅注意事项了解可能存在的限制情况。

原始 CSS 文本样式

要为您的 CSUI 组件添加样式，可以导出一个 getStyle 函数：

content.tsx


import type { PlasmoGetStyle } from "plasmo"
 
export const getStyle: PlasmoGetStyle = () => {
  const style = document.createElement("style")
  style.textContent = `
    p {
      background-color: yellow;
    }
  `
  return style
}

导入样式表文件

要导入 CSS/LESS/SASS 文件，可以将 getStyle API 与 data-text 导入方案结合使用：

content.tsx


import styleText from "data-text:./style.scss"
import type { PlasmoGetStyle } from "plasmo"
 
export const getStyle: PlasmoGetStyle = () => {
  const style = document.createElement("style")
  style.textContent = styleText
  return style
}

CSS-in-JS 方案

getStyle API 同样适用于 CSS-in-JS 样式缓存的水合过程，例如在使用 emotion 时：

content.tsx


import createCache from "@emotion/cache"
import { CacheProvider } from "@emotion/react"
import type { PlasmoGetStyle } from "plasmo"
 
const styleElement = document.createElement("style")
 
const styleCache = createCache({
  key: "plasmo-emotion-cache",
  prepend: true,
  container: styleElement
})
 
export const getStyle: PlasmoGetStyle = () => styleElement

CSS 模块支持

要使用 CSS 模块，需要进行两次样式表导入：

content.tsx


import styleText from "data-text:./style.module.css"
import type { PlasmoCSConfig } from "plasmo"
 
import * as style from "./style.module.css"
 
export const getStyle = () => {
  const style = document.createElement("style")
  style.textContent = styleText
  return style
}
 
const Overlay = () => <h1 className={style.header}>船长日志</h1>
 
export default Overlay

自定义字体支持

要在 CSUI 中使用自定义字体，必须在 CSS 文件中导入字体并在配置对象的 css 属性中声明。如果在 ShadowDOM 内部声明，浏览器无法正确识别字体资源，必须在全局范围内加载它们。

在 assets 目录中添加字体文件（例如 /assets/Fascinate.woff2）
在内容脚本旁创建 font.css 文件，使用 data-base64 方案内联导入字体：

font.css


@font-face {
  font-family: "Fascinate";
  font-style: normal;
  font-weight: 400;
  font-display: swap;
  src: url(data-base64:~assets/Fascinate.woff2) format("woff2");
  unicode-range: U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA,
    U+02DC, U+2000-206F, U+2074, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215,
    U+FEFF, U+FFFD;
}

在内容脚本配置的 css 属性中声明该文件：

content.tsx


export const config: PlasmoCSConfig = {
  matches: ["https://www.plasmocn.org/*"],
  css: ["font.css"]
}

浏览器注册字体后，即可在 CSS 样式中引用：

style.css


.hw-top {
  background: red;
  color: white;
  font-family: "Fascinate";
}

完整示例请参考 with-content-scripts-ui/contents/plasmo-overlay.tsx 。

Shadow DOM 样式定制

使用 ID #plasmo-shadow-container 和 plasmo-inline 可以在 CSS 中修改 根容器 的样式：

style.css


#plasmo-shadow-container {
  z-index: 99999;
}
 
#plasmo-inline {
  background: blue;
}

⚠️

如果某些样式规则未被正确覆盖，请参阅注意事项：根容器样式。

继承网页样式

要继承网页的样式，可以覆盖内置的 根容器，将组件直接挂载到网页的 DOM 中。点击此处了解更多详情。

注意事项

框架的通用样式封装机制目前无法处理某些特殊情况。以下是一些常见的注意事项：

CSS 变量共享

CSS 变量在同一浏览器标签页内的各个框架之间是共享的。这意味着如果网页在 :root 上下文中声明了 CSS 变量，这些变量将优先于您的变量。

要缓解 CSUI 和网页之间的 CSS 变量冲突，您可以：

为 CSS 变量使用唯一的前缀命名空间
将 CSS 变量提升到 :host 作用域下
将组件挂载在具有独立 head 和 body 的 iframe 中

根容器样式覆盖

如果宿主网页使用全局 * 选择器来设置页面样式，可能会覆盖 根容器 的样式。例如：


* {
  display: block;
}

上述代码将导致根容器具有块级显示特性。在这种情况下，使用内联样式覆盖根容器样式有助于保持容器的一致性。

在某些情况下，可能存在 CSS 样式声明无法被正常覆盖的情况。此时可以使用 !important 标志作为临时解决方案。

style.css


#plasmo-shadow-container {
  z-index: 2147483646 !important;
}