chrome.scripting

Description

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

Permissions

scripting

Availability

Chrome 88+ MV3+

# Manifest

为了使用 chrome.scripting API，您需要将“manifest_version”指定为 3 或更高，并在您的清单文件中包含“scripting”权限。

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

# Usage(用法)

您可以使用 chrome.scripting API 将 JavaScript 和 CSS 注入网站。这类似于您可以使用内容脚本（content scripts）执行的操作，但是通过使用 chrome.scripting API，扩展程序可以在运行时做出决定。

# Injection targets (注入 目标)

你可以使用 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'],
    },
    () => { ... });

您不能同时指定 frameIds 和 allFrames 属性。

# Injected code(注入 代码)

扩展可以通过外部文件或运行时变量指定要注入的代码。

# Files(文件)

文件被指定为相对于扩展根目录的路径的字符串。以下代码将文件 script.js 注入到选项卡的主框架中。

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

注意：目前最多支持单个文件。

# Runtime functions(运行 方法)

使用 scripting.executeScript() 注入 JavaScript 时，您可以指定要执行的函数而不是文件。该函数应该是当前扩展上下文可用的函数变量。

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

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

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

您可以使用 args 属性解决此问题：

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

# Runtime strings(运行时 字符串)

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

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

# Handling results(处理结果)

执行 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() 不返回任何结果。

Summary

• Types

  ContentScriptFilter

  CSSInjection

  ExecutionWorld

  InjectionResult

  InjectionTarget

  RegisteredContentScript

  ScriptInjection

  StyleOrigin

• Methods

  executeScript

  getRegisteredContentScripts

  insertCSS

  registerContentScripts

  removeCSS

  unregisterContentScripts

  updateContentScripts

Types

ContentScriptFilter

Chrome 96+

PROPERTIES

• ids

  string[] optional

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

CSSInjection

PROPERTIES

• css

  string optional

  包含要注入的 CSS 的字符串。必须指定files和 css 中的一个。

• files

  string[] optional

  要注入的 CSS 文件的路径，相对于扩展的根目录。必须指定files和 css 中的一个。

• origin

  StyleOrigin optional

  注入的样式来源。默认为“作者(AUTHOR)”。

• target

  InjectionTarget

  指定要插入 CSS 的目标的详细信息。

ExecutionWorld

Chrome 95+

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

TYPE

"ISOLATED", or "MAIN"

InjectionResult

PROPERTIES

• frameId

  number

  Chrome 90+

  与注入相关的框架。

• result

  any optional

  脚本执行的结果。

InjectionTarget

PROPERTIES

• allFrames

  boolean optional

  脚本是否应注入选项卡内的所有帧。默认为假。如果指定了 frameIds，则这不能为真。

• frameIds

  number[] optional

  要注入的特定帧的 ID。

• tabId

  number

  要注入的选项卡的 ID。

RegisteredContentScript

Chrome 96+

PROPERTIES

• allFrames

  boolean optional

  如果指定为 true，它将注入所有框架，即使该框架不是选项卡中最顶部的框架。每个框架都独立检查 URL 要求；如果不满足 URL 要求，它将不会注入到子框架中。默认为 false，意味着仅匹配顶部框架。

• css

  string[] optional

  要注入匹配页面的 CSS 文件列表。在为页面构造或显示任何 DOM 之前，它们按照它们在此数组中出现的顺序注入。

• excludeMatches

  string[] optional

  排除此内容脚本将被注入的页面。有关这些字符串的语法的更多详细信息，请参阅匹配模式。

• id

  string

  内容脚本的 ID，在 API 调用中指定。不得以“_”开头，因为它被保留为生成的脚本 ID 的前缀。

• js

  string[] optional

  要注入匹配页面的 JavaScript 文件列表。它们按照它们在此数组中出现的顺序注入。

• matches

  string[] optional

  指定此内容脚本将被注入到哪些页面。有关这些字符串的语法的更多详细信息，请参阅匹配模式。必须为 registerContentScripts 指定。

• persistAcrossSessions

  boolean optional

  指定此内容脚本是否会持续到未来的会话中。默认值为真。

• runAt

  RunAt optional

  指定何时将 JavaScript 文件注入到网页中。首选和默认值是 document_idle。

ScriptInjection

PROPERTIES

