内容脚本（Content Scripts）

指定在用户打开某些网页时要使用的 JavaScript 或 CSS 文件。

内容脚本是在网页环境中运行的文件。通过使用标准文档对象模型 (DOM)，开发者能够读取浏览器所访问网页的详情、更改这些网页，并将信息传递给其父级扩展程序。

一、内容脚本功能

内容脚本在声明扩展程序文件为可通过网络访问的资源后，便可访问扩展程序文件。他们可以直接访问以下扩展程序 API：

内容脚本无法直接访问其他 API。但用户可以通过与扩展程序的其他部分交换消息来间接访问这些扩展程序。

二、隔离环境

隔离世界是一种私有执行环境，页面或其他扩展程序无法访问。这种隔离带来的实际结果是，扩展程序内容脚本中的 JavaScript 变量对托管页面或其他扩展程序的内容脚本不可见。此概念最初是在 Chrome 首次发布时引入的，用于隔离浏览器标签页。

不仅每个扩展程序都会在各自的独立世界中运行，内容脚本和网页也会在这方面运行。这意味着它们（网页、内容脚本和任何正在运行的扩展程序）都无法访问其他项的上下文和变量。

内容脚本位于一个独立的环境中，这使得内容脚本可以对其 JavaScript 环境进行更改，而不会与网页或其他扩展程序的内容脚本发生冲突。

1. 示例

插件在类似于以下示例的网页中运行。

webPage.html

<html>

  <button id="mybutton">click me</button>

  <script>

    var greeting = "hello, ";

    var button = document.getElementById("mybutton");

    button.person_name = "Bob";

    button.addEventListener(

        "click", () => alert(greeting + button.person_name + "."), false);

  </script>

</html>

该扩展程序可以使用注入脚本部分中所述的方法之一注入以下内容脚本。

content-script.js

var greeting = "hola, ";

var button = document.getElementById("mybutton");

button.person_name = "Roberto";

button.addEventListener("click", () => alert(greeting + button.person_name + "."), false);

进行此项更改后，用户点击按钮时，系统会按顺序显示两个提醒。

三、注入脚本（Inject scripts）

内容脚本可以静态声明、动态声明或以编程方式注入。

1. 使用静态声明进行注入

使用 manifest.json 中的静态内容脚本声明。

静态声明的脚本在清单中的 "content_scripts" 键下注册。可以包含 JavaScript 文件和/ CSS 文件。所有自动运行的内容脚本都必须指定匹配模式。

manifest.json

{

 "name": "My extension",

 "content_scripts": [

   {

     "matches": ["https://*.nytimes.com/*"],

     "css": ["my-styles.css"],

     "js": ["content-script.js"]

   }

 ],

}
名称 类型 说明
matches 字符串数组 string[] 必需。指定将此内容脚本注入到哪些网页。
css 字符串数组 string[] 可选。要注入到匹配页面的 CSS 文件列表。这些代码会按照它们在此数组中出现的顺序进行注入，然后为网页构建或显示任何 DOM。
js 字符串数组 string[] 可选。要注入到匹配页面的 JavaScript 文件的列表。系统会按照文件在此数组中出现的顺序注入文件。此列表中的每个字符串都必须包含扩展程序根目录中某项资源的相对路径。前导斜杠（“/”）会自动剪除。
run_at RunAt 可选。指定应将脚本注入网页的时间。默认为 document_idle。
match_about_blank 布尔值 boolean 可选。脚本是否应注入到 about:blank 帧中，其中父帧或起始帧与 matches 中声明的模式之一匹配。默认值为 false。
match_origin_as_fallback 布尔值 boolean 可选。脚本是否应在由匹配的来源创建但其网址或来源可能与模式不直接匹配的帧中注入。其中包括采用不同架构的帧，例如 about:、data:、blob: 和 filesystem:。
world ExecutionWorld 可选。要在其中执行脚本的 JavaScript 环境。默认值为 ISOLATED

1.1 RunAt

  • document_start

    • DOM 仍在加载。
  • document_end
    • 网页的资源仍在加载
  • document_idle
    • DOM 和资源已加载完毕。这是默认值。

