开发Chrome扩展程序，核心manifest 文件

开发Chrome扩展程序，核心manifest 文件（上） 

大家好，我是dom哥。我正在写关于 Chrome 扩展开发的系列文章，感兴趣的可以点个小星星。

Chrome 在全球浏览器市场份额独占 6 成，无论是对普通用户还是开发者，都是电脑里的必备利器。Chrome 无论是在性能还是 UI 交互方面都非常出色，而 Chrome 扩展则为开发者提供了接口，让开发者有能力自己编写代码使自己的 Chrome 更强大，更加定制化。

每个 Chrome 扩展项目的根目录中都必须有一个 manifest.json 文件，即清单文件。manifest 里会记录关于扩展的重要元数据、声明权限以及指定在网页和后台中运行的文件等等。

最简单的 Chrome 扩展项目

新建一个 crx-demo 目录，在里面新建一个 manifest.json 文件，目录结构如下：

crx-demo
└── manifest.json

这就是一个最简单的 Chrome 扩展项目了！接下来就是不断丰富它的细节。

manifest 字段最小集

manifest 大约有 20 多个配置项，但大部分都是可选配置。必须的配置项有且仅有下面 3 个！

{
  "manifest_version": 3,
  "name": "CRX Demo",
  "version": "1.0.0"
}

是不是似曾相识，像不像前端项目里无人不知的 package.json 文件！

先不用追究每个字段的深层含义，这个稍后会逐个解释。接下来在 Chrome 里打开管理扩展程序 chrome://extensions/ 直接把 crx-demo 拽过来扔进去。或者你也可以 加载已解压的扩展程序。

在扩展程序里就能看到这个扩展了🎉

扩展第一版

manifest 支持配置的字段

必须的字段

"manifest_version"

指定 manifest 的版本。不同的版本支持的配置字段不一样，格式也不一样，之前是 2，现在是 3，将来会是 4。区别有点像通信领域的 3G，4G，5G 概念。

"manifest_version": 3

V2 版本的扩展 Chrome 在2024年6月份会停止支持，届时 V2 版本的扩展将无法加载。将来可能会迭代到 V4 版本，但官方尚没有消息。因此目前及未来很长时间将都是 V3 版本的 Chrome 扩展。

"name"

扩展名字。**没啥好说的。有长度限制，最多 45 个字。

"name": "your extension name"

"version"

扩展的迭代版本。这个迭代版本的格式很有讲究，不同于 package.json 里的 version 那般随意。

这里 version 的格式和 IP 地址倒是很像。要求如下：

  • 最少 1 个最多 4 个整数用点号连接而成
  • 每部分整数值域为 0-65535

下面是一些支持使用的版本示例：

"version": "1"
"version": "1.0"
"version": "2.10.2"
"version": "3.1.2.4567"

之所以这样设计，是为了方便 Chrome 扩展的自动更新。

推荐的字段

"description"

扩展的描述。一个好的描述是成功推销的第一步。最多 132 个字。

"description": "扩展的描述"

"icons"

扩展的图标。一图胜万言。

"icons": {
  "48": "icon48.png",
  "128": "icon128.png"
}

