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+

Свойства

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

onOpened

Chrome 141 и более поздних версий 
chrome.sidePanel.onOpened.addListener(
  callback: function,
)

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

Параметры

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

    function

    Параметр callback выглядит следующим образом: 

    (info: PanelOpenedInfo) => void