谷歌浏览器插件教程scripting 注入脚本

chrome.scripting

使用chrome.scripting API 在不同的上下文中执行脚本。
需要权限

{
  "name": "Scripting Extension",
  "manifest_version": 3,
  "permissions": ["scripting"],
  ...
}

您可以使用chrome.scriptingAPI 将 JavaScript 和 CSS 注入网站。这类似于您可以使用内容脚本执行的操作，但通过使用chrome.scriptingAPI，扩展可以在运行时做出决策。

用法

您可以使用该target参数指定将 JavaScript 或 CSS 注入的目标。
唯一必填字段是tabId。默认情况下，注入将在指定选项卡的主框架中运行。

const tabId = getTabId();
chrome.scripting.executeScript(
    {
      target: {tabId: tabId},
      files: ['script.js'],
    },
    () => { ... });

要在指定选项卡的所有帧中运行，您可以将allFrames布尔值设置为true.

const tabId = getTabId();
chrome.scripting.executeScript(
    {
      target: {tabId: tabId, allFrames: true},
      files: ['script.js'],
    },
    () => { ... });

您还可以通过指定单个框架 ID 来注入选项卡的特定框架。有关框架 ID 的更多信息，请参阅webNavigation API。

const tabId = getTabId();
const frameIds = [frameId1, frameId2];
chrome.scripting.executeScript(
    {
      target: {tabId: tabId, frameIds: frameIds},
      files: ['script.js'],
    },
    () => { ... });

运行时函数

function getTitle() {
  return document.title;
}
const tabId = getTabId();
chrome.scripting.executeScript(
    {
      target: {tabId: tabId},
      func: getTitle,
    },
    () => { ... });

该函数将在注入目标的上下文中执行。但是，这不会继承函数的任何当前执行上下文。因此，绑定参数（包括this对象）和外部引用的变量将导致错误。例如，以下代码将不起作用，并且会color在函数执行时抛出 ReferenceError 因为未定义：

const color = getUserColor();
function changeBackgroundColor(backgroundColor) {
  document.body.style.backgroundColor = backgroundColor;
}
const tabId = getTabId();
chrome.scripting.executeScript(
    {
      target: {tabId: tabId},
      func: changeBackgroundColor,
      args: [color],
    },
    () => { ... });

运行时字符串
如果在页面中注入 CSS，您还可以指定要在css属性中使用的字符串。此选项仅适用于scripting.insertCSS(); 您不能使用scripting.executeScript().

const css = 'body { background-color: red; }';
const tabId = getTabId();
chrome.scripting.insertCSS(
    {
      target: {tabId: tabId},
      css: css,
    },
    () => { ... });

处理结果
执行 JavaScript 的结果将传递给扩展。每帧包含一个结果。主框架保证是结果数组中的第一个索引；所有其他帧都处于不确定的顺序。

function getTitle() {
  return document.title;
}
const tabId = getTabId();
chrome.scripting.executeScript(
    {
      target: {tabId: tabId, allFrames: true},
      func: getTitle,
    },
    (injectionResults) => {
      for (const frameResult of injectionResults)
        console.log('Frame Title:' + frameResult.result);
    });

scripting.insertCSS() 不返回任何结果。

如果脚本执行的结果值是一个 Promise，Chrome 将等待 Promise 解决并返回结果值。

async function addIframe() {
  const iframe = document.createElement('iframe');
  const loadComplete = new Promise((resolve) => {
    iframe.addEventListener('load', resolve);
  });
  iframe.src = 'https://example.com';
  document.body.appendChild(iframe);
  await loadComplete;
  return iframe.contentWindow.document.title;
}

const tabId = getTabId();
chrome.scripting.executeScript(
    {
      target: {tabId: tabId, allFrames: true},
      func: addIframe,
    },
    (injectionResults) => {
      for (const frameResult of injectionResults)
        console.log('Iframe Title:' + frameResult.result);
    });

类型

ContentScriptFilter

• ids 如果指定，getRegisteredContentScripts将仅返回具有此列表中指定 id 的脚本。

CSSInjection

CSS注入

• css 包含要注入的 CSS 的字符串。files并且css必须指定其中之一。
• files 要注入的 CSS 文件的路径，相对于扩展的根目录。files并且css必须指定其中之一。
• origin 注入的样式来源。默认为 'AUTHOR'.
• target 指定要插入 CSS 的目标的详细信息。

ExecutionWorld

脚本在其中执行的 JavaScript 世界。

• ISOLATED 单独
• MAIN 主要

InjectionResult

