Chrome теперь поддерживает стандартизированное пространство имен browser.* (доступно начиная с Chrome 148). Мы постепенно обновляем документацию. Подробнее читайте в нашем руководстве по переходу .

Чтобы переводить контент на ваш предпочитаемый язык, Google использует технологии на основе искусственного интеллекта. Переводы от ИИ могут содержать ошибки.

browser.sidePanel

Описание

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

Разрешения

sidePanel

Чтобы использовать Side Panel API, добавьте разрешение "sidePanel" в файл манифеста расширения:

manifest.json:

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

Доступность

Chrome 114 и более поздних версий MV3 и более поздних версий

Основные понятия и использование

Side Panel API позволяет расширениям показывать собственный интерфейс на боковой панели, чтобы пользователи могли работать с ними, не отвлекаясь от просмотра веб-страниц.

Раскрывающееся меню боковой панели — Интерфейс боковой панели браузера Chrome.

Вот некоторые из них:

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

Примеры использования

В следующих разделах показаны некоторые распространенные варианты использования Side Panel 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(), чтобы включить боковую панель на определенной вкладке. В этом примере используется browser.tabs.onUpdated() для прослушивания любых обновлений, внесенных на вкладку. Оно проверяет, соответствует ли URL адресу www.google.com, и включает боковую панель. В противном случае она отключается.

service-worker.js:

const GOOGLE_ORIGIN = 'https://www.google.com';

browser.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 browser.sidePanel.setOptions({
      tabId,
      path: 'sidepanel.html',
      enabled: true
    });
  } else {
    // Disables the side panel on all other sites
    await browser.sidePanel.setOptions({
      tabId,
      enabled: false
    });
  }
});

Если пользователь временно переключится на вкладку, где боковая панель не включена, она будет скрыта. Она автоматически появится снова, когда пользователь перейдет на вкладку, где она была открыта ранее.

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

Полный пример можно найти в разделе Боковая панель для определенной вкладки.

Чтобы открыть боковую панель, нажмите на значок на панели инструментов.

Разработчики могут разрешить пользователям открывать боковую панель, нажимая на значок панели инструментов действий с помощью sidePanel.setPanelBehavior(). Сначала объявите ключ "action" в манифесте:

manifest.json:

