chrome.sidePanel

說明

使用 chrome.sidePanel API，在網頁主要內容與瀏覽器的側邊面板中代管內容。

權限

sidePanel

如要使用 Side Panel API，請在擴充功能的資訊清單檔案中加入 "sidePanel" 權限：

manifest.json:

{
  "name": "My side panel extension",
  ...
  "permissions": [
    "sidePanel"
  ]
}

可用性

Chrome 114 以上版本 MV3 以上

概念和用法

Side Panel API 可讓擴充功能在側邊面板中顯示自己的使用者介面，藉此提供持續強化使用者的瀏覽體驗。

側邊面板下拉式選單
Chrome 瀏覽器側邊面板 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() 為特定分頁標籤啟用側邊面板。此範例使用 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()，例如：

固定側邊面板

側邊面板 UI 中的固定圖示。
側邊面板 UI 中的固定圖示。

側邊面板工具列開啟時，側邊面板工具列會顯示圖釘圖示。 按一下該圖示，就會固定擴充功能的動作圖示。按一下動作圖示 固定後會執行動作圖示的預設動作，且只會執行 如果已明確設定這項功能，請開啟側邊面板。

範例

如要查看更多側邊面板 API 擴充功能示範，請參閱下列擴充功能：

類型

GetPanelOptions

屬性

  • tabId

    編號 選填

    如果指定，系統會傳回指定分頁的側邊面板選項。否則，會傳回預設的側邊面板選項 (適用於任何沒有特定設定的分頁)。

OpenOptions

Chrome 116 以上版本

屬性

  • tabId

    編號 選填

    開啟側邊面板的分頁。如果對應的分頁有專屬的側邊面板，則系統只會在該分頁上開啟面板。如果沒有分頁專屬的面板，全域面板則會在指定的分頁和任何其他分頁中開啟，但這些分頁卻未開啟目前開啟的分頁專屬面板。這會覆寫對應的分頁標籤中目前有效的側邊面板 (全域或特定分頁)。至少須提供其中一項或 windowId。

  • windowId

    編號 選填

    開啟側邊面板的視窗。只有在擴充功能已指定全域 (非分頁專屬) 側邊面板或 tabId 時，才適用這項設定。這會覆寫使用者在指定視窗中開啟的所有全域側邊面板。至少須提供其中一項或 tabId。

PanelBehavior

屬性

  • openPanelOnActionClick

    布林值 選填

    是否點選擴充功能的圖示，側邊面板就會顯示擴充功能的項目。預設值為 false。

PanelOptions

屬性

  • 已啟用

    布林值 選填

    是否應啟用側邊面板。。預設值為 true。

  • 路徑

    string optional

    要使用的側邊面板 HTML 檔案路徑。這必須是擴充功能套件中的本機資源。

  • tabId

    編號 選填

    如有指定，側邊面板選項只會套用到具有此 ID 的分頁。如果您省略此選項，系統會使用這些選項設定預設行為 (適用於所有沒有特定設定的分頁)。注意：如果此 tabId 和預設的 tabId 路徑相同，則該 tabId 的面板會與預設的 tabId 面板不同。

SidePanel

屬性

  • default_path

    字串

    開發人員指定的側邊面板顯示路徑。

方法

getOptions()

Promise 
chrome.sidePanel.getOptions(
  options: GetPanelOptions,
  callback?: function,
)

傳回進行中的面板設定。

參數

傳回

  • Promise&lt;PanelOptions&gt;

    Promise 適用於 Manifest V3 及以上版本，但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。

getPanelBehavior()

Promise 
chrome.sidePanel.getPanelBehavior(
  callback?: function,
)

傳回擴充功能目前的側邊面板行為。

參數

傳回

  • Promise&lt;PanelBehavior&gt;

    Promise 適用於 Manifest V3 及以上版本，但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。

open()

Promise Chrome 116 以上版本 
chrome.sidePanel.open(
  options: OpenOptions,
  callback?: function,
)

開啟擴充功能的側邊面板。只有在回應使用者動作時才需要呼叫。

參數

  • 選項

    OpenOptions

    指定要在哪個位置開啟側邊面板。

  • 回呼

    函式 選用

    callback 參數如下所示： 

    () => void

傳回

  • 承諾<void>

    Promise 適用於 Manifest V3 及以上版本，但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。

setOptions()

Promise 
chrome.sidePanel.setOptions(
  options: PanelOptions,
  callback?: function,
)

設定側邊面板。

參數

  • 選項

    PanelOptions

    要套用至面板的設定選項。

  • 回呼

    函式 選用

    callback 參數如下所示： 

    () => void

傳回

  • 承諾<void>

    Promise 適用於 Manifest V3 及以上版本，但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。

setPanelBehavior()

Promise 
chrome.sidePanel.setPanelBehavior(
  behavior: PanelBehavior,
  callback?: function,
)

設定擴充功能的側邊面板行為。此為新增/插入作業。

參數

  • 行為

    PanelBehavior

    要設定的新行為。

  • 回呼

    函式 選用

    callback 參數如下所示： 

    () => void

傳回

  • 承諾<void>

    Promise 適用於 Manifest V3 及以上版本，但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。