tabs.insertCSS()

向一个页面注入 CSS。

备注: 当使用 Manifest V3 或更高版本时,请使用 scripting.insertCSS()scripting.removeCSS() 来插入和移除 CSS。

使用该 API 前你必须拥有目标页面 URL 的权限,可以是主机权限, 或者使用 activeTab 权限

你只能向 URL 符合匹配模式的网页注入 CSS——其方案必须是“http”、“https”、“file”和“ftp”之一。你不能向任何浏览器内置页面注入 CSS,比如 about:debugging、about:addons 或者你打开的一个新的空白页。

备注: Firefox 在注入的 CSS 文件中解析 URL 时是相对于 CSS 文件本身的位置,而不是相对于它被注入到的页面的位置。

当再次调用 tabs.removeCSS() 时,已经注入的 CSS 可能会被移除。

这是一个返回 Promise 的异步函数。

语法

js
let inserting = browser.tabs.insertCSS(
  tabId,           // 可选的整型
  details          // 对象
)

参数

tabId 可选

integer。要插入 CSS 的选项卡 ID。默认为当前窗口的活动选项卡。

details

描述要插入的 CSS 的对象。包含以下属性:

allFrames 可选

boolean。如果为 true,则将 CSS 注入到当前页面的所有框架中。如果为 false,则仅将 CSS 注入到顶层框架。默认为 false

code 可选

string。要注入的代码(文本字符串形式)。

cssOrigin 可选

string。可以取以下两个值之一:“user”,表示将 CSS 添加为用户样式表;“author”,表示将其添加为作者样式表。如果省略此选项,则 CSS 将作为作者样式表添加。

  • “user”允许你防止网站覆盖你插入的 CSS。参见层叠顺序
  • “author”样式表的行为就像它们出现在页面指定的所有作者规则之后一样。这种行为包括页面脚本动态添加的任何作者样式表,即使此添加发生在 insertCSS 调用完成之后。
file 可选

string。包含要插入代码的文件路径。在 Firefox 中,相对 URL 是相对于当前页面 URL 解析的。在 Chrome 中,这些 URL 是相对于扩展的基础 URL 解析的。为了跨浏览器工作,你可以将路径指定为绝对 URL,从扩展的根目录开始,例如 "/path/to/stylesheet.css"

frameId 可选

integer。应该插入 CSS 的框架 ID。默认为 0(顶层框架)。

matchAboutBlank 可选

boolean。如果为 true,则代码将被注入到嵌入的“about:blank”和“about:srcdoc”框架中,如果你的扩展具有访问其父文档的权限。不能在顶级 about: 框架中插入代码。默认为 false

runAt 可选

extensionTypes.RunAt。代码将被注入到选项卡中的最早时间。默认为“document_idle”。

返回值

一个 Promise,在所有 CSS 都插入完成时其会被兑现且不带有参数。如果发生任何错误,promise 会以错误信息拒绝。

示例

这个示例将来自字符串的 CSS 插入到当前活动标签页中。

js
let css = "body { border: 20px dotted pink; }";

browser.browserAction.onClicked.addListener(() => {
  function onError(error) {
    console.log(`Error: ${error}`);
  }

  let insertingCSS = browser.tabs.insertCSS({ code: css });
  insertingCSS.then(null, onError);
});

这个示例从扩展中打包的文件中加载 CSS,并将其插入到 ID 为 2 的标签页中:

js
browser.browserAction.onClicked.addListener(() => {
  function onError(error) {
    console.log(`Error: ${error}`);
  }

  let insertingCSS = browser.tabs.insertCSS(2, { file: "content-style.css" });
  insertingCSS.then(null, onError);
});

示例扩展

浏览器兼容性

BCD tables only load in the browser

备注: 此 API 基于 Chromium 的 chrome.tabs API。此文档来源于 Chromium 代码库中的 tabs.json