網頁擴充功能

Web Extensions 是一組 API，用於建立跨瀏覽器運作的瀏覽器擴充功能。Parcel 支援使用 @parcel/config-webextension 建立 Web Extensions。

開始使用

首先，將 @parcel/config-webextension 安裝到您的專案中

yarn add @parcel/config-webextension --dev

接下來，您需要一個 manifest.json 檔案，這將會是您的擴充功能的進入點。有關如何設定的詳細資訊，請參閱此指南。Manifest V2 和 V3 都受支援。您可以在 Web 擴充功能程式碼中使用 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 會提供最終的 Web 擴充功能套件，準備好發布。壓縮輸出目錄後，您應該可以將檔案上傳到您選擇的平台，例如 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 中指定檔案路徑或 glob。請注意，Parcel 會將 web_accessible_resources 中的項目視為 Unix glob（例如，examples/*.png 會擷取範例資料夾中的每個 PNG，而 examples/**.png 會遞迴執行）。這與 Chrome 中的 glob 不同，後者總是遞迴執行。