{
  "name": "My side panel extension",
  ...
  "action": {
    "default_title&quot;: "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
browser.sidePanel
  .setPanelBehavior({ openPanelOnActionClick: true })
  .catch((>error) = console.error(error));
...

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

В Chrome 116 появился sidePanel.open(). Оно позволяет расширениям открывать боковую панель с помощью жеста пользователя, например нажатия на значок действия. или взаимодействие пользователя со страницей расширения или скриптом контента, например нажатие кнопки. Полную демонстрацию можно посмотреть в примере расширения Open Side Panel.

В примере ниже показано, как открыть глобальную боковую панель в текущем окне, когда пользователь нажимает на контекстное меню. При использовании sidePanel.open() необходимо выбрать контекст, в котором он должен открываться. Используйте windowId, чтобы открыть глобальную боковую панель. Вы также можете настроить tabId так, чтобы боковая панель открывалась только на определенной вкладке.

service-worker.js:

browser.runtime.onInstalled.addListener(() => {
  browser.contextMenus.create({
    id: 'openSidePanel',
    title: 'Open side panel',
    contexts: ['all']
  });
});

browser.contextMenus.onClicked.addListener((info, tab) => {
  if (info.menuItemId === 'openSidePanel') {
    // This will open the panel in all the pages on the current window.
    browser.sidePanel.open({ windowId: tab.windowId });
  }
});

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

Расширения могут использовать sidepanel.getOptions(), чтобы получить текущую боковую панель. В следующем примере показано, как настроить боковую панель приветствия в событии runtime.onInstalled(). Когда пользователь переходит на другую вкладку, она заменяется основной боковой панелью.

service-worker.js:

const welcomePage = 'sidepanels/welcome-sp.html';
const mainPage = 'sidepanels/main-sp.html';

browser.runtime.onInstalled.addListener(() => {
  browser.sidePanel.setOptions({ path: welcomePage });
  browser.sidePanel.setPanelBehavior({ openPanelOnActionClick: true });
});

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

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

Как работает боковая панель

Пользователи сначала увидят встроенные боковые панели Chrome. В меню боковой панели показывается значок расширения. Если значков нет, будет показан значок-плейсхолдер с первой буквой названия расширения.

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

Чтобы пользователи могли открывать боковую панель, используйте значок действия в сочетании с sidePanel.setPanelBehavior(). Вы также можете вызвать sidePanel.open() после взаимодействия с пользователем, например:

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

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

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

Примеры

Чтобы посмотреть другие примеры расширений с Side Panel API, изучите следующие расширения:

Типы

CloseOptions

Chrome 141 и более поздних версий

Свойства

tabId

number (необязательно)

Вкладка, на которой нужно закрыть боковую панель. Если на указанной вкладке открыта боковая панель, она будет закрыта. Если открыта только глобальная боковая панель, объект Promise, возвращенный вызовом close(), отклонит запрос с ошибкой. В Chrome 145 это поведение было изменено, а в предыдущих версиях закрывалась глобальная панель. Необходимо указать значение этого поля или поля windowId.
windowId

number (необязательно)

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

GetPanelOptions

Свойства

tabId

number (необязательно)

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

OpenOptions

Chrome 116 и более поздних версий

Свойства

tabId

number (необязательно)

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

number (необязательно)

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

PanelBehavior

Свойства

openPanelOnActionClick

Логическое значение (необязательно)

Будет ли нажатие на значок расширения переключать показ записи расширения на боковой панели. Значение по умолчанию – false.

PanelClosedInfo

Chrome 142 и более поздних версий

Свойства

путь

string

Путь к локальному ресурсу в пакете расширения, контент которого показывается на панели.
tabId

number (необязательно)

Необязательный идентификатор вкладки, на которой была закрыта боковая панель. Этот параметр указывается, только если панель относится к определенной вкладке.
windowId

число

Идентификатор окна, в котором была закрыта боковая панель. Это доступно как для глобальных панелей, так и для панелей на отдельных вкладках.

PanelLayout

Chrome 140+

Свойства

side

Side

PanelOpenedInfo

Chrome 141 и более поздних версий

Свойства

путь

string

Путь к локальному ресурсу в пакете расширения, контент которого показывается на панели.
tabId

number необязательно

Необязательный идентификатор вкладки, на которой открыта боковая панель. Этот параметр указывается, только если панель относится к определенной вкладке.
windowId

число

Идентификатор окна, в котором открыта боковая панель. Это доступно как для глобальных панелей, так и для панелей на уровне вкладки.

PanelOptions

Свойства

включено

Логическое значение (необязательно)

Включение боковой панели. Это необязательная настройка. Значение по умолчанию – true.
путь

Строка (необязательно)

Путь к HTML-файлу боковой панели. Это должен быть локальный ресурс в пакете расширения.
tabId

number (необязательно)

Если указано, настройки боковой панели будут применяться только к вкладке с этим идентификатором. Если эти параметры не указаны, они задают режим работы по умолчанию (используется для любой вкладки, у которой нет определенных настроек). Примечание. Если для этого tabId и tabId по умолчанию задан один и тот же путь, то панель для этого tabId будет отличаться от панели для tabId по умолчанию.

Side

Chrome 140+

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

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

"left"

"right"

SidePanel

Свойства

default_path

string

Путь, указанный разработчиком для отображения боковой панели.

Методы

close()

Chrome 141 и более поздних версий

chrome.sidePanel.close(
  options: CloseOptions,
): Promise<void>

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

Параметры

Параметры

CloseOptions

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

Возвраты

Promise<void>

Возвращает объект Promise, который распознается, когда боковая панель закрыта.

getLayout()

Chrome 140+

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

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

Возвраты

Promise<PanelLayout>

Возвращает объект Promise, который распознается с помощью PanelLayout.

getOptions()

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

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

Параметры

Параметры

GetPanelOptions

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

Возвраты

Promise<PanelOptions>

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

getPanelBehavior()

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

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

Возвраты

Promise<PanelBehavior>

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

open()

Chrome 116 и более поздних версий

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

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

Параметры

Параметры

OpenOptions

Указывает контекст, в котором открывается боковая панель.

Возвраты

Promise<void>

Возвращает Promise, который разрешается, когда боковая панель открыта.

setOptions()

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

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

Параметры

Параметры

PanelOptions

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

Возвраты

Promise<void>

Возвращает объект Promise, который распознается, когда заданы параметры.

setPanelBehavior()

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

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

Параметры

поможет узнать о поведении потребителей,

PanelBehavior

Новое поведение, которое нужно задать.

Возвраты

Promise<void>

Возвращает объект Promise, который распознается, когда задано новое поведение.

События

onClosed

Chrome 142 и более поздних версий

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

Срабатывает, когда боковая панель расширения закрыта.

Параметры

обратный вызов

function

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

onOpened

Chrome 141 и более поздних версий

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

Срабатывает, когда открывается боковая панель расширения.

Параметры

обратный вызов

function

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

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

Описание

Разрешения

Доступность

Основные понятия и использование

Примеры использования

Показывать одну и ту же боковую панель на всех сайтах

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

Чтобы открыть боковую панель, нажмите на значок на панели инструментов.

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

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

Как работает боковая панель

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

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

Примеры

Типы

CloseOptions

Свойства

GetPanelOptions

Свойства

OpenOptions

Свойства

PanelBehavior

Свойства

PanelClosedInfo

Свойства

PanelLayout

Свойства

PanelOpenedInfo

Свойства

PanelOptions

Свойства

Side

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

SidePanel

Свойства

Методы

close()

Параметры

Возвраты

getLayout()

Возвраты

getOptions()

Параметры

Возвраты

getPanelBehavior()

Возвраты

open()

Параметры

Возвраты

setOptions()

Параметры

Возвраты

setPanelBehavior()

Параметры

Возвраты

События

onClosed

Параметры

onOpened

Параметры

browser.sidePanel