为 Microsoft Edge 边栏开发扩展

作为Microsoft Edge 扩展开发人员，你可以将新的或现有的 Microsoft Edge 扩展显示在边栏中。除其他 UI 外，任何扩展都可以使用边栏。

详细内容：

简介
- 术语
概念和用法
在清单文件中添加 sidePanel 权限
侧面板 API 的用例
侧边栏用户体验
- 在边栏中打开扩展
扩展示例
类型和方法
另请参阅

简介

使用 chrome.sidePanel API 将内容与网页的主要内容一起托管在 Microsoft Edge 的边栏中。

作为Microsoft Edge 扩展开发人员，你可以将新的或现有的 Microsoft Edge 扩展显示在边栏中。除其他 UI 外，任何扩展都可以使用边栏。

Microsoft Edge 扩展的边栏

通过使用侧面板 API，可以通过让用户在网页的主要内容旁查看其他信息来增强浏览体验。

边栏是位于 Microsoft Edge 一侧的持久窗格。边栏窗格与浏览器的主要内容共存。边栏减少了在选项卡之间不断切换的需要，从而获得更高效的浏览体验。

扩展可以选择使用侧面板 API 在 Microsoft Edge 边栏中显示自定义 UI。此外，扩展可以继续出现在 Microsoft Edge 工具栏中，以及 UI（如弹出窗口），并且可以注入脚本。

术语

Term	定义
侧面板 API	可在 Microsoft Edge 扩展中使用的功能的名称。 Chrome UI 使用术语侧面板。
`sidePanel` 或 `side_panel`	API 的名称以及启用任何扩展作为边栏扩展的权限。
边栏扩展	边栏中具有 UI 的 Microsoft Edge 扩展。

概念和用法

侧面板 API 允许扩展在 Microsoft Edge 边栏中显示自己的 UI，从而提供对用户浏览旅程进行补充的持久体验。

Edge 浏览器边栏 UI