1.2 ExecutionWorld

  • ISOLATED

    • 指定独立的世界，这是扩展程序独有的执行环境。
  • MAIN
    • 指定 DOM 的主环境，即与托管网页的 JavaScript 共享的执行环境。

2. 使用动态声明进行注入

如果内容脚本的匹配模式并不为人所知，或者内容脚本不应总是注入已知主机上，就需要使用动态进行注入。

内容脚本对象是使用 chrome.scripting 命名空间（而不是 manifest.json）中的方法在 Chrome 中注册的。

Scripting API 还允许扩展程序开发者执行以下操作：

  • 注册内容脚本。
  • 获取已注册内容脚本的列表。
  • 更新已注册内容脚本的列表。
  • 移除已注册的内容脚本。

动态声明可以包含 JavaScript 文件和或 CSS 文件。

service-worker.js

2.1. 注册

chrome.scripting

  .registerContentScripts([{

    id: "session-script",

    js: ["content.js"],

    persistAcrossSessions: false,

    matches: ["*://example.com/*"],

    runAt: "document_start",

  }])

  .then(() => console.log("registration complete"))

  .catch((err) => console.warn("unexpected error", err))

2.2. 更新

chrome.scripting

  .updateContentScripts([{

    id: "session-script",

    excludeMatches: ["*://admin.example.com/*"],

  }])

  .then(() => console.log("registration updated"));

2.3. 获取

chrome.scripting

  .getRegisteredContentScripts()

  .then(scripts => console.log("registered content scripts", scripts));

2.4. 移除

chrome.scripting

  .unregisterContentScripts({ ids: ["session-script"] })

  .then(() => console.log("un-registration complete"));

3. 以编程方式注入

对于需要为了响应事件或在特定情况下运行的内容脚本，使用程序化注入。

如需以编程方式注入内容脚本，扩展程序需要对要尝试注入脚本的页面拥有主机权限。可以通过在扩展程序清单中请求这些权限来授予主机权限，也可以通过 activeTab 暂时授予主机权限。

3.1. 内容文件作为脚本进行注入

manifest.json

{

  "name": "My extension",

  "permissions": [

    "activeTab",

    "scripting"

  ],

  "background": {

    "service_worker": "background.js"

  },

  "action": {

    "default_title": "Action Button"

  }

}

content-script.js

document.body.style.backgroundColor = "orange";

service-worker.js

chrome.action.onClicked.addListener((tab) => {

  chrome.scripting.executeScript({

    target: { tabId: tab.id },

    files: ["content-script.js"]

  });

});

3.2. 注入函数正文，并将其作为内容脚本执行。

service-worker.js

function injectedFunction() {

  document.body.style.backgroundColor = "orange";

}

chrome.action.onClicked.addListener((tab) => {

  chrome.scripting.executeScript({

    target : {tabId : tab.id},

    func : injectedFunction,

  });

});

3.3 注入函数时，可以传递参数

service-worker.js

function injectedFunction(color) {

  document.body.style.backgroundColor = color;

}

chrome.action.onClicked.addListener((tab) => {

  chrome.scripting.executeScript({

    target : {tabId : tab.id},

    func : injectedFunction,

    args : [ "orange" ],

  });

});

四、排除匹配项和 glob

如需自定义指定的网页匹配，请在声明式注册中添加以下字段

名称 类型 说明
exclude_matches 字符串数组 string[] 可选。不包括此内容脚本将被注入的网页。
include_globs 字符串数组 string[] 可选。在 matches 之后应用，以仅包含也与此 glob 匹配的网址。
exclude_globs 字符串数组 string[] 可选。在 matches 之后应用，以排除与此 glob 匹配的网址。

1. 排除/包含匹配

如果同时满足以下两个条件，内容脚本将会注入到网页中：

  • 其网址与任何 matches 格式和 include_globs 格式匹配。
  • 该网址也不符合 exclude_matches 或 exclude_globs 格式。由于 matches 属性是必需的，因此 exclude_matches、include_globs 和 exclude_globs 只能用于限制哪些页面会受到影响。

1.1. 示例

以下扩展程序会将内容脚本注入 https://www.nytimes.com/health，但不会注入 https://www.nytimes.com/business。

manifest.json

