Эта страница переведена с помощью 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 боковой панели. Полные примеры расширений см. в разделе «Примеры расширений».

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

Боковая панель может быть изначально настроена с помощью свойства "default_path" в ключе "side_panel" манифеста, чтобы отображать одну и ту же боковую панель на всех сайтах. Этот путь должен указывать на относительный путь внутри каталога расширения.

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() для отслеживания любых обновлений, внесенных во вкладку. Он проверяет, является ли URL-адрес 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() после взаимодействия пользователя, например:

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

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

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

На боковой панели инструментов отображается значок булавки, когда боковая панель открыта. Щелчок по значку закрепляет значок действия вашего расширения. Щелчок по закрепленному значку действия выполнит действие по умолчанию для вашего значка действия и откроет боковую панель только в том случае, если это было явно настроено.

Примеры

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

Типы

CloseOptions

Chrome 141+

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

tabId
число необязательно
Вкладка, в которой следует закрыть боковую панель. Если в указанной вкладке открыта боковая панель, специфичная для данной вкладки, она будет закрыта для этой вкладки. Необходимо указать хотя бы одно из значений: `this` или ` windowId .
windowId
число необязательно
Окно, в котором следует закрыть боковую панель. Если в указанном окне открыта глобальная боковая панель, она будет закрыта для всех вкладок в этом окне, где не активна ни одна панель, специфичная для данной вкладки. Необходимо указать хотя бы одно из значений: this или tabId .

GetPanelOptions

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

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

OpenOptions

Chrome 116+

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

tabId
число необязательно
Вкладка, в которой будет открыта боковая панель. Если для соответствующей вкладки есть боковая панель, специфичная для этой вкладки, панель будет открыта только для этой вкладки. Если такой панели нет, глобальная панель будет открыта в указанной вкладке и во всех других вкладках, где в данный момент не открыта панель, специфичная для этой вкладки. Это переопределит любую активную в данный момент боковую панель (глобальную или специфичную для вкладки) в соответствующей вкладке. Необходимо указать хотя бы один из параметров: `this` или ` windowId .
windowId
число необязательно
Окно, в котором будет открыта боковая панель. Это применимо только в том случае, если расширение имеет глобальную (не привязанную к вкладке) боковую панель или указан tabId . Это переопределит любую текущую активную глобальную боковую панель, открытую пользователем в данном окне. Необходимо указать хотя бы один из параметров: this или tabId .

PanelBehavior

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

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

PanelClosedInfo

Chrome 142+

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

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

PanelLayout

Chrome 140+

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

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

PanelOpenedInfo

Chrome 141+

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

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

PanelOptions

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

включено
логический необязательный
Включить ли боковую панель. Этот параметр необязателен. Значение по умолчанию — true.
путь
строка необязательный
Путь к HTML-файлу боковой панели, который необходимо использовать. Это должен быть локальный ресурс внутри пакета расширения.
tabId
число необязательно
Если указано, параметры боковой панели будут применяться только к вкладке с этим идентификатором. Если не указано, эти параметры задают поведение по умолчанию (используется для любой вкладки, не имеющей специальных настроек). Примечание: если для этого tabId и tabId по умолчанию указан один и тот же путь, то панель для этого tabId будет представлять собой другой экземпляр, чем панель для 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 144+

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