谷歌浏览器插件教程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

评论区 (0)

没有记录
支持 markdown,图片截图粘贴拖拽都可以自动上传。
空气

空气 · 中级学士

热爱技术,喜欢新东西。

老程序员年度分享MVP
查看更多

最新视频课程

钻级赞助商