{

  "name": "My extension",

  "content_scripts": [

    {

      "matches": ["https://*.nytimes.com/*"],

      "exclude_matches": ["*://*/*business*"],

      "js": ["contentScript.js"]

    }

  ],

}

service-worker.js

chrome.scripting.registerContentScripts([{

  id : "test",

  matches : [ "https://*.nytimes.com/*" ],

  excludeMatches : [ "*://*/*business*" ],

  js : [ "contentScript.js" ],

}]);

2. Glob 匹配

Glob 属性遵循与匹配模式不同且更灵活的语法。可接受的 glob 字符串是指可能包含通配符和问号的网址。

  • 星号 (*) 匹配任何长度的字符串，包括空字符串
  • 问号 (?) 匹配任何单个字符。

例如，glob https://???.example.com/foo/* 与以下任何一项匹配：

  • https://www.example.com/foo/bar
  • https://the.example.com/foo/

不过，它与以下内容不匹配：

  • https://my.example.com/foo/bar
  • https://example.com/foo/
  • https://www.example.com/foo

2.1 示例

  1. 此扩展程序会将内容脚本注入 https://www.nytimes.com/arts/index.html 和 https://www.nytimes.com/jobs/index.htm*，但不会注入 https://www.nytimes.com/sports/index.html：

manifest.json

{

  "name": "My extension",

  "content_scripts": [

    {

      "matches": ["https://*.nytimes.com/*"],

      "include_globs": ["*nytimes.com/???s/*"],

      "js": ["contentScript.js"]

    }

  ],

}
  1. 此扩展程序会将内容脚本注入 https://history.nytimes.com 和 https://.nytimes.com/history，但不会注入 https://science.nytimes.com 或 https://www.nytimes.com/science：

manifest.json

{

  "name": "My extension",

  "content_scripts": [

    {

      "matches": ["https://*.nytimes.com/*"],

      "exclude_globs": ["*science*"],

      "js": ["contentScript.js"]

    }

  ],

}
  1. 全部参数都加上

此扩展程序会将内容脚本注入 https://www.example.com/arts/index.html

和 https://.example.com/jobs/index.html，但不会注入 https://science.example.com、https://www.example.com/jobs/business 和 https://www.example.com/science

manifest.json

{

  "content_scripts": [

    {

      "matches": ["https://*.example.com/*"],

      "exclude_matches": ["*://*/*business*"],

      "include_globs": ["*example.com/???s/*"],

      "exclude_globs": ["*science*"],

      "js": ["content-script.js"]

    }

  ],

}

五、运行时间

run_at 字段用于控制何时将 JavaScript 文件注入网页。首选值为 "document_idle"。

manifest.json

{

  "name": "My extension",

  "content_scripts": [

    {

      "matches": ["https://*.nytimes.com/*"],

      "run_at": "document_idle",

      "js": ["contentScript.js"]

    }

  ],

}

service-worker.js

chrome.scripting.registerContentScripts([{

  id : "test",

  matches : [ "https://*.nytimes.com/*" ],

  runAt : "document_idle",

  js : [ "contentScript.js" ],

}]);

六、允许运行的 iframe

"all_frames" 字段允许该扩展程序指定将 JavaScript 和 CSS 文件注入到符合指定网址要求的所有框架中，还是仅注入标签页中最顶层的框架。

manifest.json

{

  "name": "My extension",

  ...

  "content_scripts": [

    {

      "matches": ["https://*.nytimes.com/*"],

      "all_frames": true,

      "js": ["contentScript.js"]

    }

  ],

  ...

}

service-worker.js

chrome.scripting.registerContentScripts([{

  id: "test",

  matches : [ "https://*.nytimes.com/*" ],

  allFrames : true,

  js : [ "contentScript.js" ],

}]);
名称 类型 说明
all_frames 布尔值 boolean 可选。默认为 false，表示仅匹配顶部帧。 如果指定 true，所有帧都将注入到，即使帧不是标签页中的最顶层帧也是如此。系统会单独检查每个帧是否符合网址要求。如果不符合网址要求，则不会注入子框架。

七、通信

