Эта страница переведена с помощью Cloud Translation API.

chrome.sidePanel

Описание

Используйте API chrome.sidePanel для размещения контента в боковой панели браузера рядом с основным содержимым веб-страницы.

Разрешения

sidePanel

Для использования API боковой панели добавьте разрешение "sidePanel" в файл манифеста расширения:

manifest.json:

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

Доступность

Chrome 114+ MV3+

Понятия и применение

API боковой панели позволяет расширениям отображать собственный пользовательский интерфейс на боковой панели, обеспечивая постоянное отображение элементов, дополняющих процесс просмотра веб-страниц пользователем.

Выпадающее меню боковой панели — Боковая панель пользовательского интерфейса браузера Chrome.

В числе особенностей можно отметить следующее:

Боковая панель остается открытой при переключении между вкладками (если такая настройка включена).
Оно может быть доступно только на определенных веб-сайтах.
Боковые панели, являясь расширением, имеют доступ ко всем API Chrome.
В настройках Chrome пользователи могут указать, с какой стороны должна отображаться панель.

Варианты использования

В следующих разделах показаны некоторые распространенные варианты использования API боковой панели. Полные примеры расширений см. в разделе «Примеры расширений».

Отображайте одну и ту же боковую панель на каждом сайте.

The side panel can be set initially from the "default_path" property in the "side_panel" key of the manifest to display the same side panel on every site. This should point to a relative path within the extension directory.

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>

Включить боковую панель на определенном сайте

An extension can use sidepanel.setOptions() to enable a side panel on a specific tab. This example uses chrome.tabs.onUpdated() to listen for any updates made to the tab. It checks if the URL is www.google.com and enables the side panel. Otherwise, it disables it.

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
    });
  }
});

When a user temporarily switches to a tab where the side panel is not enabled, the side panel will be hidden. It will automatically show again when the user switches to a tab where it was previously open.

Когда пользователь переходит на сайт, где боковая панель отключена, она закрывается, и расширение не отображается в выпадающем меню боковой панели.

Полный пример см. в образце боковой панели, специфичном для каждой вкладки .

Откройте боковую панель, щелкнув значок на панели инструментов.

Разработчики могут разрешить пользователям открывать боковую панель при нажатии на значок панели инструментов действий с помощью 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 introduces sidePanel.open() . It allows extensions to open the side panel through an extension user gesture, such as clicking on the action icon . Or a user interaction on an extension page or content script , such as clicking a button. For a complete demo, see the Open Side Panel sample extension.

The following code shows how to open a global side panel on the current window when the user clicks on a context menu. When using sidePanel.open() , you must choose the context in which it should open. Use windowId to open a global side panel. Alternatively, set the tabId to open the side panel only on a specific tab.

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 });
  }
});

Переключиться на другую панель

Extensions can use sidepanel.getOptions() to retrieve the current side panel. The following example sets a welcome side panel on runtime.onInstalled() . Then when the user navigates to a different tab, it replaces it with the main side panel.

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 });
  }
});

Полный код смотрите в примере "Несколько боковых панелей" .

Пользовательский интерфейс боковой панели

Users will see Chrome's built-in side panels first. Each side panel displays the extension's icon in the side panel menu. If no icons are included, it will show a placeholder icon with the first letter of the extension's name.

Откройте боковую панель

To allow users to open the side panel, use an action icon in combination with sidePanel.setPanelBehavior() . Alternatively, make a call to sidePanel.open() following a user interaction, such as:

клик действия
Сочетание клавиш
Контекстное меню
Жест пользователя на странице расширения или в скрипте контента.

Закрепите боковую панель

Значок булавки в боковой панели пользовательского интерфейса.

The side panel toolbar displays a pin icon when your side panel is open. Clicking the icon pins your extension's action icon. Clicking the action icon once pinned will perform the default action for your action icon and will only open the side panel if this has been explicitly configured.

Примеры

Для просмотра дополнительных демонстраций расширений Side Panel API, ознакомьтесь с любым из следующих расширений:

Типы

CloseOptions

Chrome 141+

Характеристики

tabId
число необязательно
Вкладка, в которой следует закрыть боковую панель. Если в указанной вкладке открыта боковая панель, специфичная для данной вкладки, она будет закрыта для этой вкладки. Необходимо указать хотя бы одно из значений: `this` или ` windowId .
windowId
число необязательно
The window in which to close the side panel. If a global side panel is open in the specified window, it will be closed for all tabs in that window where no tab-specific panel is active. At least one of this or tabId must be provided.

GetPanelOptions

Характеристики

tabId
число необязательно
Если указано иное, будут возвращены параметры боковой панели для данной вкладки. В противном случае возвращаются параметры боковой панели по умолчанию (используемые для любой вкладки, не имеющей специальных настроек).

OpenOptions

Chrome 116+

Характеристики

tabId
число необязательно
Вкладка, в которой будет открыта боковая панель. Если для соответствующей вкладки есть боковая панель, специфичная для этой вкладки, панель будет открыта только для этой вкладки. Если такой панели нет, глобальная панель будет открыта в указанной вкладке и во всех других вкладках, где в данный момент не открыта панель, специфичная для этой вкладки. Это переопределит любую активную в данный момент боковую панель (глобальную или специфичную для вкладки) в соответствующей вкладке. Необходимо указать хотя бы один из параметров: `this` или ` windowId .
windowId
число необязательно
The window in which to open the side panel. This is only applicable if the extension has a global (non-tab-specific) side panel or tabId is also specified. This will override any currently-active global side panel the user has open in the given window. At least one of this or tabId must be provided.

