Описание
Используйте API chrome.sidePanel
для размещения контента на боковой панели браузера рядом с основным содержимым веб-страницы.
Разрешения
sidePanel
Чтобы использовать API боковой панели, добавьте разрешение "sidePanel"
в файл манифеста расширения:
манифест.json:
{
"name": "My side panel extension",
...
"permissions": [
"sidePanel"
]
}
Доступность
Концепции и использование
API боковой панели позволяет расширениям отображать собственный пользовательский интерфейс на боковой панели, обеспечивая постоянное взаимодействие, дополняющее путешествие пользователя в Интернете.
![Выпадающее меню боковой панели](https://developer.chrome.com/static/docs/extensions/reference/api/sidePanel/images/example-side-panel.png?authuser=5&hl=ru)
Некоторые функции включают в себя:
- Боковая панель остается открытой при переходе между вкладками (если это разрешено).
- Он может быть доступен только на определенных сайтах.
- В качестве страницы расширения боковые панели имеют доступ ко всем API Chrome.
- В настройках Chrome пользователи могут указать, на какой стороне должна отображаться панель.
Случаи использования
В следующих разделах демонстрируются некоторые распространенные случаи использования API боковой панели. Полные примеры расширений см. в разделе «Примеры расширений».
Отображать одну и ту же боковую панель на каждом сайте
Боковую панель можно изначально настроить с помощью свойства "default_path"
в ключе "side_panel"
манифеста, чтобы отображать одну и ту же боковую панель на каждом сайте. Это должно указывать на относительный путь в каталоге расширения.
манифест.json:
{
"name": "My side panel extension",
...
"side_panel": {
"default_path": "sidepanel.html"
}
...
}
боковая панель.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 , и включает боковую панель. В противном случае он отключает его.
сервис-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"
в манифесте:
манифест.json:
{
"name": "My side panel extension",
...
"action": {
"default_title": "Click to open panel"
},
...
}
Теперь добавьте этот код к предыдущему примеру:
сервис-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
, чтобы боковая панель открывалась только на определенной вкладке.
сервис-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()
. Затем, когда пользователь переходит на другую вкладку, она заменяется основной боковой панелью.
сервис-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()
после взаимодействия с пользователем, например:
- Щелчок действия
- Сочетание клавиш
- Контекстное меню
- Жест пользователя на странице расширения или скрипте контента.
Закрепите боковую панель
![Значок закрепления в пользовательском интерфейсе на боковой панели.](https://developer.chrome.com/static/docs/extensions/reference/api/sidePanel/images/side-panel-pin.png?authuser=5&hl=ru)
На панели инструментов боковой панели отображается значок булавки, когда боковая панель открыта. При нажатии на значок закрепляется значок действия вашего расширения. Нажатие на закрепленный значок действия приведет к выполнению действия по умолчанию для вашего значка действия и откроет боковую панель только в том случае, если это было явно настроено.
Примеры
Для получения дополнительных демонстраций расширений API боковой панели изучите любое из следующих расширений:
- Боковая панель словаря .
- Глобальная боковая панель .
- Несколько боковых панелей .
- Откройте боковую панель .
- Боковая панель для конкретного сайта .
Типы
GetPanelOptions
Характеристики
- идентификатор табуляции
номер необязательно
Если указано, будут возвращены параметры боковой панели для данной вкладки. В противном случае возвращаются параметры боковой панели по умолчанию (используются для любой вкладки, не имеющей определенных настроек).
OpenOptions
Характеристики
- идентификатор табуляции
номер необязательно
Вкладка, в которой открывается боковая панель. Если соответствующая вкладка имеет боковую панель для конкретной вкладки, панель будет открыта только для этой вкладки. Если панель для конкретной вкладки отсутствует, глобальная панель будет открыта на указанной вкладке и на любых других вкладках без открытой в данный момент панели для конкретной вкладки. Это переопределит любую активную в данный момент боковую панель (глобальную или для конкретной вкладки) на соответствующей вкладке. Необходимо указать хотя бы одно из значений this или
windowId
. - идентификатор окна
номер необязательно
Окно, в котором открывается боковая панель. Это применимо только в том случае, если расширение имеет глобальную (не зависящую от вкладок) боковую панель или также указан
tabId
. Это переопределит любую активную в данный момент глобальную боковую панель, которую пользователь открыл в данном окне. Должен быть указан хотя бы один из значений this илиtabId
.
PanelBehavior
Характеристики
- опенпанельонактионклик
логическое значение необязательно
Будет ли щелчок по значку расширения включать отображение записи о расширении на боковой панели. По умолчанию ложь.
PanelOptions
Характеристики
- включено
логическое значение необязательно
Должна ли быть включена боковая панель. Это необязательно. Значение по умолчанию верно.
- путь
строка необязательна
Путь к используемому HTML-файлу боковой панели. Это должен быть локальный ресурс в пакете расширения.
- идентификатор табуляции
номер необязательно
Если указано, параметры боковой панели будут применяться только к вкладке с этим идентификатором. Если они опущены, эти параметры задают поведение по умолчанию (используется для любой вкладки, не имеющей определенных настроек). Примечание. Если для этого tabId и tabId по умолчанию задан один и тот же путь, то панель для этого tabId будет другим экземпляром, чем панель для tabId по умолчанию.
SidePanel
Характеристики
- путь_по умолчанию
нить
Указанный разработчиком путь для отображения боковой панели.
Методы
getOptions()
chrome.sidePanel.getOptions(
options: GetPanelOptions,
callback?: function,
)
Возвращает конфигурацию активной панели.
Параметры
- параметры
Указывает контекст, для которого возвращается конфигурация.
- перезвонить
функция необязательна
Параметр
callback
выглядит так:(options: PanelOptions) => void
- параметры
Возврат
Обещание< Параметры панели >
Промисы поддерживаются в Манифесте V3 и более поздних версиях, но обратные вызовы предусмотрены для обратной совместимости. Вы не можете использовать оба при одном вызове функции. Промис разрешается с тем же типом, который передается в обратный вызов.
getPanelBehavior()
chrome.sidePanel.getPanelBehavior(
callback?: function,
)
Возвращает текущее поведение боковой панели расширения.
Параметры
- перезвонить
функция необязательна
Параметр
callback
выглядит так:(behavior: PanelBehavior) => void
- поведение
Возврат
Обещание < PanelBehavior >
Промисы поддерживаются в Манифесте V3 и более поздних версиях, но обратные вызовы предусмотрены для обратной совместимости. Вы не можете использовать оба при одном вызове функции. Промис разрешается с тем же типом, который передается в обратный вызов.
open()
chrome.sidePanel.open(
options: OpenOptions,
callback?: function,
)
Открывает боковую панель расширения. Это может быть вызвано только в ответ на действие пользователя.
Параметры
- параметры
Указывает контекст, в котором открывается боковая панель.
- перезвонить
функция необязательна
Параметр
callback
выглядит так:() => void
Возврат
Обещание<void>
Промисы поддерживаются в Манифесте V3 и более поздних версиях, но обратные вызовы предусмотрены для обратной совместимости. Вы не можете использовать оба при одном вызове функции. Промис разрешается с тем же типом, который передается в обратный вызов.
setOptions()
chrome.sidePanel.setOptions(
options: PanelOptions,
callback?: function,
)
Настраивает боковую панель.
Параметры
- параметры
Параметры конфигурации, применимые к панели.
- перезвонить
функция необязательна
Параметр
callback
выглядит так:() => void
Возврат
Обещание<void>
Промисы поддерживаются в Манифесте V3 и более поздних версиях, но обратные вызовы предусмотрены для обратной совместимости. Вы не можете использовать оба при одном вызове функции. Промис разрешается с тем же типом, который передается в обратный вызов.
setPanelBehavior()
chrome.sidePanel.setPanelBehavior(
behavior: PanelBehavior,
callback?: function,
)
Настраивает поведение боковой панели расширения. Это операция по переустановке.
Параметры
- поведение
Новое поведение, которое необходимо установить.
- перезвонить
функция необязательна
Параметр
callback
выглядит так:() => void
Возврат
Обещание<void>
Промисы поддерживаются в Манифесте V3 и более поздних версиях, но обратные вызовы предусмотрены для обратной совместимости. Вы не можете использовать оба при одном вызове функции. Промис разрешается с тем же типом, который передается в обратный вызов.