Chrome 现在支持标准化的 browser.* 命名空间（自 Chrome 148 起提供）。我们正在逐步更新文档。如需了解详情，请参阅我们的过渡指南。

Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

browser.sidePanel

说明

使用 chrome.sidePanel API 在浏览器的侧边栏中托管内容，与网页的主要内容并排显示。

权限

sidePanel

如需使用 Side Panel API，请在扩展程序清单文件中添加 "sidePanel" 权限：

manifest.json:

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

可用性

Chrome 114 及更高版本 browser.*（自 Chrome 148 起） MV3 及更高版本

概念和用法

借助 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() 在特定标签页上启用侧边栏。此示例使用 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

Chrome 141 及更高版本 browser.*（自 Chrome 148 起）

属性

tabId

number 可选

要在其中关闭侧边栏的标签页。如果指定标签页中打开了标签页专用侧边栏，系统会关闭该标签页的侧边栏。如果仅打开了全局侧边栏，则调用 close() 返回的 promise 将拒绝并返回错误。此行为在 Chrome 145 中发生了变化，之前的版本会回退到关闭全局面板。必须至少提供此字段或 windowId。
windowId

number 可选

要在其中关闭侧边栏的窗口。如果指定窗口中打开了全局侧边栏，则该窗口中所有未启用标签页专用侧边栏的标签页都会关闭全局侧边栏。必须至少提供此字段或 tabId。

GetPanelOptions

属性

tabId

number 可选

如果指定，系统将返回给定标签页的侧边栏选项。否则，返回默认侧边栏选项（用于任何没有特定设置的标签页）。

OpenOptions

Chrome 116 及更高版本 browser.*（自 Chrome 148 起）

属性

tabId

number 可选

要在其中打开侧边栏的标签页。如果相应标签页有标签页专属侧边栏，则该侧边栏只会针对该标签页打开。如果没有标签页专用面板，则全局面板将在指定标签页以及当前未打开标签页专用面板的任何其他标签页中打开。这会覆盖相应标签页中当前处于活跃状态的所有侧边栏（全局或标签页专用）。必须至少提供此字段或 windowId。
windowId

number 可选

要在其中打开侧边栏的窗口。仅当扩展程序具有全局（非标签页专用）侧边栏或同时指定了 tabId 时，此属性才适用。这将覆盖用户在给定窗口中打开的任何当前处于活动状态的全局侧边栏。必须至少提供此字段或 tabId。

PanelBehavior

属性

openPanelOnActionClick

布尔值（可选）

点击扩展程序的图标是否会切换在侧边栏中显示扩展程序的条目。默认值为 false。

PanelClosedInfo

Chrome 142 及更高版本 browser.*（自 Chrome 148 起）

属性

路径

字符串

扩展程序包中本地资源的路径，其内容会显示在面板中。
tabId

number 可选

关闭侧边栏的标签页的可选 ID。仅当面板特定于标签页时，系统才会提供此信息。
windowId

数值

关闭侧边栏的窗口的 ID。这适用于全局面板和标签页专用面板。

PanelLayout

Chrome 140 及更高版本 browser.*（自 Chrome 148 起）

属性

side

Side

PanelOpenedInfo

Chrome 141 及更高版本 browser.*（自 Chrome 148 起）

属性

路径

字符串

扩展程序包中本地资源的路径，其内容会显示在面板中。
tabId

number 可选

打开侧边栏的标签页的可选 ID。仅当面板特定于标签页时，系统才会提供此信息。
windowId

数值

打开侧边栏的窗口的 ID。这适用于全局面板和标签页专用面板。

PanelOptions

属性

已启用

布尔值（可选）

是否应启用侧边栏。您可以选择是否创建 PIN 码。默认值为 true。
路径

字符串可选

要使用的侧边栏 HTML 文件的路径。这必须是扩展程序包中的本地资源。
tabId

number 可选

如果指定了此 ID，则侧边栏选项将仅应用于具有此 ID 的标签页。如果省略，这些选项会设置默认行为（用于任何没有特定设置的标签页）。注意：如果为此 tabId 和默认 tabId 设置了相同的路径，则此 tabId 的面板将与默认 tabId 的面板不同。

Side

