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()。擴充功能可讓擴充功能透過擴充功能使用者手勢開啟側邊面板，例如按一下動作圖示。或是在擴充功能網頁或內容指令碼上進行互動，例如按下按鈕。如需完整示範，請參閱「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.tabs.onActivated.addListener(async ({ tabId }) => {
  const { path } = await chrome.sidePanel.getOptions({ tabId });
  if (path === welcomePage) {
    chrome.sidePanel.setOptions({ path: mainPage });
  }
});

如需完整範例，請參閱多個側邊面板。

側邊面板使用者體驗

使用者會先看到 Chrome 的內建側邊面板。每個側邊面板都會在側邊面板選單中顯示擴充功能的圖示。如果未加入任何圖示，則會出現擴充功能名稱第一個字母的預留位置圖示。

開啟側邊面板

前往側邊面板選單
使用者可以在側邊面板選單中找到可用的側邊面板。再從下拉式選單中選擇額外資訊。
側邊面板下拉式選單
Chrome 瀏覽器側邊面板 UI。
透過使用者手勢開啟

您可以使用 sidePanel.open() 和 sidePanel.setPanelBehavior()，透過使用者互動方式開啟側邊面板，例如：

示例

如要進一步瞭解 Side Panel API 擴充功能示範，請參考下列任一擴充功能：

類型

GetPanelOptions

屬性

  • tabId

    數字 選填

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

OpenOptions

Chrome 116 以上版本

屬性

  • tabId

    數字 選填

    用來開啟側邊面板的分頁。如果對應的分頁有特定分頁的側邊面板，該面板只會開啟該分頁。如果沒有特定分頁面板，全域面板會在指定的分頁和任何其他分頁中開啟，但不會顯示目前開啟的分頁特定面板。這會覆寫對應分頁中目前使用中的側邊面板 (全域或特定分頁)。必須提供至少一個此值或 windowId。

  • windowId

    數字 選填

    用來開啟側邊面板的視窗。只有在擴充功能具有全域 (非分頁專屬) 側邊面板，或同時指定 tabId 時，才適用這項政策。這會覆寫使用者在指定視窗中目前開啟的所有全域側邊面板。必須提供至少一個此值或 tabId。

PanelBehavior

屬性

  • openPanelOnActionClick

    布林值 (選用)

    是否按一下擴充功能圖示，即可在側邊面板中顯示擴充功能的項目。預設值為 false。

PanelOptions

屬性

  • 已啟用

    布林值 (選用)

    是否應啟用側邊面板。這不是必要的步驟。預設值為 true。

  • path

    字串 選用

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

  • tabId

    數字 選填

    如果有指定，側邊面板選項只會套用至這個 ID 的分頁。省略時，這些選項會設定預設行為 (適用於無特定設定的分頁)。注意：如果此 tabId 和 default tabId 有相同的路徑，則此 tabId 的面板將與預設的 tabId 面板不同。

SidePanel

屬性

  • default_path

    字串

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

方法

getOptions()

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

傳回使用中的面板設定。

參數

傳回

  • Promise<PanelOptions>

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

getPanelBehavior()

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

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

參數

傳回

  • Promise<PanelBehavior>

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

open()

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

開啟擴充功能的側邊面板。只有在回應使用者動作時，系統才會呼叫此方法。

參數

  • 選項

    OpenOptions

    指定要在哪個情境中開啟側邊面板。

  • 回呼

    函式選用

    callback 參數如下所示： 

    ()=>void

傳回

  • Promise<void>

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

setOptions()

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

設定側邊面板。

參數

  • 選項

    PanelOptions

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

  • 回呼

    函式選用

    callback 參數如下所示： 

    ()=>void

傳回

  • Promise<void>

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

setPanelBehavior()

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

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

參數

  • 行為

    PanelBehavior

    要設定的新行為。

  • 回呼

    函式選用

    callback 參數如下所示： 

    ()=>void

傳回

  • Promise<void>

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。