• frameId 与注入关联的帧。
• result 脚本执行的结果。

InjectionTarget

• allFrames 脚本是否应注入选项卡内的所有帧。默认为假。frameIds如果已指定，则不能为真。
• frameIds 要注入的特定帧的ID 。
• tabId 要注入的选项卡的 ID。

RegisteredContentScript

• allFrames 如果指定为 true，它将注入所有帧，即使该帧不是选项卡中最顶层的帧。每个框架都独立检查 URL 要求；如果不满足 URL 要求，它将不会注入到子框架中。默认为 false，表示仅匹配顶部帧。
• css 要注入匹配页面的 CSS 文件列表。在为页面构建或显示任何 DOM 之前，它们按照它们在此数组中出现的顺序被注入。
• excludeMatches 排除此内容脚本将被注入的页面。有关这些字符串的语法的更多详细信息，请参阅匹配模式。
• id 内容脚本的 ID，在 API 调用中指定。不能以“_”开头，因为它保留为生成的脚本 ID 的前缀。
• js 要注入匹配页面的 JavaScript 文件列表。这些是按照它们在这个数组中出现的顺序注入的
• matches 指定此内容脚本将被注入到哪些页面。有关这些字符串的语法的更多详细信息，请参阅匹配模式。必须为 指定registerContentScripts。
• persistAcrossSessions 指定此内容脚本是否将持续到未来的会话中。默认值为真。
• runAt 指定何时将 JavaScript 文件注入网页。首选和默认值为document_idle.
• world 运行脚本的 JavaScript“世界”。默认为ISOLATED.

ScriptInjection

• args 提供的函数中的参数
• files 要注入的 JS 或 CSS 文件的路径，相对于扩展的根目录。files并且func必须指定其中之一
• injectImmediately 是否应该尽快在目标中触发注入。请注意，这并不能保证在页面加载之前会发生注入，因为在脚本到达目标时页面可能已经加载。
• target 指定要注入脚本的目标的详细信息。
• world 运行脚本的 JavaScript“世界”。默认为ISOLATED.
• func 要注入的 JavaScript 函数。该函数将被序列化，然后反序列化以进行注入。这意味着任何绑定的参数和执行上下文都将丢失

StyleOrigin

• AUTHOR
• USER

方法

executeScript

将脚本注入目标上下文。该脚本将在document_idle. 如果脚本评估为一个承诺，浏览器将等待承诺解决并返回结果值。

chrome.scripting.executeScript(
  injection: ScriptInjection,
  callback?: function,
)

callback参数如下所示：

(results: InjectionResult[]) => void

getRegisteredContentScripts

返回与给定过滤器匹配的此扩展的所有动态注册的内容脚本。

chrome.scripting.getRegisteredContentScripts(
  filter?: ContentScriptFilter,
  callback?: function,
)

callback参数如下所示：

(scripts: RegisteredContentScript[]) => void

insertCSS

将 CSS 样式表插入到目标上下文中。如果指定了多个帧，则忽略不成功的注入。

chrome.scripting.insertCSS(
  injection: CSSInjection,
  callback?: function,
)

callback参数如下所示：

() => void

registerContentScripts

为此扩展注册一个或多个内容脚本。

chrome.scripting.registerContentScripts(
  scripts: RegisteredContentScript[],
  callback?: function,
)

callback参数如下所示：

() => void

removeCSS

从目标上下文中删除此扩展先前插入的 CSS 样式表。

chrome.scripting.removeCSS(
  injection: CSSInjection,
  callback?: function,
)

• injection:要删除的样式的详细信息。请注意css，files、 和origin属性必须与通过 插入的样式表完全匹配insertCSS。尝试删除不存在的样式表是无操作的。
• callback参数如下所示：

() => void

unregisterContentScripts

取消注册此扩展的内容脚本。

chrome.scripting.unregisterContentScripts(
  filter?: ContentScriptFilter,
  callback?: function,
)

• filter:如果指定，仅注销与过滤器匹配的动态内容脚本。否则，所有扩展的动态内容脚本都将被注销。
• callback参数如下所示：

() => void

updateContentScripts

更新此扩展的一个或多个内容脚本。

chrome.scripting.updateContentScripts(
  scripts: RegisteredContentScript[],
  callback?: function,
)

• scripts 包含要更新的脚本列表。如果在此对象中指定了属性，则仅更新现有脚本的属性。如果在脚本解析/文件验证期间出现错误，或者如果指定的 ID 与完全注册的脚本不对应，则不会更新任何脚本。
• callback参数如下所示：

  () => void