跳轉到主要內容
把擴充功能圖示宣告在可被 Extension.js 驗證、改寫並可預期輸出的 manifest 欄位中,藉此維持擴充功能品牌與 action UI 的一致性。 Extension.js 會處理 manifest.json 中的圖示路徑、解析 public/相對路徑、輸出圖示資產,並在開發期間監看圖示檔案。

範本範例

action

action template screenshot 在 manifest.json 中宣告工具列圖示的 action 擴充功能。
儲存庫:extension-js/templates/action

圖示能力

支援的圖示欄位

Chromium 不接受 .svg(或 .webp)作為 icons 與 action 圖示。把這些欄位指向 SVG 的 manifest 能在 Firefox 中載入,但在 Chrome、Edge、Brave 與 Opera 中會失敗。 針對所有 Chromium 目標請提供 PNG 檔案。sidebar_action 與 browser_action.theme_icons 是 Firefox 欄位,而且 sidebar_action.default_icon 對 .svg 的支援在那裡也只是部分的(*)。

在 manifest.json 中宣告圖示的範例

圖示變體

icon_variants 為每種配色方案宣告一組圖示。Extension.js 會讀取頂層的這個鍵,以及 action、browser_action 與 page_action 之下的這個鍵。
這個鍵底下的檔案會像 icons 一樣被輸出與檢查:
  • 每個變體檔案都輸出在它的原始位置,它在 manifest 中的路徑遵循與 icons 相同的規則。
  • 缺少變體檔案時,建置會以圖示錯誤停止,錯誤裡會寫出這個鍵:Can't find an icon file listed in icon_variants.
Chromium 只有在開啟 ExtensionIconVariants 旗標時才會讀取 icon_variants,Firefox 目前還不讀取這個鍵。對於這些目標,建置會保留你的 manifest 中宣告的 icons 與 action 的 default_icon。 如果 manifest 中沒有它們,建置會先用不帶 color_schemes 的變體群組來填入,其次用淺色群組。Chromium 只接受 PNG 尺寸,Firefox 還可以使用 any 的 SVG。 Safari 會在工具列上讀取 icon_variants,寫在頂層或 action 下都可以,並且優先於 icons。在 Safari 27 上實測,它一律繪製淺色組,在深色外觀下也不會切換到深色組。Apple 的應用程式轉換器不讀取這個鍵,只用 icons 來產生應用程式圖示。所以 Safari 建置會得到同樣的後備處理:
  • 如果 manifest 中有 icons 與 action 的 default_icon,建置會保留它們。
  • 如果 manifest 中沒有它們,建置會先用不帶 color_schemes 的變體群組來填入,其次用淺色群組。
  • 建置優先使用 PNG 尺寸,只有在沒有任何群組提供 PNG 時才使用 SVG。
  • icon_variants 本身會留在 Safari 的輸出裡,所以 Apple 的轉換器仍然會把這個鍵列為不支援。
建置會印出一則提示,說明瀏覽器顯示的是哪些圖示:
當建置替你填入 icons 時,提示也會說明:
在 Safari 建置中,提示會說明工具列和應用程式圖示各自使用什麼:
瀏覽器前綴對這個鍵同樣有效。chromium:icon_variants 或 firefox:icon_variants 底下的清單只會在對應瀏覽器的建置中輸出它的檔案。請見瀏覽器專屬的 manifest 欄位。

從 SVG 產生各尺寸 PNG

把 SVG 保留為設計原始檔,匯出所有瀏覽器都接受的 PNG 尺寸。下面這條命令使用 librsvg 提供的 rsvg-convert(macOS 上 brew install librsvg,Debian 與 Ubuntu 上 apt install librsvg2-bin):
然後像上面的範例那樣,把 icons 與 action.default_icon 指向這些 PNG 檔案。

輸出路徑

典型的圖示輸出:
圖示不會被搬進某個 icons/ 資料夾。宣告為 images/icon.png 的圖示會輸出在 images/icon.png,而輸出的 manifest 也仍然指向同一個路徑。

路徑行為

  • Extension.js 從 manifest 資料夾解析相對的圖示路徑。
  • 開頭為 / 與 public/... 的路徑會以擴充功能 public 根目錄的語義來解析。
  • Extension.js 可以監看 public 資料夾中的資產,而不必透過圖示功能本身重新輸出。
  • 由動態匯入的模組設定的圖示,會發布在載入該模組的 worker 或頁面旁邊。見執行階段載入的檔案。

開發行為

  • 變更現有圖示檔案會觸發重新編譯。
  • 當 manifest 的修改變更了圖示參考時,正在執行的 extension dev 工作階段會自行重新啟動編譯器。
  • 缺少必要的圖示檔會造成建置錯誤(某些可選的圖示群組會改為警告)。

最佳實務

  • 明確宣告 manifest 中的圖示欄位,而不是仰賴附帶的資產 import。
  • 提供多種圖示尺寸(16、32、48、128),讓瀏覽器各介面顯示更銳利。
  • 保持圖示檔名穩定,以減少開發期 manifest 的變動。
  • 刻意使用 public 根路徑,並測試最終 manifest 的輸出路徑。

後續步驟