虽然内容脚本的执行环境和托管它们的页面彼此隔离，但它们共享对页面 DOM 的访问权限。如果网页希望通过内容脚本与内容脚本或扩展程序进行通信，则必须通过共享 DOM 来实现。

可以使用 window.postMessage()

content-script.js

var port = chrome.runtime.connect();

window.addEventListener("message", (event) => {

  // We only accept messages from ourselves

  if (event.source !== window) {

    return;

  }

  if (event.data.type && (event.data.type === "FROM_PAGE")) {

    console.log("Content script received: " + event.data.text);

    port.postMessage(event.data.text);

  }

}, false);

example.js

document.getElementById("theButton").addEventListener("click", () => {

  window.postMessage(

      {type : "FROM_PAGE", text : "Hello from the webpage!"}, "*");

}, false);

非扩展程序网页 example.html 向自身发布消息。内容脚本拦截和检查此消息，然后发布到扩展程序进程。通过这种方式，页面就能与扩展进程建立通信连接。反之亦然。

八、访问扩展程序文件

如需从内容脚本访问扩展程序文件，可以调用 chrome.runtime.getURL() 来获取扩展程序资源的绝对网址。

content-script.js

let image = chrome.runtime.getURL("images/my_image.png")

如需在 CSS 文件中使用字体或图片，可以使用 @@extension_id 构建网址，如以下示例所示 (content.css)：

content.css

body {

 background-image:url('chrome-extension://__MSG_@@extension_id__/background.png');

}

@font-face {

 font-family: 'Stint Ultra Expanded';

 font-style: normal;

 font-weight: 400;

 src: url('chrome-extension://__MSG_@@extension_id__/fonts/Stint Ultra Expanded.woff') format('woff');

}

所有资源都必须在 manifest.json 文件中声明为网络可访问资源：

manifest.json

{

 "web_accessible_resources": [

   {

     "resources": [ "images/*.png" ],

     "matches": [ "https://example.com/*" ]

   },

   {

     "resources": [ "fonts/*.woff" ],

     "matches": [ "https://example.com/*" ]

   }

 ],

}

九、禁止事项

1. Eval()

以下为 Manifest V3 禁止使用案例

content-script.js

const data = document.getElementById("json-data");

// WARNING! Might be evaluating an evil script!

const parsed = eval("(" + data + ")");

2. 字符串拼接函数

以下为 Manifest V3 禁止使用案例

content-script.js

const elmt_id = "...";

window.setTimeout("animate(" + elmt_id + ")", 200);

引用

Chrome 插件 V3 版本 Manifest.json 中的内容脚本（Content Scripts）解析的更多相关文章

  1. Chrome插件开发之manifest.json

    广而告之: Chrome插件之一键保存网页为PDF1.1发布 http://www.cnblogs.com/bdstjk/p/3179543.html 最近做“一键保存网页为PDF”过程中,对Chro ...

  2. maven-bundle-plugin 2.4.0以下版本导出META-INF中的内容到MANIFEST.MF中

    今天终于把maven-bundle-plugin不能导出META-INF中的内容到Export-Package中的问题解决了,因为用到的第三方JAR包需要加载META-INF/XX/XX.xml这个内 ...

  3. Chrome插件（Extensions）开发攻略

    本文将从个人经验出发,讲述为什么需要Chrome插件,如何开发,如何调试,到哪里找资料,会遇到怎样的问题以及如何解决等,同时给出一个个人认为的比较典型的例子——获取网页内容,和服务器交互,再把信息反馈 ...

  4. 【干货】Chrome插件(扩展)开发全攻略(不点进来看看你肯定后悔)

    写在前面 我花了将近一个多月的时间断断续续写下这篇博文,并精心写下完整demo,写博客的辛苦大家懂的,所以转载务必保留出处.本文所有涉及到的大部分代码均在这个demo里面:https://github ...

  5. 【干货】Chrome插件(扩展)开发全攻略

    写在前面 我花了将近一个多月的时间断断续续写下这篇博文,并精心写下完整demo,写博客的辛苦大家懂的,所以转载务必保留出处.本文所有涉及到的大部分代码均在这个demo里面:https://github ...

  6. chrome插件编写基本入门

    chrome插件编写基本入门  http://igeekbar.com/igeekbar/post/331.htm #精选JAVASCRIPTCHROME 作为一名程序猿,怎么能不会写chrome插件 ...

  7. Chrome插件(扩展)

    [干货]Chrome插件(扩展)开发全攻略   写在前面 我花了将近一个多月的时间断断续续写下这篇博文,并精心写下完整demo,写博客的辛苦大家懂的,所以转载务必保留出处.本文所有涉及到的大部分代码均 ...

  8. 【干货】Chrome插件(扩展)开发全攻略（转）

    写在前面 我花了将近一个多月的时间断断续续写下这篇博文,并精心写下完整demo,写博客的辛苦大家懂的,所以转载务必保留出处.本文所有涉及到的大部分代码均在这个demo里面:https://github ...

  9. 能说会道爱办公——“别人家的”Chrome插件到底怎么做

    根据相关数据显示,谷歌的Chrome浏览器目前已达近七成的市场占有率,成为浏览器的"霸主".大家选择Chrome,除了是因为性能的优越以及强大的兼容性之外,Chrome充足的扩展插 ...

  10. 利用chrome插件批量读取浏览器页面内容并写入数据库

    试想一下,如果每天要收集100页网页数据甚至更多.如果采用人工收集会吐血,用程序去收集也就成为一个不二的选择.首先肯定会想到说用java.php.C#等高级语言,但这偏偏又有个登陆和验证码,搞到无所适 ...

