說明
使用 chrome.sidePanel API，在瀏覽器的側邊面板中，與網頁的主要內容並列顯示內容。
權限
sidePanel如要使用 Side Panel API，請在擴充功能的資訊清單檔案中新增 "sidePanel" 權限：
manifest.json:
{
"name": "My side panel extension",
...
"permissions": [
"sidePanel"
]
}
可用性
概念和用途
Side Panel API 可讓擴充功能在側邊面板中顯示自己的 UI，提供持續性的體驗，輔助使用者的瀏覽過程。
部分功能包括：
- 切換分頁時，側邊面板會保持開啟 (如果已設定)。
- 僅適用於特定網站。
- 側邊面板是擴充功能頁面，因此可存取所有 Chrome API。
- 使用者可以在 Chrome 設定中，指定面板顯示在哪一側。
用途
以下各節將說明 Side Panel API 的一些常見用途。如需完整的擴充功能範例，請參閱「擴充功能範例」。
在每個網站上顯示相同的側邊面板
您可以從資訊清單 "side_panel" 鍵的 "default_path" 屬性，一開始就設定側邊面板，在每個網站上顯示相同的側邊面板。這應指向擴充功能目錄中的相對路徑。
manifest.json:
{
"name": "My side panel extension",
...
"side_panel": {
"default_path": "sidepanel.html"
}
...
}
sidepanel.html:
<!DOCTYPE html>
<html>
<head>
<title>My Sidepanel</title>
</head>
<body>
<h1>All sites sidepanel extension</h1>
<p>This side panel is enabled on all sites</p>
</body>
</html>
在特定網站上啟用側邊面板
擴充功能可以使用 sidepanel.setOptions()，在特定分頁啟用側邊面板。這個範例使用 browser.tabs.onUpdated() 監聽分頁的任何更新。檢查網址是否為 www.google.com，並啟用側邊面板。否則，系統會停用該功能。
service-worker.js：
const GOOGLE_ORIGIN = 'https://www.google.com';
browser.tabs.onUpdated.addListener(async (tabId, info, tab) => {
if (!tab.url) return;
const url = new URL(tab.url);
// Enables the side panel on google.com
if (url.origin === GOOGLE_ORIGIN) {
await browser.sidePanel.setOptions({
tabId,
path: 'sidepanel.html',
enabled: true
});
} else {
// Disables the side panel on all other sites
await browser.sidePanel.setOptions({
tabId,
enabled: false
});
}
});
如果使用者暫時切換到未啟用側邊面板的分頁，側邊面板就會隱藏。當使用者切換到先前開啟過該面板的分頁時，面板會自動再次顯示。
如果使用者前往未啟用側邊面板的網站，側邊面板就會關閉，且擴充功能不會顯示在側邊面板下拉式選單中。
如需已完成樣本，請參閱分頁專屬側邊面板範例。
按一下工具列圖示，開啟側邊面板
開發人員可以讓使用者在點選動作工具列圖示時，使用 sidePanel.setPanelBehavior() 開啟側邊面板。首先，在資訊清單中宣告 "action" 鍵：
manifest.json:
{
"name": "My side panel extension",
...
"action": {
"default_title": "Click to open panel"
},
...
}
現在，請將這段程式碼新增至上一個範例：
service-worker.js：
const GOOGLE_ORIGIN = 'https://www.google.com';
// Allows users to open the side panel by clicking on the action toolbar icon
browser.sidePanel
.setPanelBehavior({ openPanelOnActionClick: true })
.catch((error) => console.error(error));
...
透過程式輔助，在使用者互動時開啟側邊面板
Chrome 116 推出 sidePanel.open()。擴充功能可透過使用者手勢開啟側邊面板，例如點選動作圖示。或擴充功能頁面或內容指令碼上的使用者互動，例如點選按鈕。如需完整示範，請參閱開啟側邊面板範例擴充功能。
下列程式碼說明如何在使用者點選內容選單時，在目前視窗中開啟全域側邊面板。使用 sidePanel.open() 時，您必須選擇開啟的情境。使用 windowId 開啟全域側邊面板。或者，您也可以設定 tabId，只在特定分頁開啟側邊面板。
service-worker.js：
browser.runtime.onInstalled.addListener(() => {
browser.contextMenus.create({
id: 'openSidePanel',
title: 'Open side panel',
contexts: ['all']
});
});
browser.contextMenus.onClicked.addListener((info, tab) => {
if (info.menuItemId === 'openSidePanel') {
// This will open the panel in all the pages on the current window.
browser.sidePanel.open({ windowId: tab.windowId });
}
});
切換至其他面板
擴充功能可以使用 sidepanel.getOptions() 擷取目前的側邊面板。以下範例會在 runtime.onInstalled() 上設定歡迎側邊面板。當使用者前往其他分頁時，系統會將其替換為主要側邊面板。
service-worker.js：
const welcomePage = 'sidepanels/welcome-sp.html';
const mainPage = 'sidepanels/main-sp.html';
browser.runtime.onInstalled.addListener(() => {
browser.sidePanel.setOptions({ path: welcomePage });
browser.sidePanel.setPanelBehavior({ openPanelOnActionClick: true });
});
browser.tabs.onActivated.addListener(async ({ tabId }) => {
const { path } = await browser.sidePanel.getOptions({ tabId });
if (path === welcomePage) {
browser.sidePanel.setOptions({ path: mainPage });
}
});
如需完整程式碼，請參閱多個側邊面板範例。
側邊面板使用者體驗
使用者會先看到 Chrome 內建的側邊面板。每個側邊面板都會在側邊面板選單中顯示擴充功能的圖示。如果未提供圖示，系統會顯示預留位置圖示，其中包含擴充功能名稱的第一個字母。
開啟側邊面板
如要允許使用者開啟側邊面板，請搭配使用動作圖示和 sidePanel.setPanelBehavior()。或者，您也可以在使用者互動後呼叫 sidePanel.open()，例如：
固定側邊面板
側邊面板開啟時，側邊面板工具列會顯示圖釘圖示。 按一下圖示，即可固定擴充功能的動作圖示。固定後，按一下動作圖示會執行動作圖示的預設動作，且只有在明確設定後，才會開啟側邊面板。
範例
如需更多 Side Panel API 擴充功能示範，請瀏覽下列任一擴充功能：
類型
CloseOptions
屬性
-
tabId
數字 選填
要關閉側邊面板的分頁。如果指定分頁已開啟分頁專屬側邊面板，系統會關閉該分頁的側邊面板。如果只開啟全域側邊面板，呼叫
close()傳回的 Promise 會遭到拒絕，並顯示錯誤。這項行為在 Chrome 145 中有所變更，舊版會改為關閉全域面板。必須提供這個欄位或windowId。 -
windowId
數字 選填
要關閉側邊面板的視窗。如果指定視窗中開啟了全域側邊面板，系統會關閉該視窗中所有未啟用分頁專屬面板的分頁。必須提供這個欄位或
tabId。
GetPanelOptions
屬性
-
tabId
數字 選填
如果指定，系統會傳回指定分頁的側邊面板選項。否則，系統會傳回預設的側邊面板選項 (用於未指定設定的分頁)。
OpenOptions
屬性
-
tabId
數字 選填
要在哪個分頁開啟側邊面板。如果對應的分頁有專屬側邊面板，則該面板只會為該分頁開啟。如果沒有分頁專屬面板，全域面板會在指定分頁和任何其他分頁中開啟，但不會開啟目前已開啟的分頁專屬面板。這會覆寫對應分頁中目前啟用的任何側邊面板 (全域或分頁專屬)。必須提供這個欄位或
windowId。 -
windowId
數字 選填
要在其中開啟側邊面板的視窗。只有在擴充功能具有全域 (非分頁專屬) 側邊面板，或同時指定
tabId時，才適用這項權限。這會覆寫使用者在指定視窗中開啟的任何目前有效的全域側邊面板。必須提供這個欄位或tabId。
PanelBehavior
屬性
-
openPanelOnActionClick
布林值 選填
點選擴充功能圖示後，是否會在側邊面板切換顯示擴充功能項目。預設值為 false。
PanelClosedInfo
屬性
-
路徑
字串
擴充功能套件中本機資源的路徑，其內容會顯示在面板中。
-
tabId
數字 選填
關閉側邊面板的分頁 ID (選用)。只有在面板為分頁專屬時，才會提供這項資訊。
-
windowId
數字
關閉側邊面板的視窗 ID。這項功能適用於全域和分頁專屬面板。
PanelLayout
屬性
-
球隊
PanelOpenedInfo
屬性
-
路徑
字串
擴充功能套件中本機資源的路徑，其內容會顯示在面板中。
-
tabId
數字 選填
開啟側邊面板的分頁 ID (選用)。只有在面板為分頁專屬時，才會提供這項資訊。
-
windowId
數字
開啟側邊面板的視窗 ID。這項功能適用於全域和分頁專屬面板。
PanelOptions
屬性
-
已啟用
布林值 選填
是否啟用側邊面板。(此為自選設定)。預設值為 true。
-
路徑
字串 選填
要使用的側邊面板 HTML 檔案路徑。這必須是擴充功能套件中的本機資源。
-
tabId
數字 選填
如果指定，側邊面板選項只會套用至具有這個 ID 的分頁。如果省略，這些選項會設定預設行為 (用於沒有特定設定的分頁)。注意：如果為這個 tabId 和預設 tabId 設定相同的路徑，則這個 tabId 的面板會與預設 tabId 的面板不同。
Side
定義瀏覽器 UI 中側邊面板可能的對齊方式。
列舉
"left"
"right"
SidePanel
屬性
-
default_path
字串
開發人員指定的側邊面板顯示路徑。
方法
close()
browser.sidePanel.close(
options: CloseOptions,
): Promise<void>
關閉擴充功能的側邊面板。如果面板已關閉，則不會執行任何操作。
參數
-
選項
指定關閉側邊面板的情境。
傳回
-
承諾<void>
傳回 Promise，在側邊面板關閉時解析。
getLayout()
browser.sidePanel.getLayout(): Promise<PanelLayout>
傳回側邊面板目前的版面配置。
傳回
-
Promise<PanelLayout>
傳回 Promise，其解析為
PanelLayout。
getOptions()
browser.sidePanel.getOptions(
options: GetPanelOptions,
): Promise<PanelOptions>
傳回有效的面板設定。
參數
-
指定要傳回設定的背景資訊。
傳回
-
Promise<PanelOptions>
傳回 Promise，並解析為有效的面板設定。
傳回
-
Promise<PanelBehavior>
傳回 Promise，並根據擴充功能的側邊面板行為解析。
open()
browser.sidePanel.open(
options: OpenOptions,
): Promise<void>
開啟擴充功能的側邊面板。只有在回應使用者動作時，才能呼叫這個方法。
參數
-
選項
指定開啟側邊面板的情境。
傳回
-
承諾<void>
傳回 Promise，在側邊面板開啟時解析。
參數
-
選項
要套用至面板的設定選項。
傳回
-
承諾<void>
傳回 Promise，在設定選項後解析。
setPanelBehavior()
browser.sidePanel.setPanelBehavior(
behavior: PanelBehavior,
): Promise<void>
設定擴充功能的側邊面板行為。這項作業會新增或更新資料。
參數
-
要設定的新行為。
傳回
-
承諾<void>
傳回 Promise，在設定新行為時解析。
事件
onClosed
browser.sidePanel.onClosed.addListener(
callback: function,
)
在擴充功能的側邊面板關閉時觸發。
參數
-
callback
函式
callback參數如下：(info: PanelClosedInfo) => void
onOpened
browser.sidePanel.onOpened.addListener(
callback: function,
)
在擴充功能的側邊面板開啟時觸發。
參數
-
callback
函式
callback參數如下：(info: PanelOpenedInfo) => void