网页扩展

网页扩展是一组用于构建跨多个浏览器工作的浏览器扩展的 API。Parcel 支持使用 @parcel/config-webextension 构建网页扩展。

入门

首先，将 @parcel/config-webextension 安装到您的项目中

yarn add @parcel/config-webextension --dev

接下来，您需要一个 manifest.json 文件，它将作为您的扩展的入口点。有关如何设置它的详细信息，请参阅本指南。Manifest V2 和 V3 都受支持。您可以在网页扩展代码中使用 TypeScript、Vue 和 Parcel 支持的任何其他语言。

manifest.json

{
  "manifest_version": 3,
  "name": "Sample Web Extension",
  "version": "0.0.1",
  "background": {
    "service_worker": "background.ts",
    "type": "module"
  },
  "content_scripts": [{
    "matches": ["*://github.com/parcel-bundler/*"],
    "js": ["parcel-content-script.ts"]
  }]
}

要构建您的扩展，请使用您的 manifest.json 作为入口点，并使用 @parcel/config-webextension 作为配置运行 Parcel

parcel build manifest.json --config @parcel/config-webextension

您也可以在项目中创建一个 .parcelrc 文件，扩展 @parcel/config-webextension。这样，您就不需要每次都将 --config 选项传递给 Parcel CLI。

.parcelrc

{
  "extends": "@parcel/config-webextension"
}

HMR

由于 MV3 中对内容安全策略的限制，HMR 不受支持，但更新您的代码将导致扩展重新加载。对于 MV2，HMR 默认情况下完全受支持。重新加载包含内容脚本的页面将在两个版本中重新加载扩展。

为了获得最佳的开发体验，请在开发构建中使用 --host localhost（这有时对于内容脚本重新加载是必要的）。您可以复制以下配置

package.json

{
  "scripts": {
    "start": "parcel watch src/manifest.json --host localhost --config @parcel/config-webextension",
    "build": "parcel build src/manifest.json --config @parcel/config-webextension"
  }
}

运行 yarn start 或 npm start 将启动开发服务器。源映射和 HMR 将适用于后台脚本、弹出页面和选项页面。对于 MV2，HMR 通常也适用于内容脚本。

要将扩展添加到您的浏览器，请加载 Parcel 的输出文件夹（未打包）。例如，在 Chrome 中，在 chrome://extensions 页面中单击“加载未打包”，然后选择 path/to/project/dist。

运行 yarn build 或 npm run build 将为您提供最终的网页扩展包，准备发布。将输出目录压缩后，您应该能够将文件上传到您选择的平台，例如 Chrome 网上应用店。

特殊注意事项

意外消息

在开发模式下，您的后台脚本将在每次内容脚本页面重新加载时收到一个包含内容 { __parcel_hmr_reload__: true } 的消息事件。Parcel 将自动使用它在必要时刷新扩展。因此，您需要确保在处理任何后台脚本接收到的消息之前，这些消息不包含 __parcel_hmr_reload__ 属性。

样式

在内容脚本中导入的任何样式都将被注入到该内容脚本的 css 属性中，因此将应用于整个页面。通常这是您想要的，但如果不是，您始终可以使用 CSS 模块来防止样式应用于原始站点。

此外，内容脚本 CSS 会解析链接到其注入的站点的链接，因此您将无法引用本地资产。您应该内联您的包来解决此问题。

content-script.css

.my-class {
  /* Equivalent to: https://injected-site.com/custom-bg.png */
  /* This is probably not what you want! */
  background-image: url(./custom-bg.png);
}

.my-other-class {
  /* This will use the local file custom-bg.png */
  background-image: url(data-url:./custom-bg.png);
}

最后，在从内容脚本中的 import() 中添加或删除链接的 CSS 时，热重载可能无法正常工作，而同步 import 则没有此问题。这是一个已知限制，将在未来版本中修复。

`web_accessible_resources`

您在内容脚本中使用的任何资源都将自动添加到 web_accessible_resources 中，因此您通常不需要在 web_accessible_resources 中指定任何内容。例如，以下内容脚本将正常工作

content-script.js

import myImage from 'url:./image.png';

const injectedImage = document.createElement('img');
injectedImage.src = myImage;
document.body.appendChild(injectedImage);

但是，如果您确实希望扩展中的资源可供其他扩展或网站访问，您可以在 web_accessible_resources 中指定文件路径或通配符。请注意，Parcel 将 web_accessible_resources 中的条目视为 Unix 通配符（例如，examples/*.png 将检索 examples 文件夹中的所有 PNG，而 examples/**.png 将递归地执行此操作）。这与 Chrome 中的通配符不同，Chrome 中的通配符始终是递归的。