随机推荐

  1. 为 Hugging Face 用户带来无服务器 GPU 推理服务

    今天,我们非常兴奋地宣布 部署到 Cloudflare Workers AI 功能正式上线,这是 Hugging Face Hub 平台上的一项新服务,它使得通过 Cloudflare 边缘数据中心部 ...

  2. 阿里开源的32B大模型到底强在哪里？

    阿里巴巴最近开源了一个320亿参数的大语言模型Qwen1.5-32B,网上都说很强很强,那么它到底强在哪里呢? 更高的性价比 Qwen1.5-32B中的B是billion的意思,也就是10亿,32B就 ...

  3. openGauss2.1.0新特性-账本数据库实验

    openGauss2.1.0 新特性-账本数据库实验 账本数据库融合了区块链思想,将用户操作记录至两种历史表中:用户历史表和全局区块表.当用户创建防篡改用户表时,系统将自动为该表添加一个 hash 列 ...

  4. 基于pdfbox实现的pdf添加文字水印工具

    简述 最近有个需求需要给pdf加文字水印,于是开始搜索大法,但是发现网络上的代码基本都是将字体文件直接放在jar包里面.个人强迫症发作(手动狗头),想要像poi一样直接加载系统字体,于是研究了一下午p ...

  5. HarmonyOS实现几种常见图片点击效果

    一. 样例介绍 HarmonyOS提供了常用的图片.图片帧动画播放器组件,开发者可以根据实际场景和开发需求,实现不同的界面交互效果,包括:点击阴影效果.点击切换状态.点击动画效果.点击切换动效. 相关 ...

  6. gitlib配置

    第1步:下载Java并安装Java.一般来说下载jdk对应的版本就行. 第2步:配置Java环境变量,具体如下: 1. 新建:变量名:JAVA_HOME:变量值:C:\Program Files\Ja ...

  7. webpack 打包jquery

    前言 记一次配置webpack jqeury中的案例. 正文 选取自己需要安装的jquery版本号 dependencies:{ //此处的jquery版本根据npm后的版本来看,会有安装版本的提示 ...

  8. python数据库迁移

    实际操作命令 1,python 文件.py db init 2,python xx.py db migrate -m '版本描述' 3,python xx.py db upgrade 4,python ...

  9. Locust、Jemter、Loadrunner三种工具的分布式压测

    前言: 最近公司接了一个云上展会项目,合同里签订的是6w并发连接数和2w QPS的性能指标,还有监理单位,第三方评测单位. 唉,先吐槽一下,有了监理和评测,文档tmd一堆堆,严格按照软件开发来执行,写 ...

  10. vscode下的超级慢的解决方法

    vscode下的超级慢的解决方法 从网上看到的方法,记录给自己看 vscode官网:https://code.visualstudio.com/Download 复制下载链接 链接如下: https: ...