• args

  any[] optional

  Chrome 92+

  柯里化(curry)到提供的函数中的参数。这仅在指定了 func 参数时才有效。这些参数必须是 JSON 可序列化的。

• files

  string[] optional

  要注入的 JS 或 CSS 文件的路径，相对于扩展的根目录。必须指定文件(files)和 func 中的一个。

• target

  InjectionTarget

  指定要注入脚本的目标的详细信息。

• world

  ExecutionWorld optional

  Chrome 95+

  运行脚本的 JavaScript “世界(world)”。默认为 Isolated。

• func

  function optional

  Chrome 92+

  要注入的 JavaScript 函数。这个函数会被序列化，然后反序列化注入。这意味着任何绑定参数和执行上下文都将丢失。必须指定文件files和 func 中的一个。

  func 函数如下所示：

  () => {...}

StyleOrigin

风格变化的起源。有关更多信息，请参阅样式起源（style origins）。

TYPE

"AUTHOR", or "USER"

Methods

executeScript

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

Promise

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

PARAMETERS

• injection

  ScriptInjection

  要注入的脚本的详细信息。

• callback

  function optional

  回调参数如下所示：

  (results: InjectionResult[]) => void

  • results

    InjectionResult[]

RETURNS

• Promise<InjectionResult[]>

  Pending

  这仅在未指定callback参数时返回 Promise，并且使用 MV3+。 Promise 中的类型与callback的第一个参数相同。

getRegisteredContentScripts

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

Promise Chrome 96+

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

PARAMETERS

• filter

  ContentScriptFilter optional

  过滤扩展动态注册脚本的对象。

• callback

  function optional

  回调参数如下所示：

  (scripts: RegisteredContentScript[]) => void

  • scripts

    RegisteredContentScript[]

RETURNS

• Promise<RegisteredContentScript[]>

  Pending

  这仅在未指定callback参数时返回 Promise，并且使用 MV3+。 Promise 中的类型与callback的第一个参数相同。

insertCSS

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

Promise

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

PARAMETERS

• injection

  CSSInjection

  要插入的样式的详细信息。

• callback

  function optional

  回调参数如下所示：

  () => void

RETURNS

• Promise<void>

  Pending

  这仅在未指定callback参数时返回 Promise，并且使用 MV3+。 Promise 中的类型与callback的第一个参数相同。

registerContentScripts

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

Promise Chrome 96+

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

PARAMETERS

• scripts

  RegisteredContentScript[]

  包含要注册的脚本列表。如果在脚本解析/文件验证期间出现错误，或者如果指定的 ID 已经存在，则不会注册任何脚本。

• callback

  function optional

  回调参数如下所示：

  () => void

RETURNS

• Promise<void>

  Pending

  这仅在未指定callback参数时返回 Promise，并且使用 MV3+。 Promise 中的类型与callback的第一个参数相同。

removeCSS

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

Promise Chrome 90+

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

PARAMETERS

• injection

  CSSInjection

  要删除的样式的详细信息。请注意，css、文件files和源属性origin必须与通过 insertCSS 插入的样式表完全匹配。试图删除一个不存在的样式表是一个空操作。

• callback

  function optional

  回调参数如下所示：

  () => void

RETURNS

• Promise<void>

  Pending

  这仅在未指定callback参数时返回 Promise，并且使用 MV3+。 Promise 中的类型与callback的第一个参数相同。

unregisterContentScripts

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

Promise Chrome 96+

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

PARAMETERS

• filter

  ContentScriptFilter optional

  如果指定，则仅取消注册与过滤器匹配的动态内容脚本。否则，所有扩展的动态内容脚本都将被取消注册。

• callback

  function optional

  回调参数如下所示：

  () => void

RETURNS

• Promise<void>

  Pending

  这仅在未指定callback参数时返回 Promise，并且使用 MV3+。 Promise 中的类型与callback的第一个参数相同。

updateContentScripts

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

Promise Chrome 96+

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

PARAMETERS

• scripts

  RegisteredContentScript[]

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

• callback

  function optional

  回调参数如下所示：

  () => void

RETURNS

• Promise<void>

  Pending

  这仅在未指定callback参数时返回 Promise，并且使用 MV3+。 Promise 中的类型与callback的第一个参数相同。

By.一粒技术服务