Chrome 140 及更高版本 browser.*（自 Chrome 148 起）

定义浏览器界面中侧边栏的可能对齐方式。

枚举

"left"

"right"

SidePanel

属性

default_path

字符串

开发者指定的侧边栏显示路径。

方法

close()

Chrome 141 及更高版本 browser.*（自 Chrome 148 起）

browser.sidePanel.close(
  options: CloseOptions,
): Promise<void>

关闭扩展程序的侧边栏。如果面板已关闭，则此操作无效。

参数

选项

CloseOptions

指定关闭侧边栏的上下文。

承诺<void>

返回一个 Promise，该 Promise 会在侧边栏关闭时解析。

getLayout()

Chrome 140 及更高版本 browser.*（自 Chrome 148 起）

browser.sidePanel.getLayout(): Promise<PanelLayout>

返回侧边栏的当前布局。

Promise<PanelLayout>

返回一个使用 PanelLayout 解析的 Promise。

getOptions()

browser.sidePanel.getOptions(
  options: GetPanelOptions,
): Promise<PanelOptions>

返回有效的面板配置。

参数

选项

GetPanelOptions

指定要返回其配置的上下文。

Promise<PanelOptions>

返回一个 Promise，该 Promise 会解析为活跃面板配置。

getPanelBehavior()

browser.sidePanel.getPanelBehavior(): Promise<PanelBehavior>

返回扩展程序的当前侧边栏行为。

Promise<PanelBehavior>

返回一个 Promise，该 Promise 会解析为扩展程序的侧边栏行为。

open()

Chrome 116 及更高版本 browser.*（自 Chrome 148 起）

browser.sidePanel.open(
  options: OpenOptions,
): Promise<void>

打开扩展程序的侧边栏。此方法只能在响应用户操作时调用。

参数

选项

OpenOptions

指定打开侧边栏的上下文。

承诺<void>

返回一个 Promise，该 Promise 会在侧边栏打开时解析。

setOptions()

browser.sidePanel.setOptions(
  options: PanelOptions,
): Promise<void>

配置侧边栏。

参数

选项

PanelOptions

要应用于面板的配置选项。

承诺<void>

返回一个 Promise，该 Promise 会在选项设置完毕后解析。

setPanelBehavior()

browser.sidePanel.setPanelBehavior(
  behavior: PanelBehavior,
): Promise<void>

配置扩展程序的侧边栏行为。这是一项 upsert 操作。

参数

为您提供数据分析

PanelBehavior

要设置的新行为。

承诺<void>

返回一个 Promise，该 Promise 会在新行为设置完成后解析。

事件

onClosed

Chrome 142 及更高版本 browser.*（自 Chrome 148 起）

browser.sidePanel.onClosed.addListener(
  callback: function,
)

在扩展程序的侧边栏关闭时触发。

参数

callback

函数

callback 参数如下所示：
```
(info: PanelClosedInfo) => void
```
- 信息
  
  PanelClosedInfo

onOpened

Chrome 141 及更高版本 browser.*（自 Chrome 148 起）

browser.sidePanel.onOpened.addListener(
  callback: function,
)

在扩展程序的侧边栏打开时触发。

参数

callback

函数

callback 参数如下所示：
```
(info: PanelOpenedInfo) => void
```
- 信息
  
  PanelOpenedInfo

browser.sidePanel 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

说明

权限

可用性

概念和用法

使用场景

在每个网站上显示相同的侧边栏

在特定网站上启用侧边栏

点击工具栏图标即可打开侧边栏

在用户互动时以程序化方式打开侧边栏

切换到其他面板

侧边栏用户体验

打开侧边栏

固定侧边栏

示例

类型

CloseOptions

属性

GetPanelOptions

属性

OpenOptions

属性

PanelBehavior

属性

PanelClosedInfo

属性

PanelLayout

属性

PanelOpenedInfo

属性

PanelOptions

属性

Side

枚举

SidePanel

属性

方法

close()

参数

返回

getLayout()

返回

getOptions()

参数

返回

getPanelBehavior()

返回

open()

参数

返回

setOptions()

参数

返回

setPanelBehavior()

参数

返回

事件

onClosed

参数

onOpened

参数

browser.sidePanel