官方建议至少应该提供 128x128 和 48x48 两个尺寸的图标。128x128 的用于 Chrome Web Store，48x48 的用于管理扩展页面(chrome://extensions)。

值得注意的是，不支持使用 WebP 和 SVG 格式的图标。其他的格式 PNG，JPEG，GIF，ICO，BMP 都是支持的！

继续完善细节，给 manifest.json 加上 "description" 和 "icons" 字段

+ "description": "扩展的描述"
+ "icons": {
+   "48": "icon48.png",
+   "128": "icon128.png"
+ }

在 chrome://extensions 刷新扩展，可以看到已经变成了这个样子：

扩展第二版

值得一提的是，"description" 和 "icons" 是你往 Chrome Web Store 发布扩展时必填的两个字段！

可选的字段

到目前为止，这个扩展还没有任何用处 😅，只是看上去有了点雏形。

在下一篇将详细介绍 manifest 几个强大的可选项，它们将为 Chrome 扩展注入灵魂：

  • "content_scripts": 向 web 页面注入 JavaScript 和 CSS。
  • "background": 以 service worker 形式运行后台服务。
  • "permissions": 权限管理，有些功能需要用户授权才能获得。

觉得不错可以点个小星星支持一下🌹

 

【出处】：https://www.cnblogs.com/iovec/p/manifest.html

=======================================================================================

Chrome扩展的核心：manifest 文件（中）

合集 - Chrome扩展开发完全指南(3)
 
1.Chrome扩展的核心：manifest 文件（上）12-13
2.Chrome扩展的核心：manifest 文件（中）12-14
3.Chrome扩展开发实战：快速填充表单12-15
收起
 

大家好，我是 dom 哥。我正在写关于 Chrome 扩展开发的系列文章，感兴趣的可以 点个小星星 。

在上一篇中已经完成了 Chrome 扩展的雏形，本篇接着介绍 manifest 中的可选字段，完善扩展的细节。

manifest 中的可选字段

"content_scripts"

向 web 页面注入 JavaScript 和 CSS。可以说这是 Chrome 扩展的灵魂。当指定 content_scripts 后，每当页面加载时，content_scripts 也将随之加载。

"content_scripts": [
   {
     "css": ["content-style.css"],
     "js": ["content-script.js"],
     "matches": ["<all_urls>"],
     "run_at": "document_idle", // optional
     "world": "ISOLATED" // optional
   }
 ]

content_scripts 里的配置项解释：

  • "css"：指定注入的 css 样式文件
  • "js"：指定注入的 js 脚本文件

值得注意的是，css 和 js 指定的文件路径必须是相对路径！总是相对于扩展根目录！

  • "matches"：用于指定往哪些页面注入 css 和 js，必填项。

    其值并非普通的 url，而是满足如下结构的匹配模式。

    <scheme>://<host>/<path>

    • scheme：指明协议格式，只能是以下几种

      • http
      • https
      • 通配符 *, 表示 http 或 https
      • file

    • host：指明主机名。支持通配符 *，但有限制，通配符 * 的屁股后面必须跟 . 或 /！也就是只有以下两种使用方式

      • *.example.com 匹配子域
      • */ 匹配所有域

    • path：指明匹配的网址路径。/* 表示匹配所有路径。

    特殊 case： "<all_urls>" 匹配所有页面！一般，额，简单粗暴，就用这个😅！

  • "run_at"：脚本注入时机。默认情况下，扩展会在页面处于空闲状态时注入 css 和 js。有以下3个时机可供选择：

    • document_start 页面 html 开始加载前就注入。此时 DOM 树还未建立！
    • document_end window DOMContentLoaded 事件触发后注入。此时 DOM 树已建立，但图片，字体，脚本等资源尚未加载完毕。
    • document_idle 当页面空闲时注入。这也是默认的注入时机！浏览器会在 document_end 和 window.onload 触发前这个时间段内选择时机注入，具体注入时机取决于页面的复杂程度。

    下面这张图片可以直观的看出注入时机和页面加载状态的先后时间顺序。🟥 红色字是页面内脚本打印，🟩 绿色字是扩展 content-script 打印。

  • "world"：content-script 的脚本执行环境。默认情况下，content-script 运行在一个隔离的沙箱环境中。这意味着和页面的运行时环境是隔离开来的两个独立环境，最明显的表现就是两个环境里的 全局变量 window 不通。该字段有以下2个选择：

    • ISOLATED 隔离沙箱环境。这也是默认的 content-script 执行环境。
    • MAIN 页面运行时环境。这意味者扩展脚本和页面脚本共享运行时，同一个 window，同一个世界，同一个梦想。

    理解两者的不同非常重要！假设页面上的 js 给 window 对象增加了一个 customVariable 全局变量，

    <head>
  <script>
    window.customVariable = "window.customVariable"
  </script>
</head>

    下面是扩展的 content-script 在 ISOLATED 和 MAIN 两个不同的环境中打印 window.customVariable 变量的结果：

    可以发现 ISOLATED 隔离环境访问不到 window.customVariable，值是 undefined，而 MAIN 环境则能访问到！

    我画了一张图，以便直观的展示 ISOLATED 和 MAIN 执行环境的区别

"background"

注册一个 service worker 作为后台服务。"content_scripts" 是页面级别的脚本，运行于前台页面，随页面销毁。"background" 是浏览器级别的服务，可以长期运行于后台，但事情也并没有那么简单，Chrome 扩展的 service worker 会在需要时自动加载，在闲置时自动休眠。

作为后台服务，service worker 的主要用途是注册事件监听，响应各种事件，比如网络请求，content_scripts 传来的 message 等等。Chrome 扩展提供了大量 chrome.* 接口可供使用，这些接口大多都能在 "background" 中使用，但 "content_scripts" 只能使用其中的少数，这是为安全起见故意设计的。

"background": {
  "service_worker": "service-worker.js",
  "type": "module"
}

不同于 "content_scripts" 可以用数组指定多个，"background" 只支持设置一个。

  • type：指明支不支持 ES Modules，只有 module 一个值，加上就支持 import，不加上就不支持！

配置完 "background" 后在扩展管理里更新扩展，就能看到注册的 Service Worker 啦！

当 service worker 闲置时，它会自动休眠，显示为无效。如下图所示：

background-dim.jpg

"permissions"

明确申明你的扩展需要用到哪些特殊的扩展 APIs，就像手机 App 询问网络权限，位置权限，照片权限等等。权限和 API 绑定，每个权限被授权后都将解锁一批 API。有些权限只需要申明，浏览器就会授予权限，而有些权限还将展示警示弹窗需要用户明确授权才行。

举几个例子：

  • "webRequest"，获得访问 chrome.webRequest API，可以监控所有网络流量。
  • "cookies"，获得访问 chrome.cookies API，可以操作网站 cookie
  • "bookmarks"，获得访问 chrome.bookmarks API，可以读写管理书签
  • "desktopCapture"，获得访问 chrome.desktopCapture API，可以进行窗口或页面的截图
  • "downloads"，获得访问 chrome.downloads API，可以操作和管理浏览器下载

截至目前，crx-demo 项目的目录结构如下：

crx-demo
├── background
│   ├── service-worker.js
│   └── sub.js
├── content-scripts
│   ├── document_end.css
│   ├── document_end.js
│   ├── document_idle.css
│   ├── document_idle.js
│   ├── document_idle_main.js
│   ├── document_start.css
│   └── document_start.js
├── icon128.png
├── icon48.png
└── manifest.json

已经可以在 content-script 和 background 里任意编写代码来实现自己匪夷所思的奇思妙想啦！

crx-demo 项目已经放在 github 上啦，后续会继续更新丰富细节。

本篇就介绍到这里，下篇接着将把剩余的 manifest 重要选项整理完。

觉得不错可以 点个小星星 支持一下🌹

 

【出处】：https://www.cnblogs.com/iovec/p/manifest2.html

=======================================================================================

Chrome扩展的核心：manifest 文件（下） 

合集 - Chrome扩展开发完全指南(7)
 
1.Chrome扩展开发系列开篇12-192.Chrome扩展的核心：manifest 文件（上）12-133.Chrome扩展的核心：manifest 文件（中）12-14
4.Chrome扩展的核心：manifest 文件（下）12-16
5.Chrome扩展开发实战：快速填充表单12-156.打造一个极度舒适的Chrome扩展项目开发环境 🚀12-177.推荐给前端开发的 5 款 Chrome 扩展 🚀12-18
收起
 

大家好，我是 dom 哥。这是我关于 Chrome 扩展开发的系列文章，感兴趣的可以 点个小星星。

在上篇和中篇中已经完成了对 manifest 文件中以下字段的解释：

  • "manifest_version"
  • "name"
  • "version"
  • "description"
  • "icons"
  • "content_scripts"
  • "background"
  • "permissions"

本篇接着说剩下的 manifest 可选字段。

UI 配置

"action"

定义 Chrome 右上角工具栏上扩展 icon 按钮的 UI 和行为。

"action": {
  "default_popup": "popup/index.html",  // optional
  "default_title": "Click Me",    // optional, shown in tooltip
  "default_icon": {               // optional
    "16": "images/icon16.png",    // optional
    "24": "images/icon24.png",    // optional
    "32": "images/icon32.png"     // optional
  }
},

  • default_popup：当用户点击右上角扩展按钮时展示的弹窗。是一个普通的 html 文件。弹窗的大小被限制在 25x25 至 800x600 之间。
    在 crx-demo 根目录下新建一个 html 文件 popup/index.html

    <!DOCTYPE html>
<html>
  <head> </head>
  <body style="min-width: 300px;min-height: 400px;">
    <img src="../icon128.png" />
    <h1>crx-demo1</h1>
  </body>
</html>

    更新 manifest.json 文件

    + "action": {
+   "default_popup": "popup/index.html"
+ }

    在 chrome://extensions 更新以下扩展，就能看到效果啦

  • default_title：鼠标悬浮在扩展按钮上展现的 tooltip。

  • default_icon：设置扩展按钮的图标，如果不设置的话，默认是用 "icons" 里面设置的图标。

    这是我设置了 default_title 和 default_icon 之后的效果：

"devtools_page"

在 Chrome DevTools 开发者工具中增加一个新的面板。像 Vue.js devtools 和 React Developer Tools 这两个扩展都是 devtools_page。

"devtools_page": "devtools/index.html"

在每次开发者工具打开时 devtools_page 配置的 html 都将以 iframe 的形式加载。但注意，devtools_page 配置的 html 并不会展现在 DevTools 的 UI 界面。它的主要作用是用于加载所需要的 JavaScript 文件。

设置 devtools/index.html 的内容如下：

<script src="./index.js"></script>

没错！什么也不需要，只需要一个 script 标签！

从下图可以看出，装载 devtools_page 的 iframe 被设置了 display: none

需要在 devtools/index.js 里调用 chrome.devtools.* API 来创建 DevTools 面板：

chrome.devtools.panels.create("My Devtools Panel", "", "devtools/panel.html")

没错！就这一行！此时 crx-demo/devtools 目录的结构如下：

devtools
├── index.html
├── index.js
└── panel.html

有必要说说 chrome.devtools.panels.create 的参数，

chrome.devtools.panels.create(title, iconPath, pagePath)

  • title： DevTools 工具栏上展示的名字，类似 Elements，Console，Network，Application 这些。

  • iconPath：title 左边配置一个小 icon，但但但！实际上 Chrome 会忽略这个参数！ 也就是根本设置不了小 icon，这个参数是废的，写死空字符串忽略就行啦。

  • pagePath：这个才是真正的 DevTools 面板要显示的 HTML 页面，值得注意的是，这个路径是相对于扩展根目录的。它将以 iframe 的形式加载，如下图所示：

"side_panel"

在 Chrome 侧边栏配置一个新的页面。侧边栏是浏览器级别的，常驻右侧。

值得注意的是，要求在 "permissions" 声明 sidePanel 权限：

"permissions": [
  "sidePanel"
]
"side_panel": {
  "default_path": "side_panel/index.html"
}

side_panel 页面里可以使用所有 chrome.* API，尽情驰骋吧～

"options_page"

配置一个扩展选项页，供用户自定义扩展的功能选项。

"options_page": "options_page/index.html"

配置完之后会多出来两个入口，一个是右上角 action 按钮右键里的选项：

另一个是扩展详情页里的扩展程序选项：

点击之后实际上就是新开一个浏览器页面打开扩展里的静态页面：

"chrome_url_overrides"

重写一些默认的 Chrome 页面。

"chrome_url_overrides" : {
  "PAGE_TO_OVERRIDE": "myPage.html"
}

PAGE_TO_OVERRIDE 的取值须为下列之一，也是目前支持重写的页面：

  • newtab：新标签页。即 chrome://newtab

  • history：浏览历史记录页面。即 chrome://history

  • bookmarks：书签管理页面。即 chrome://bookmarks

值得注意的是，一个扩展只允许重写一个页面，不能重写多个页面！

其他可选项

"declarative_net_request"

拦截和修改网络请求。 不同于 manifest V2 编程式的操作处理，V3 规定必须使用声明式的静态规则进行配置。

"commands"

定义全局快捷键。需要在 background service-worker 中监听并自定义处理逻辑。

chrome.commands.onCommand.addListener((command) => {
  console.log(`Command: ${command}`)
})

"web_accessible_resources"

声明扩展里可以被外部 Web 页面或其他扩展访问的资源。默认情况下扩展里的所有资源，包括 img，html，js，css 都不允许被外部访问，这是为了安全而刻意设计的。

"homepage_url"

指定关于该扩展的主页。默认是指向 Chrome 应用商店，当你的扩展没放到 Chrome 应用商店，而是放在自己的网站上时可以用这个字段指明。
入口在扩展的详情页，如下图所示：

"author"

指明扩展的作者。

"author": {
  "email": "user@example.com"
}

值得注意的是，当往 Chrome 应用商店发布时，manifest.json 里指定的 author.email 地址必须和发布账户的一样！

总结

本篇介绍了 manifest.json 里剩余的一些可配置项：

  • "action"
  • "devtools_page"
  • "side_panel"
  • "options_page"
  • "chrome_url_overrides"
  • "declarative_net_request"
  • "commands"
  • "web_accessible_resources"
  • "homepage_url"
  • "author"

至此，Chrome 扩展 manifest 里常用的配置项全部介绍整理完毕。

文中涉及的 crx-demo 项目代码已放在 GitHub。

觉得不错可以 点个小星星 支持一下 🌹

 

【出处】：https://www.cnblogs.com/iovec/p/manifest3.html

=======================================================================================

posted on 2023-12-13 19:39  jack_Meng  阅读(232)  评论(0)  编辑  收藏  举报

导航