侧边栏

侧边栏是在浏览器窗口侧面显示的面板,位于网页旁边。此页面描述了侧边栏,包括指定侧边栏、设计侧边栏以及使用示例。

浏览器提供了一个用户界面,允许用户选择要显示的侧边栏。例如,Firefox 具有“查看”>“侧边栏”菜单。每个浏览器窗口可以显示自己的侧边栏,该侧边栏显示在窗口中的每个选项卡上。

浏览器可能包含许多内置侧边栏。例如,Firefox 包含一个用于与书签交互的侧边栏。

Annotator sidebar with a box allowing the user to take notes about the page.

使用sidebar_action 清单文件键,扩展程序可以向浏览器添加自己的侧边栏。它将与内置侧边栏一起列出,用户可以使用与内置侧边栏相同的机制打开它。

与浏览器操作弹出窗口类似,侧边栏的内容指定为 HTML 文档。当用户打开侧边栏时,侧边栏的文档会加载到每个打开的浏览器窗口中。每个窗口都会获得文档自己的实例。当打开新窗口时,它们也会获得自己的侧边栏文档。

可以使用sidebarAction.setPanel() 函数设置特定选项卡的文档。侧边栏可以使用windows.getCurrent() API 确定它属于哪个窗口。

js
// sidebar.js
browser.windows.getCurrent({ populate: true }).then((windowInfo) => {
  myWindowId = windowInfo.id;
});

如果侧边栏希望为不同的窗口显示不同的内容,这将非常有用。有关此示例,请参阅“annotate-page”示例

侧边栏文档可以访问扩展的后台和弹出窗口脚本获得的相同一组特权 JavaScript API。它们可以使用runtime.getBackgroundPage() 直接访问后台页面(除非侧边栏属于隐身模式窗口),并且可以使用tabs.sendMessage()runtime.sendNativeMessage() 等消息传递 API 与内容脚本或原生应用程序交互。

当其浏览器窗口关闭或用户关闭侧边栏时,侧边栏文档将被卸载。这意味着与后台页面不同,侧边栏文档不会一直保持加载状态,但与浏览器操作弹出窗口不同,它们在用户与网页交互时会保持加载状态。

首次安装定义侧边栏的扩展时,其侧边栏将自动打开。这旨在帮助用户了解扩展包含侧边栏。请注意,扩展程序无法以编程方式打开侧边栏:侧边栏只能由用户打开。

指定侧边栏

要指定侧边栏,请使用sidebar_action 清单文件键定义默认文档,以及默认标题和图标。

json
"sidebar_action": {
  "default_title": "My sidebar",
  "default_panel": "sidebar.html",
  "default_icon": "sidebar_icon.png"
}

可以使用sidebarAction API 以编程方式更改标题、面板和图标。

标题和图标显示在浏览器提供的任何用于列出侧边栏的用户界面中,例如 Firefox 中的“查看”>“侧边栏”菜单。

有关如何设计侧边栏网页以匹配 Firefox 样式的详细信息,请参阅Acorn 设计系统 文档。

示例

GitHub 上的webextensions-examples 存储库包含annotate-page 示例,该示例实现了侧边栏。