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，扩展程序可以在侧边栏中显示自己的界面，从而提供持久的体验，补充用户的浏览历程。

<ph type="x-smartling-placeholder">
</ph> 侧边栏下拉菜单 <ph type="x-smartling-placeholder">
</ph> Chrome 浏览器侧边栏界面。

部分功能包括：

  • 在标签页之间导航时，侧边栏会保持打开状态（如果已设置为打开）。
  • 它只能在特定网站上提供。
  • 作为扩展程序页面，侧边栏可以访问所有 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.sidePanel.setPanelBehavior({ openPanelOnActionClick: true });
});

chrome.tabs.onActivated.addListener(async ({ tabId }) => {
  const { path } = await chrome.sidePanel.getOptions({ tabId });
  if (path === welcomePage) {
    chrome.sidePanel.setOptions({ path: mainPage });
  }
});

如需查看完整代码，请参阅多个侧边栏示例。

侧边栏用户体验

用户会先看到 Chrome 的内置侧边栏。每个侧边栏都会在侧边栏菜单中显示相应扩展程序的图标。如果未添加任何图标，系统会显示一个占位符图标，其中包含扩展程序名称的首字母。

打开侧边栏

若要允许用户打开侧边栏，请结合使用“操作”图标 与 sidePanel.setPanelBehavior() 共享。或者，在用户互动之后调用 sidePanel.open()，例如：

固定侧边栏

<ph type="x-smartling-placeholder">
</ph> 侧边栏界面中的固定图标。 <ph type="x-smartling-placeholder">
</ph> 侧边栏界面中的固定图标。

侧边栏处于打开状态时，侧边栏工具栏会显示一个图钉图标。 点击该图标即可固定该扩展程序的操作图标。点击操作图标 固定后，系统会对您的操作图标执行默认操作， 打开侧边栏（如果已明确配置）。

示例

如需查看更多 Side Panel API 扩展程序演示，请探索以下任一扩展程序：

类型

GetPanelOptions

属性

  • tabId

    编号（选填）

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

OpenOptions

Chrome 116 及更高版本

属性

  • tabId

    编号（选填）

    要打开侧边栏的标签页。如果相应标签页有专属于标签页的侧边栏，那么系统只会为该标签页打开侧边栏。如果没有特定于标签页的面板，则系统会在指定标签页中打开全局面板，否则会在没有当前打开的标签页特有的面板的任何其他标签页中打开全局面板。这会覆盖相应标签页中当前处于活动状态的所有侧边栏（全局或特定于标签页的侧边栏）。必须至少提供其中一个或 windowId。

  • windowId

    编号（选填）

    要在其中打开侧边栏的窗口。仅当扩展程序具有全局（非标签页专用）侧边栏或指定了 tabId 时，这种情况才适用。这将替换用户在给定窗口中打开的任何当前处于活跃状态的全局侧边栏。必须至少提供其中一个或 tabId。

PanelBehavior

属性

  • openPanelOnActionClick

    布尔值（可选）

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

PanelOptions

属性

  • 已启用

    布尔值（可选）

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

  • 路径

    字符串（可选）

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

  • tabId

    编号（选填）

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

SidePanel

属性

  • default_path

    字符串

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

方法

getOptions()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.sidePanel.getOptions(
  options: GetPanelOptions,
  callback?: function,
)

返回有效的面板配置。

参数

返回

  • Promise&lt;PanelOptions&gt;

    Manifest V3 及更高版本支持 Promise，但为以下项目提供回调： 向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。

getPanelBehavior()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.sidePanel.getPanelBehavior(
  callback?: function,
)

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

参数

  • callback

    函数（可选）

    callback 参数如下所示： 

    (behavior: PanelBehavior) => void

返回

  • Promise&lt;PanelBehavior&gt;

    Manifest V3 及更高版本支持 Promise，但为以下项目提供回调： 向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。

open()

<ph type="x-smartling-placeholder"></ph> 承诺 Chrome 116 及更高版本 
chrome.sidePanel.open(
  options: OpenOptions,
  callback?: function,
)

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

参数

  • 选项

    OpenOptions

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

  • callback

    函数（可选）

    callback 参数如下所示： 

    () => void

返回

  • 承诺<void>

    Manifest V3 及更高版本支持 Promise，但为以下项目提供回调： 向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。

setOptions()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.sidePanel.setOptions(
  options: PanelOptions,
  callback?: function,
)

配置侧边栏。

参数

  • 选项

    PanelOptions

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

  • callback

    函数（可选）

    callback 参数如下所示： 

    () => void

返回

  • 承诺<void>

    Manifest V3 及更高版本支持 Promise，但为以下项目提供回调： 向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。

setPanelBehavior()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.sidePanel.setPanelBehavior(
  behavior: PanelBehavior,
  callback?: function,
)

配置扩展程序的侧边栏行为。这是一项更新/插入操作。

参数

  • 为您提供数据分析

    PanelBehavior

    要设置的新行为。

  • callback

    函数（可选）

    callback 参数如下所示： 

    () => void

返回

  • 承诺<void>

    Manifest V3 及更高版本支持 Promise，但为以下项目提供回调： 向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。