說明
使用 chrome.sidePanel
API,在網頁主要內容與瀏覽器的側邊面板中代管內容。
權限
sidePanel
如要使用 Side Panel API,請在擴充功能的資訊清單檔案中加入 "sidePanel"
權限:
manifest.json:
{
"name": "My side panel extension",
...
"permissions": [
"sidePanel"
]
}
可用性
概念和用法
Side Panel API 可讓擴充功能在側邊面板中顯示自己的使用者介面,藉此提供持續強化使用者的瀏覽體驗。
部分功能包括:
- 如果在設定分頁瀏覽時,側邊面板會保持開啟狀態。
- 而且只適用於特定網站。
- 側邊面板是以擴充功能頁面的形式存取所有 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()
為特定分頁標籤啟用側邊面板。此範例使用 chrome.tabs.onUpdated()
監聽對分頁所做的任何更新。會檢查網址為 www.google.com 並啟用側邊面板。否則該功能會停用。
service-worker.js:
const GOOGLE_ORIGIN = 'https://www.google.com';
chrome.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 chrome.sidePanel.setOptions({
tabId,
path: 'sidepanel.html',
enabled: true
});
} else {
// Disables the side panel on all other sites
await chrome.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
chrome.sidePanel
.setPanelBehavior({ openPanelOnActionClick: true })
.catch((error) => console.error(error));
...
透過程式輔助方式開啟使用者互動事件的側邊面板
Chrome 116 推出了 sidePanel.open()
。可讓擴充功能透過擴充功能使用者手勢 (例如按一下動作圖示) 開啟側邊面板。或是在擴充功能頁面或內容指令碼上的互動,例如點擊按鈕。如需完整示範,請參閱開啟側邊面板的擴充功能範例。
以下程式碼顯示如何在使用者點選內容選單時,在目前視窗中開啟全域側邊面板。使用 sidePanel.open()
時,您必須選擇要在何種情況下開啟它。使用 windowId
開啟全域側邊面板。或者,您也可以將 tabId
設為只在特定分頁中開啟側邊面板。
service-worker.js:
chrome.runtime.onInstalled.addListener(() => {
chrome.contextMenus.create({
id: 'openSidePanel',
title: 'Open side panel',
contexts: ['all']
});
});
chrome.contextMenus.onClicked.addListener((info, tab) => {
if (info.menuItemId === 'openSidePanel') {
// This will open the panel in all the pages on the current window.
chrome.sidePanel.open({ windowId: tab.windowId });
}
});
切換到其他面板
擴充功能可以使用 sidepanel.getOptions()
擷取目前的側邊面板。以下範例會在 runtime.onInstalled()
上設定歡迎側邊面板。這樣一來,當使用者前往其他分頁時,該分頁就會取代主要側邊面板。
service-worker.js:
const welcomePage = 'sidepanels/welcome-sp.html';
const mainPage = 'sidepanels/main-sp.html';
chrome.runtime.onInstalled.addListener(() => {
chrome.sidePanel.setOptions({ path: welcomePage });
chrome.sidePanel.setPanelBehavior({ openPanelOnActionClick: true });
});
chrome.tabs.onActivated.addListener(async ({ tabId }) => {
const { path } = await chrome.sidePanel.getOptions({ tabId });
if (path === welcomePage) {
chrome.sidePanel.setOptions({ path: mainPage });
}
});
如需完整程式碼,請參閱多側邊面板範例。
側邊面板使用者體驗
使用者會先看到 Chrome 內建的側邊面板。每個側邊面板都會在側邊面板選單中顯示擴充功能的圖示。如果未附上圖示,則會顯示預留位置圖示,其中含有擴充功能名稱的首字母。
開啟側邊面板
如要允許使用者開啟側邊面板,請搭配使用動作圖示
使用 sidePanel.setPanelBehavior()
。或者,您也可以在使用者互動後呼叫 sidePanel.open()
,例如:
固定側邊面板
側邊面板工具列開啟時,側邊面板工具列會顯示圖釘圖示。 按一下該圖示,就會固定擴充功能的動作圖示。按一下動作圖示 固定後會執行動作圖示的預設動作,且只會執行 如果已明確設定這項功能,請開啟側邊面板。
範例
如要查看更多側邊面板 API 擴充功能示範,請參閱下列擴充功能:
類型
GetPanelOptions
屬性
-
tabId
編號 選填
如果指定,系統會傳回指定分頁的側邊面板選項。否則,會傳回預設的側邊面板選項 (適用於任何沒有特定設定的分頁)。
OpenOptions
屬性
-
tabId
編號 選填
開啟側邊面板的分頁。如果對應的分頁有專屬的側邊面板,則系統只會在該分頁上開啟面板。如果沒有分頁專屬的面板,全域面板則會在指定的分頁和任何其他分頁中開啟,但這些分頁卻未開啟目前開啟的分頁專屬面板。這會覆寫對應的分頁標籤中目前有效的側邊面板 (全域或特定分頁)。至少須提供其中一項或
windowId
。 -
windowId
編號 選填
開啟側邊面板的視窗。只有在擴充功能已指定全域 (非分頁專屬) 側邊面板或
tabId
時,才適用這項設定。這會覆寫使用者在指定視窗中開啟的所有全域側邊面板。至少須提供其中一項或tabId
。
PanelBehavior
屬性
-
openPanelOnActionClick
布林值 選填
是否點選擴充功能的圖示,側邊面板就會顯示擴充功能的項目。預設值為 false。
PanelOptions
屬性
-
已啟用
布林值 選填
是否應啟用側邊面板。。預設值為 true。
-
路徑
string optional
要使用的側邊面板 HTML 檔案路徑。這必須是擴充功能套件中的本機資源。
-
tabId
編號 選填
如有指定,側邊面板選項只會套用到具有此 ID 的分頁。如果您省略此選項,系統會使用這些選項設定預設行為 (適用於所有沒有特定設定的分頁)。注意:如果此 tabId 和預設的 tabId 路徑相同,則該 tabId 的面板會與預設的 tabId 面板不同。
SidePanel
屬性
-
default_path
字串
開發人員指定的側邊面板顯示路徑。
方法
getOptions()
chrome.sidePanel.getOptions(
options: GetPanelOptions,
callback?: function,
)
傳回進行中的面板設定。
參數
-
指定要傳回設定的背景資訊。
-
回呼
函式 選用
callback
參數如下所示:(options: PanelOptions) => void
-
選項
-
傳回
-
Promise<PanelOptions>
Promise 適用於 Manifest V3 及以上版本,但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。
getPanelBehavior()
chrome.sidePanel.getPanelBehavior(
callback?: function,
)
傳回擴充功能目前的側邊面板行為。
參數
-
回呼
函式 選用
callback
參數如下所示:(behavior: PanelBehavior) => void
傳回
-
Promise<PanelBehavior>
Promise 適用於 Manifest V3 及以上版本,但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。
open()
chrome.sidePanel.open(
options: OpenOptions,
callback?: function,
)
開啟擴充功能的側邊面板。只有在回應使用者動作時才需要呼叫。
參數
-
選項
指定要在哪個位置開啟側邊面板。
-
回呼
函式 選用
callback
參數如下所示:() => void
傳回
-
承諾<void>
Promise 適用於 Manifest V3 及以上版本,但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。
setOptions()
chrome.sidePanel.setOptions(
options: PanelOptions,
callback?: function,
)
設定側邊面板。
參數
-
選項
要套用至面板的設定選項。
-
回呼
函式 選用
callback
參數如下所示:() => void
傳回
-
承諾<void>
Promise 適用於 Manifest V3 及以上版本,但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。
setPanelBehavior()
chrome.sidePanel.setPanelBehavior(
behavior: PanelBehavior,
callback?: function,
)
設定擴充功能的側邊面板行為。此為新增/插入作業。
參數
-
要設定的新行為。
-
回呼
函式 選用
callback
參數如下所示:() => void
傳回
-
承諾<void>
Promise 適用於 Manifest V3 及以上版本,但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。