与其他扩展资源一样，边栏中显示的 HTML 页面在扩展源的受信任扩展上下文中运行， (extension://<id>) 。侧栏具有与其他受信任的扩展上下文相同的 API 访问权限。

所有现有扩展 API 都可用于边栏扩展，因此你可以在启用边栏的扩展中利用扩展框架的所有当前功能。

边栏的一些功能包括：

在选项卡之间导航时，边栏将保持打开状态。
- 已知问题：当用户切换到以前打开边栏的选项卡时，边栏不会再次自动显示 (问题 #142) 。
边栏中的扩展可用于特定网站。
边栏中的扩展可以访问 Microsoft Edge 扩展支持的所有 API。
在 Microsoft Edge 设置中，用户可以指定多个边栏设置。

在清单文件中添加 sidePanel 权限

若要使用侧面板 API，请在 "sidePanel" 扩展的清单文件中添加权限， (manifest.json) ：

{
  ...
  "name": "My sidebar extension",
  ...
  "side_panel": {
    "default_path": "sidepanel.html"
  },
  "permissions": [
    "sidePanel"
  ]
   ...
}

Microsoft Edge 的每个扩展都有一个名为 manifest.json的 JSON 格式的清单文件。清单文件是扩展的蓝图。

每个示例都包含一个完整的清单文件;请参阅下面的扩展示例。

另请参阅：

扩展的清单文件格式

侧面板 API 的用例

以下部分演示侧面板 API 的一些常见用例。

有关完整的扩展示例，请参阅下面的扩展示例。

可以将边栏设置为默认值，以在所有打开的浏览器选项卡中显示相同的扩展。默认值在浏览器会话中保留。

在中 manifest.json， "default_path" 定义键，例如 "sidepanel.html"：

{
  "name": "My sidebar extension",
  ...
  "side_panel": {
    "default_path": "sidepanel.html"
  }
  ...
}

指定为默认值的文件（如 sidepanel.html）将显示在所有打开的浏览器选项卡中：

<!DOCTYPE html>
<html>
  <head>
    <title>Global side panel</title>
  </head>
  <body>
    <h1>All sites sidepanel extension</h1>
    <p>This side panel is enabled on all sites</p>
  </body>
</html>

另请参阅：

GoogleChrome/chrome-extensions-samples 存储库中的全局侧面板示例。

扩展可以使用 sidepanel.setOptions () 在特定选项卡上启用边栏。这可以是特定的网站，因此当用户转到此网站时，扩展将在边栏中打开。

此示例使用 chrome.tabs.onUpdated () 侦听对选项卡所做的任何更新。它会检查 URL 是否为 www.bing.com ，如果是，则启用边栏。否则，它将禁用边栏。

service-worker.js:

const BING_ORIGIN = 'https://www.bing.com';

chrome.tabs.onUpdated.addListener(async (tabId, info, tab) => {
  if (!tab.url) return;
  const url = new URL(tab.url);
  // Enables the sidebar when at bing.com
  if (url.origin === BING_ORIGIN) {
    await chrome.sidePanel.setOptions({
      tabId,
      path: 'sidepanel.html',
      enabled: true
    });
  } else {
    // Disables the sidebar when at other sites
    await chrome.sidePanel.setOptions({
      tabId,
      enabled: false
    });
  }
});

在 addListener()中，我们执行以下操作：

测试 url.origin 它是否是所需的选项卡。
在中 sidePanel.setOptions()，将设置为 enabledtrue 或 false。

当用户切换到未启用边栏的选项卡或站点时，将隐藏边栏。

已知问题：当用户切换到以前打开边栏的选项卡时，边栏不会再次自动显示 (问题 #142) 。

有关完整示例，请参阅特定于站点的侧面板示例。

若要允许用户通过单击操作工具栏图标打开边栏，请使用 sidePanel.setPanelBehavior () 。首先，在 "action" 中 manifest.json声明密钥：

{
  "name": "My sidebar extension",
  ...
   "action": {
    "default_title": "Click to open sidebar"
  },
  ...
}

然后，将以下代码添加到 service-worker.js 上面的 “仅为特定网站启用侧边栏”中的代码列表：

// Allow users to open the sidebar by clicking the action toolbar icon
chrome.sidePanel
  .setPanelBehavior({ openPanelOnActionClick: true })
  .catch((error) => console.error(error));

sidePanel.open () 允许扩展通过用户手势（例如单击操作图标）或通过扩展页面或内容脚本上的任意用户交互（例如单击按钮）打开边栏。

以下代码演示如何在用户单击上下文菜单时打开当前窗口中的全局边栏。使用 sidePanel.open()时，选择应在其中打开边栏的上下文：

使用 windowId 打开全局边栏，如以下示例所示。
或者，将设置为 tabId 仅在特定选项卡上打开边栏。

// service-worker.js:
chrome.runtime.onInstalled.addListener(() => {
  chrome.contextMenus.create({
    id: 'openSidePanel',
    title: 'Open sidebar',
    contexts: ['all']
  });
});

chrome.contextMenus.onClicked.addListener((info, tab) => {
  if (info.menuItemId === 'openSidePanel') {
    // Open the sidebar in all the tabs of the current window.
    chrome.sidePanel.open({ windowId: tab.windowId });
  }
});

有关完整演示，请参阅通过用户交互打开侧面板。

扩展可以使用 sidepanel.getOptions () 检索当前边栏，然后为特定选项卡启用其他边栏。

本示例设置一个边栏，其中包含 runtime.onInstalled () 上的欢迎消息。当用户导航到其他选项卡时，边栏将替换为浏览器级别的边栏。

// service-worker.js:
const welcomePage = 'sidebar/welcome-sb.html';
const mainPage = 'sidebar/main-sb.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 });
  }
});

有关完整代码，请参阅多个侧面板示例。

为 Microsoft Edge 边栏开发扩展具有这些用户体验 (UX) 功能。

若要允许用户打开边栏，请执行下列操作之一：