Descrição
Use a API chrome.sidePanel
para hospedar conteúdo no painel lateral do navegador ao lado do conteúdo principal de uma página da Web.
Permissões
sidePanel
Para usar a API Side Panel, adicione a permissão "sidePanel"
no arquivo de extensão manifest:
manifest.json:
{
"name": "My side panel extension",
...
"permissions": [
"sidePanel"
]
}
Disponibilidade
Conceitos e uso
A API Side Panel permite que as extensões mostrem a própria IU no painel lateral, possibilitando experiências persistentes que complementam a jornada de navegação do usuário.
Estes são alguns dos recursos:
- O painel lateral permanecerá aberto durante a navegação entre guias (se definido para isso).
- Ela só pode estar disponível em sites específicos.
- Como uma página de extensão, os painéis laterais têm acesso a todas as APIs do Chrome.
- Nas configurações do Chrome, os usuários podem especificar em qual lado o painel será exibido.
Casos de uso
As seções a seguir demonstram alguns casos de uso comuns da API Side Panel. Consulte Exemplos de extensão para ver exemplos completos.
Exibir o mesmo painel lateral em todos os sites
O painel lateral pode ser definido inicialmente na propriedade "default_path"
na chave "side_panel"
do manifesto para mostrar o mesmo painel em todos os sites. Ele aponta para um caminho relativo dentro do diretório de extensão.
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>
Ativar um painel lateral em um site específico
Uma extensão pode usar o sidepanel.setOptions()
para ativar um painel lateral em uma guia específica. Este exemplo usa chrome.tabs.onUpdated()
para detectar as atualizações feitas na guia. Ela verifica se o URL é www.google.com e ativa o painel lateral. Caso contrário, ela será desativada.
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
});
}
});
Quando um usuário alterna temporariamente para uma guia em que o painel lateral não está ativado, o painel lateral fica oculto. Ele será exibido novamente de forma automática quando o usuário alternar para uma guia onde estava anteriormente aberta.
Quando o usuário acessa um site em que o painel lateral não está ativado, o painel lateral é fechado, e a extensão não aparece no menu suspenso.
Para conferir um exemplo completo, confira o exemplo Painel lateral específico da guia.
Clique no ícone da barra de ferramentas para abrir o painel lateral
Os desenvolvedores podem permitir que os usuários abram o painel lateral ao clicarem no ícone de ação na barra de ferramentas com sidePanel.setPanelBehavior()
. Primeiro, declare a chave "action"
no manifesto:
manifest.json:
{
"name": "My side panel extension",
...
"action": {
"default_title": "Click to open panel"
},
...
}
Agora, adicione este código ao exemplo anterior:
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));
...
Abrir programaticamente o painel lateral na interação do usuário
O Chrome 116 apresenta o sidePanel.open()
. Ela permite que as extensões abram o painel lateral com um gesto de extensão do usuário, como clicar no ícone de ação. Ou uma interação do usuário em uma página de extensão ou script de conteúdo, como clicar em um botão. Para uma demonstração completa, consulte o exemplo de extensão Abrir painel lateral.
O código a seguir mostra como abrir um painel lateral global na janela atual quando o usuário clica em um menu de contexto. Ao usar sidePanel.open()
, você precisa escolher o contexto em que ele será aberto. Use windowId
para abrir um painel lateral global. Como alternativa, defina tabId
para abrir o painel lateral apenas em uma guia específica.
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 });
}
});
Usar outro painel
As extensões podem usar sidepanel.getOptions()
para recuperar o painel lateral atual. O exemplo a seguir define um painel lateral de boas-vindas no runtime.onInstalled()
. Então, quando o usuário navega para uma guia diferente, ela é substituída pelo painel lateral principal.
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 });
}
});
Veja o exemplo de Vários painéis laterais para ver o código completo.
Experiência do usuário no painel lateral
Os painéis laterais integrados do Chrome vão aparecer primeiro para os usuários. Cada painel lateral mostra o ícone da extensão no menu do painel lateral. Se nenhum ícone estiver incluído, será exibido um ícone de espaço reservado com a primeira letra do nome da extensão.
Abrir o painel lateral
Para permitir que os usuários abram o painel lateral, use um ícone de ação combinado com
sidePanel.setPanelBehavior()
. Se preferir, faça uma chamada para sidePanel.open()
após uma interação do usuário, como:
- Um clique de ação
- Um atalho de teclado
- Um menu de contexto
- Um gesto do usuário em uma página de extensão ou script de conteúdo.
Fixar o painel lateral
A barra de ferramentas do painel lateral mostra um ícone de alfinete quando o painel lateral está aberto. Clicar nesse ícone fixa o ícone de ação da sua extensão. Ao clicar no ícone de ação depois de fixado, a ação padrão será executada para ele e o painel lateral só será aberto se isso tiver sido configurado explicitamente.
Exemplos
Para mais demonstrações de extensões da API Side Panel, explore qualquer uma das seguintes extensões:
- Painel lateral do dicionário.
- Painel lateral global.
- Vários painéis laterais:
- Abrir o painel lateral.
- Painel lateral específico do site.
Tipos
GetPanelOptions
Propriedades
-
tabId
número opcional
Se especificado, as opções do painel lateral da guia especificada serão retornadas. Caso contrário, retorna as opções padrão do painel lateral (usadas para qualquer guia que não tenha configurações específicas).
OpenOptions
Propriedades
-
tabId
número opcional
A guia em que o painel lateral será aberto. Se a guia correspondente tiver um painel lateral específico para ela, o painel será aberto apenas para essa guia. Se não houver um painel específico para a guia, o painel global será aberto na guia especificada e em todas as outras que não estiverem abertas. Isso vai modificar qualquer painel lateral ativo no momento (global ou específico de guia) na guia correspondente. É necessário fornecer pelo menos uma dessas informações ou
windowId
. -
windowId
número opcional
A janela em que o painel lateral será aberto. Isso só será aplicável se a extensão tiver um painel lateral global (não específico para guias) ou se
tabId
também for especificado. Isso substitui qualquer painel lateral global ativo que o usuário tenha aberto na janela especificada. É necessário fornecer pelo menos uma dessas informações outabId
.
PanelBehavior
Propriedades
-
openPanelOnActionClick
booleano opcional
Se clicar no ícone da extensão irá alternar a exibição da entrada da extensão no painel lateral. O padrão é "false".
PanelOptions
Propriedades
-
ativado
booleano opcional
Define se o painel lateral precisa ser ativado. Isso é opcional. O valor padrão é true.
-
caminho
string opcional
O caminho para o arquivo HTML do painel lateral a ser usado. Precisa ser um recurso local no pacote de extensões.
-
tabId
número opcional
Se especificado, as opções do painel lateral só serão aplicadas à guia com esse ID. Se omitidos, essas opções definem o comportamento padrão (usado para qualquer guia que não tenha configurações específicas). Observação: se o mesmo caminho for definido para esse tabId e o tabId padrão, o painel desse tabId será uma instância diferente do painel para o tabId padrão.
SidePanel
Propriedades
-
default_path
string
Caminho especificado pelo desenvolvedor para a exibição do painel lateral.
Métodos
getOptions()
chrome.sidePanel.getOptions(
options: GetPanelOptions,
callback?: function,
)
Retorna a configuração do painel ativo.
Parâmetros
-
do modelo.
Especifica o contexto para o qual retornar a configuração.
-
callback
função optional
O parâmetro
callback
tem esta aparência:(options: PanelOptions) => void
-
do modelo.
-
Retorna
-
Promise<PanelOptions>
Promessas são compatíveis com o Manifest V3 e versões mais recentes, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo que é passado para o callback.
getPanelBehavior()
chrome.sidePanel.getPanelBehavior(
callback?: function,
)
Retorna o comportamento atual do painel lateral da extensão.
Parâmetros
-
callback
função optional
O parâmetro
callback
tem esta aparência:(behavior: PanelBehavior) => void
-
comportamento do consumidor
-
Retorna
-
Promise<PanelBehavior>
Promessas são compatíveis com o Manifest V3 e versões mais recentes, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo que é passado para o callback.
open()
chrome.sidePanel.open(
options: OpenOptions,
callback?: function,
)
Abre o painel lateral da extensão. Ele só pode ser chamado em resposta a uma ação do usuário.
Parâmetros
-
do modelo.
Especifica o contexto em que o painel lateral será aberto.
-
callback
função optional
O parâmetro
callback
tem esta aparência:() => void
Retorna
-
Promise<void>
Promessas são compatíveis com o Manifest V3 e versões mais recentes, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo que é passado para o callback.
setOptions()
chrome.sidePanel.setOptions(
options: PanelOptions,
callback?: function,
)
Configura o painel lateral.
Parâmetros
-
do modelo.
As opções de configuração a serem aplicadas ao painel.
-
callback
função optional
O parâmetro
callback
tem esta aparência:() => void
Retorna
-
Promise<void>
Promessas são compatíveis com o Manifest V3 e versões mais recentes, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo que é passado para o callback.
setPanelBehavior()
chrome.sidePanel.setPanelBehavior(
behavior: PanelBehavior,
callback?: function,
)
Configura o comportamento do painel lateral da extensão. Essa é uma operação de upsert.
Parâmetros
-
comportamento do consumidor
O novo comportamento a ser definido.
-
callback
função optional
O parâmetro
callback
tem esta aparência:() => void
Retorna
-
Promise<void>
Promessas são compatíveis com o Manifest V3 e versões mais recentes, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo que é passado para o callback.