说明
使用 chrome.sidePanel API 可将内容托管在浏览器侧边栏中的网页主要内容旁边。
权限
sidePanel要使用 Side Panel API，请在扩展程序 manifest 文件中添加 "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.tabs.onActivated.addListener(async ({ tabId }) => {
const { path } = await chrome.sidePanel.getOptions({ tabId });
if (path === welcomePage) {
chrome.sidePanel.setOptions({ path: mainPage });
}
});
如需查看完整示例，请参阅多个侧边栏。
侧边栏用户体验
用户会先看到 Chrome 的内置侧边栏。每个侧边栏都会在侧边栏菜单中显示相应扩展程序的图标。如果未添加任何图标，系统会显示占位符图标，且以扩展程序名称的第一个字母开头。
打开侧边栏
- 转到侧边栏菜单
- 用户可以在侧边栏菜单中找到可用的侧边栏。然后，从下拉菜单中选择所需的附加信息。
- 通过用户手势打开
您可以使用
sidePanel.open()和sidePanel.setPanelBehavior()通过用户互动来打开侧边栏，例如：
示例
如需更多 Side Panel API 扩展程序演示，请探索以下任一扩展程序：
类型
GetPanelOptions
属性
-
tabId
数字可选
如果指定，则返回给定标签页的侧边栏选项。否则，系统会返回默认的侧边栏选项（用于没有特定设置的任何标签页）。
OpenOptions
属性
-
tabId
数字可选
要打开侧边栏的标签页。如果相应标签页具有标签页专用的侧边栏，那么系统只会针对该标签页打开该面板。如果没有特定于标签页的面板，则全局面板将在指定的标签页中打开，并在任何其他标签页中打开，而不会有当前已打开的标签页专用面板。这会替换相应标签页中当前处于活动状态的所有侧边栏（全局或标签页特有的侧边栏）。必须至少提供此 ID 或
windowId中的一个。 -
windowId
数字可选
用于打开侧边栏的窗口。仅当扩展程序具有全局（非标签页专用）侧边栏或还指定了
tabId时，此方法才适用。这会覆盖用户在给定窗口中打开的任何当前处于有效状态的全局侧边栏。必须至少提供此 ID 或tabId中的一个。
PanelBehavior
属性
-
openPanelOnActionClick
布尔值 选填
是否点击扩展程序的图标是否会在侧边栏中显示相应扩展程序的条目。默认值为 false。
PanelOptions
属性
-
已启用
布尔值 选填
是否应启用侧边栏。您可以选择是否创建 PIN 码。默认值为 true。
-
path
字符串（可选）
要使用的侧边栏 HTML 文件的路径。该资源必须是扩展程序软件包中的本地资源。
-
tabId
数字可选
如果指定，侧边栏选项将仅应用于具有此 ID 的标签页。如果省略这些选项，系统会设置默认行为（用于没有特定设置的任何标签页）。注意：如果为此 tabId 和默认 tabId 设置了相同的路径，则此 tabId 的面板将不同于默认 tabId 的面板。
SidePanel
属性
-
default_path
string
开发者指定的侧边栏显示路径。
方法
getOptions()
chrome.sidePanel.getOptions(
options: GetPanelOptions,
callback?: function,
)
返回有效的面板配置。
参数
-
指定要返回其配置的上下文。
-
callback
函数（可选）
callback参数如下所示：(options: PanelOptions)=>void
-
选项
-
返回
-
Promise<PanelOptions>
Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。
getPanelBehavior()
chrome.sidePanel.getPanelBehavior(
callback?: function,
)
返回扩展程序当前的侧边栏行为。
参数
-
callback
函数（可选）
callback参数如下所示：(behavior: PanelBehavior)=>void
-
为您提供数据分析
-
返回
-
Promise<PanelBehavior>
Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。
open()
chrome.sidePanel.open(
options: OpenOptions,
callback?: function,
)
打开扩展程序的侧边栏。只能在响应用户操作时调用此方法。
参数
-
选项
指定在什么上下文中打开侧边栏。
-
callback
函数（可选）
callback参数如下所示：()=>void
返回
-
Promise<void>
Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。
setOptions()
chrome.sidePanel.setOptions(
options: PanelOptions,
callback?: function,
)
配置侧边栏。
参数
-
选项
要应用于面板的配置选项。
-
callback
函数（可选）
callback参数如下所示：()=>void
返回
-
Promise<void>
Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。
setPanelBehavior()
chrome.sidePanel.setPanelBehavior(
behavior: PanelBehavior,
callback?: function,
)
配置扩展程序的侧边栏行为。这是一项更新/插入操作。
参数
-
为您提供数据分析
要设置的新行为。
-
callback
函数（可选）
callback参数如下所示：()=>void
返回
-
Promise<void>
Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。