每個瀏覽器使用哪套 API
Firefox 沒有
chrome.sidePanel,Chrome 也沒有 sidebarAction。Safari 兩者都沒有。如何讓 Safari 的背景保持執行,請參閱建置 Safari 擴充功能中的防護寫法。
在 manifest 中宣告面板
使用瀏覽器前綴,讓每個建置拿到自己的鍵:manifest.json
dist/ 中的位置。可用瀏覽器頁面列出每個前綴會套用到哪些目標。
這份 manifest 遵循三條規則:
- Chrome 需要
sidePanel權限。 沒有這個權限,Chrome 不會顯示面板。對於你自己寫的side_panel鍵,建置不會自動加上它。 - 帶前綴的鍵會取代不帶前綴的鍵。 如果你同時寫了不帶前綴的
permissions清單,在 Chromium 建置中它會被chromium:permissions取代。請把所有 Chromium 權限都寫進chromium:permissions。 - 只寫一個鍵,Firefox 仍然會有 sidebar。 在 Extension.js 4.1.33 中,只宣告了
side_panel的 manifest 在建置 Firefox 時會得到一個指向同一頁面的sidebar_action鍵。建置會為此印出一則警告。如果想分別控制每個瀏覽器,請同時宣告兩個鍵。
執行階段 API:chrome.sidePanel 與 browser.sidebarAction
關於這張表:
sidePanel.close()從 Chrome 141 開始提供。 面板已經關閉時,它什麼也不做。從 Chrome 145 開始,如果只開啟了全域面板,close({ tabId })會 reject。在 Chrome 145 之前,同樣的呼叫會關閉全域面板。- Chrome 沒有
isOpen()。 要知道面板狀態,請監聽onOpened和onClosed。 - 如果同時傳入
tabId和windowId,Firefox 的setPanel、setTitle和setIcon會失敗。 只傳其中一個,或者都不傳以修改全域值。 - Chrome 沒有面板的標題或圖示 API。 Chrome 在 side panel 選單中顯示擴充功能的圖示。
chrome.action.setTitle和chrome.action.setIcon只修改工具列按鈕。
sidePanel 參考文件和 MDN sidebarAction 參考文件。
使用者手勢規則
兩個瀏覽器都只在使用者做了某個操作之後才開啟面板。規則並不相同:- Firefox:
open()、close()和toggle()只能在使用者操作的處理函式中呼叫。工具列點擊、右鍵選單項目、鍵盤指令和擴充功能頁面上的按鈕都算作使用者操作。 - Chromium:
open()只能在使用者手勢之後呼叫。工具列點擊、鍵盤指令、右鍵選單項目,以及在擴充功能頁面或內容腳本中的點擊都算作使用者手勢。Chrome 參考文件沒有為close()規定手勢要求。 - 在 Chromium 上,工具列點擊是例外。 在背景腳本的頂層呼叫一次
setPanelBehavior。之後,工具列點擊會直接開啟面板,你的程式碼不會執行。
從工具列按鈕開啟面板
這個背景腳本為每個瀏覽器準備了各自的路徑。判斷在建置時完成,所以每個套件只保留屬於自己的一半:background.js
setPanelBehavior,不要在點擊處理函式中呼叫。這個行為只對之後的點擊生效,所以如果在第一次點擊中才呼叫,第一次點擊不會開啟面板。
Firefox 這一半使用 browserAction,因為上面的 manifest 把 Firefox 建置為 Manifest V2。各個目標上 EXTENSION_PUBLIC_BROWSER 的值,請參閱環境變數。
從你自己的手勢開啟面板
如果要從右鍵選單、按鈕或快速鍵開啟面板,請在執行階段偵測 API。判斷條件用你要呼叫的方法sidebarAction.open,而不是只判斷 browser 物件:
background.js
contextMenus 加到兩個權限清單中:
manifest.json
openPanel 在呼叫 open() 之前沒有任何 await,所以選單點擊帶來的手勢仍然有效。
Firefox 建置會對 chrome.sidePanel 發出警告
從 4.1.18 開始,為 Firefox 做正式建置時,如果套件中讀取了chrome.sidePanel,建置會發出警告。建置仍然會成功。上一節的執行階段偵測會觸發這則警告,因為 Firefox 套件中仍然包含 chrome.sidePanel.open 呼叫。工具列範例中的 isFirefoxLike 判斷不會觸發它,因為建置會刪除 Chromium 那一半。完整的提示訊息和修正方法,請參閱 Firefox 建置會對僅 Chromium 可用的 API 發出警告。
要在右鍵選單範例中消除這則警告,請把 openPanel 中的執行階段偵測換成 isFirefoxLike。