PanelBehavior

Характеристики

openPanelOnActionClick
логический необязательный
Определяет, будет ли при нажатии на значок расширения отображаться его запись в боковой панели. По умолчанию — false.

PanelClosedInfo

Chrome 142+

Характеристики

путь
нить
Путь к локальному ресурсу внутри пакета расширения, содержимое которого отображается на панели.
tabId
число необязательно
Необязательный идентификатор вкладки, на которой была закрыта боковая панель. Он предоставляется только в том случае, если панель привязана к конкретной вкладке.
windowId
число
Идентификатор окна, в котором была закрыта боковая панель. Эта информация доступна как для глобальных панелей, так и для панелей, специфичных для отдельных вкладок.

PanelLayout

Chrome 140+

Характеристики

сторона
Сторона

PanelOpenedInfo

Chrome 141+

Характеристики

путь
нить
Путь к локальному ресурсу внутри пакета расширения, содержимое которого отображается на панели.
tabId
число необязательно
Необязательный идентификатор вкладки, на которой открывается боковая панель. Он указывается только в том случае, если панель привязана к конкретной вкладке.
windowId
число
Идентификатор окна, в котором открыта боковая панель. Эта информация доступна как для глобальных панелей, так и для панелей, специфичных для отдельных вкладок.

PanelOptions

Характеристики

включено
логический необязательный
Включить ли боковую панель. Этот параметр необязателен. Значение по умолчанию — true.
путь
строка необязательный
Путь к HTML-файлу боковой панели, который необходимо использовать. Это должен быть локальный ресурс внутри пакета расширения.
tabId
число необязательно
If specified, the side panel options will only apply to the tab with this id. If omitted, these options set the default behavior (used for any tab that doesn't have specific settings). Note: if the same path is set for this tabId and the default tabId, then the panel for this tabId will be a different instance than the panel for the default tabId.

Side

Chrome 140+

Определяет возможное выравнивание боковой панели в пользовательском интерфейсе браузера.

Перечисление

"левый"

"верно"

SidePanel

Характеристики

default_path
нить
Разработчик указал путь для отображения боковой панели.

Методы

getLayout()

Chrome 140+

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

Возвращает текущую компоновку боковой панели.

Возвраты

Promise< PanelLayout >
Возвращает Promise, который разрешается с помощью PanelLayout .

getOptions()

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

Возвращает конфигурацию активной панели.

Параметры

параметры
GetPanelOptions
Указывает контекст, для которого следует вернуть конфигурацию.

Возвраты

Promise< PanelOptions >
Возвращает промис, который разрешается с активной конфигурацией панели.

getPanelBehavior()

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

Возвращает текущее поведение боковой панели расширения.

Возвраты

Promise< PanelBehavior >
Возвращает промис, который разрешается в соответствии с поведением боковой панели расширения.

open()

Chrome 116+

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

Открывает боковую панель расширения. Эта функция может вызываться только в ответ на действие пользователя.

Параметры

параметры
Открытые параметры
Указывает контекст, в котором следует открыть боковую панель.

Возвраты

Обещание<пустота>
Возвращает промис, который разрешается после открытия боковой панели.

setOptions()

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

Настраивает боковую панель.

Параметры

параметры
PanelOptions
Параметры конфигурации, применяемые к панели.

Возвраты

Обещание<пустота>
Возвращает промис, который разрешается после установки параметров.

setPanelBehavior()

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

Настраивает поведение боковой панели расширения. Это операция обновления/вставки.

Параметры

поведение
PanelBehavior
Новое поведение, которое необходимо установить.

Возвраты

Обещание<пустота>
Возвращает промис, который разрешается после установки нового поведения.

События

onClosed

В ожидании

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

Срабатывает при закрытии боковой панели расширения.

Параметры

перезвонить
функция
Параметр callback выглядит следующим образом:
```
(info: PanelClosedInfo) => void
```
- информация
  PanelClosedInfo

onOpened

Chrome 141+

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

Срабатывает при открытии боковой панели расширения.

Параметры

перезвонить
функция
Параметр callback выглядит следующим образом:
```
(info: PanelOpenedInfo) => void
```
- информация
  PanelOpenedInfo

chrome.sidePanel Оптимизируйте свои подборки Сохраняйте и классифицируйте контент в соответствии со своими настройками.

Описание

Разрешения

Доступность

Понятия и применение

Варианты использования

Отображайте одну и ту же боковую панель на каждом сайте.

Включить боковую панель на определенном сайте

Откройте боковую панель, щелкнув значок на панели инструментов.

Программное открытие боковой панели при взаимодействии с пользователем

Переключиться на другую панель

Пользовательский интерфейс боковой панели

Откройте боковую панель

Закрепите боковую панель

Примеры

Типы

CloseOptions

Характеристики

GetPanelOptions

Характеристики

OpenOptions

Характеристики

PanelBehavior

Характеристики

PanelClosedInfo

Характеристики

PanelLayout

Характеристики

PanelOpenedInfo

Характеристики

PanelOptions

Характеристики

Side

Перечисление

SidePanel

Характеристики

Методы

getLayout()

Возвраты

getOptions()

Параметры

Возвраты

getPanelBehavior()

Возвраты

open()

Параметры

Возвраты

setOptions()

Параметры

Возвраты

setPanelBehavior()

Параметры

Возвраты

События

onClosed

Параметры

onOpened

Параметры

chrome.sidePanel