为什么捐赠
API 浏览器
联系站长
Quasar CLI with Webpack - @quasar/app-webpack
配置 BEX

在配置任何内容之前,我们需要了解 BEX 的结构。BEX 可以是以下一项(或多项):

  1. 在浏览器中运行在自己的选项卡中
  2. 运行在开发者工具窗口中。
  3. 运行在一个弹窗中。
  4. 作为选项窗口运行。
  5. 在网页的上下文中运行(注入到网站中)。

不需要为每种 BEX 类型都创建一个新的 Quasar 应用,因为一个 Quasar 应用可以运行在上述所有场景中。更多信息请参考类型部分

quasar.config 配置文件

/quasar.config file > sourceFiles

// 如果您想更改默认文件路径
sourceFiles: {
  bexManifestFile?: 'src-bex/manifest.json',
}
/quasar.config file > bex

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 配置,有两种方式:

/quasar.config file

build: {
  extendWebpack(webpackCfg) { ... },
  chainWebpack(webpackChain) { ... }
}

在构建(或开发)浏览器扩展时,UI 文件会被注入并以 www 文件夹的形式提供。

Manifest.json

BEX 最重要的配置文件是 /src-bex/manifest.json。建议在开始项目之前先阅读该文件的说明文档

当您首次添加 BEX 模式时,会注意到 manifest 文件包含三个根属性:allchromefirefox。Chrome 的 manifest 是通过 all + chrome 深度合并而来,Firefox 的则通过 all + firefox 生成。您甚至可以为每个目标设置不同的 manifest 版本:

/src-bex/manifest.json

{
  "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/manifest.json

// 示例:关联 /src-bex/assets/content.css
"content_scripts": [
  {
    "matches": [ "<all_urls>" ],
    "css": [ "assets/content.css" ],
    "js": [ /*...*/ ]
  }
]

警告

这必须是原生 CSS,因为它不会通过 Sass 进行预处理。

动态/其他脚本

如果您需要为 BEX 动态加载或编译其他脚本,可以在 quasar.config 文件中进行配置:

/quasar.config file

bex: {
  /**
   * 不在 bex manifest 中但需要编译并在浏览器扩展中使用的额外脚本(js/ts)列表。
   * 也许可以动态地使用它们?
   *
   * 列表中的每个条目应该是相对于 /src-bex/ 的文件名
   *
   * @example [ 'my-script.ts', 'sub-folder/my-other-script.js' ]
   */
  extraScripts?: string[];
}