在配置任何内容之前,我们需要了解 BEX 的结构。BEX 可以是以下一项(或多项):
不需要为每种 BEX 类型都创建一个新的 Quasar 应用,因为一个 Quasar 应用可以运行在上述所有场景中。更多信息请参考类型部分。
quasar.config 配置文件
// 如果您想更改默认文件路径
sourceFiles: {
bexManifestFile?: 'src-bex/manifest.json',
}bex: {
/**
* 不在 bex manifest 中但需要编译并在浏览器扩展中使用的额外脚本(js/ts)列表。
* 也许可以动态地使用它们?
*
* 列表中的每个条目应该是相对于 /src-bex/ 的文件名
*
* @example [ 'my-script.ts', 'sub-folder/my-other-script.js' ]
*/
extraScripts?: string[];
/**
* 扩展用于 bex 脚本(background、content scripts、dom script)的 Esbuild 配置
*/
extendBexScriptsConf?: (config: EsbuildConfiguration) => void;
/**
* 如果需要动态修改浏览器扩展的 manifest 文件
* (/src-bex/manifest.json),请使用此方法。
*/
extendBexManifestJson?: (json: object) => void;
}/src 中的 UI
如果您想修改 /src 中 UI 的 Webpack 配置,有两种方式:
build: {
extendWebpack(webpackCfg) { ... },
chainWebpack(webpackChain) { ... }
}在构建(或开发)浏览器扩展时,UI 文件会被注入并以 www 文件夹的形式提供。
Manifest.json
BEX 最重要的配置文件是 /src-bex/manifest.json。建议在开始项目之前先阅读该文件的说明文档。
当您首次添加 BEX 模式时,会注意到 manifest 文件包含三个根属性:all、chrome 和 firefox。Chrome 的 manifest 是通过 all + chrome 深度合并而来,Firefox 的则通过 all + firefox 生成。您甚至可以为每个目标设置不同的 manifest 版本:
{
"all": {
"manifest_version": 3,
"icons": {
"16": "icons/icon-16x16.png",
"48": "icons/icon-48x48.png",
"128": "icons/icon-128x128.png"
},
"permissions": ["storage", "tabs"],
"host_permissions": ["*://*/*"],
"content_security_policy": {
"extension_pages": "script-src 'self'; object-src 'self';"
},
"web_accessible_resources": [
{
"resources": ["*"],
"matches": ["*://*/*"]
}
],
"action": {
"default_popup": "www/index.html"
},
"content_scripts": [
{
"matches": ["<all_urls>"],
"css": ["assets/content.css"],
"js": ["my-content-script.ts"]
}
]
},
"chrome": {
"background": {
"service_worker": "background.ts"
}
},
"firefox": {
"background": {
"scripts": ["background.ts"]
}
}
}给 TS 开发者的提示
您的 background 和 content 脚本使用 .ts 扩展名,在 manifest.json 文件中也请使用相同的扩展名!例如:“background.ts”、“my-content-script.ts”。虽然浏览器厂商只支持 .js 扩展名,但 Quasar CLI 会自动转换文件扩展名。
后台脚本和内容脚本
每个 BEX 背后都有内容脚本和后台脚本(manifest v2)/ service-worker(manifest v3+)。建议在编写第一个 BEX 之前先了解它们各自的作用。
概述:
- 后台脚本 - 运行在 BEX 自身的上下文中,可以监听所有可用的浏览器扩展事件。
- 内容脚本 - 运行在网页的上下文中。每个运行扩展的选项卡都会有一个独立的内容脚本实例。
提示
由于内容脚本运行在网页上下文中,这意味着只有与网页交互的 BEX 才能使用内容脚本。弹窗、选项页和开发者工具中的 BEX 不会有内容脚本。不过,它们都会有后台脚本。
警告
在 Chrome 中使用 Manifest v3 时,您的后台脚本实际上是一个 Service Worker。目前 Firefox 的 Manifest v3 尚未采用这种方式。
CSS
任何您希望在网页中(而非 Quasar 应用中)使用的样式,都应以文件形式放在 src-bex/assets/<name>.css 中。添加此类文件时,请确保在 /src-bex/manifest.json 中将其关联到需要它的 content scripts:
// 示例:关联 /src-bex/assets/content.css
"content_scripts": [
{
"matches": [ "<all_urls>" ],
"css": [ "assets/content.css" ],
"js": [ /*...*/ ]
}
]警告
这必须是原生 CSS,因为它不会通过 Sass 进行预处理。
动态/其他脚本
如果您需要为 BEX 动态加载或编译其他脚本,可以在 quasar.config 文件中进行配置:
bex: {
/**
* 不在 bex manifest 中但需要编译并在浏览器扩展中使用的额外脚本(js/ts)列表。
* 也许可以动态地使用它们?
*
* 列表中的每个条目应该是相对于 /src-bex/ 的文件名
*
* @example [ 'my-script.ts', 'sub-folder/my-other-script.js' ]
*/
extraScripts?: string[];
}