說明
使用 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()
。擴充功能可讓擴充功能透過擴充功能使用者手勢開啟側邊面板,例如按一下動作圖示。或是在擴充功能網頁或內容指令碼上進行互動,例如按下按鈕。如需完整示範,請參閱「Open Side Panel」範例擴充功能。
下方程式碼顯示當使用者點選內容選單時,如何在目前視窗中開啟全域側邊面板。使用 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()
,例如:
固定側邊面板
側邊面板開啟時,側邊面板工具列會顯示圖釘圖示。 按一下圖示,即可固定擴充功能的動作圖示。按下固定後的動作圖示,會執行動作圖示的預設動作,而且只有在已明確設定此項目時才會開啟側邊面板。
示例
如要進一步瞭解 Side Panel API 擴充功能示範,請參考下列任一擴充功能:
類型
GetPanelOptions
屬性
-
tabId
數字 選填
如果有指定,系統就會傳回指定分頁的側邊面板選項。否則,會傳回預設的側邊面板選項 (適用於沒有特定設定的分頁)。
OpenOptions
屬性
-
tabId
數字 選填
用來開啟側邊面板的分頁。如果對應的分頁有特定分頁的側邊面板,該面板只會開啟該分頁。如果沒有特定分頁面板,全域面板會在指定的分頁和任何其他分頁中開啟,但不會顯示目前開啟的分頁特定面板。這會覆寫對應分頁中目前使用中的側邊面板 (全域或特定分頁)。必須提供至少一個此值或
windowId
。 -
windowId
數字 選填
用來開啟側邊面板的視窗。只有在擴充功能具有全域 (非分頁專屬) 側邊面板,或同時指定
tabId
時,才適用這項政策。這會覆寫使用者在指定視窗中目前開啟的所有全域側邊面板。必須提供至少一個此值或tabId
。
PanelBehavior
屬性
-
openPanelOnActionClick
布林值 (選用)
是否按一下擴充功能圖示,即可在側邊面板中顯示擴充功能的項目。預設值為 false。
PanelOptions
屬性
-
已啟用
布林值 (選用)
是否應啟用側邊面板。這不是必要的步驟。預設值為 true。
-
path
字串 選用
要使用的側邊面板 HTML 檔案路徑。這必須是擴充功能套件中的本機資源。
-
tabId
數字 選填
如果有指定,側邊面板選項只會套用至這個 ID 的分頁。省略時,這些選項會設定預設行為 (適用於無特定設定的分頁)。注意:如果此 tabId 和 default tabId 有相同的路徑,則此 tabId 的面板將與預設的 tabId 面板不同。
SidePanel
屬性
-
default_path
字串
開發人員指定的側邊面板顯示路徑。
方法
getOptions()
chrome.sidePanel.getOptions(
options: GetPanelOptions,
callback?: function,
)
傳回使用中的面板設定。
參數
-
指定要傳回設定的結構定義。
-
回呼
函式選用
callback
參數如下所示:(options: PanelOptions) => void
-
選項
-
傳回
-
Promise<PanelOptions>
Manifest V3 以上版本支援 Promise,但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。
getPanelBehavior()
chrome.sidePanel.getPanelBehavior(
callback?: function,
)
傳回擴充功能目前的側邊面板行為。
參數
-
回呼
函式選用
callback
參數如下所示:(behavior: PanelBehavior) => void
傳回
-
Promise<PanelBehavior>
Manifest V3 以上版本支援 Promise,但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。
open()
chrome.sidePanel.open(
options: OpenOptions,
callback?: function,
)
開啟擴充功能的側邊面板。只有在回應使用者動作時,系統才會呼叫此方法。
參數
-
選項
指定要在哪個情境中開啟側邊面板。
-
回呼
函式選用
callback
參數如下所示:() => void
傳回
-
Promise<void>
Manifest V3 以上版本支援 Promise,但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。
setOptions()
chrome.sidePanel.setOptions(
options: PanelOptions,
callback?: function,
)
設定側邊面板。
參數
-
選項
要套用至面板的設定選項。
-
回呼
函式選用
callback
參數如下所示:() => void
傳回
-
Promise<void>
Manifest V3 以上版本支援 Promise,但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。
setPanelBehavior()
chrome.sidePanel.setPanelBehavior(
behavior: PanelBehavior,
callback?: function,
)
設定擴充功能的側邊面板行為。這是更新/插入作業。
參數
-
要設定的新行為。
-
回呼
函式選用
callback
參數如下所示:() => void
傳回
-
Promise<void>
Manifest V3 以上版本支援 Promise,但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。