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
sidePanelPara usar a API Side Panel, adicione a permissão "sidePanel" no arquivo de manifesto da extensão:
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 interface no painel lateral, permitindo experiências persistentes que complementam a jornada de navegação do usuário.
Alguns recursos incluem:
- O painel lateral permanece aberto ao navegar entre as guias (se configurado para isso).
- Ele pode estar disponível apenas 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 deve ser exibido.
Casos de uso
As seções a seguir demonstram alguns casos de uso comuns da API Side Panel. Consulte Exemplos de extensões para ver exemplos completos.
Mostrar 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 lateral em todos os sites. Ele precisa apontar para um caminho relativo no diretório da 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 sidepanel.setOptions() para ativar um painel lateral em uma guia específica. Este exemplo usa browser.tabs.onUpdated() para detectar atualizações feitas na guia. Ele 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';
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
});
}
});
Quando um usuário muda temporariamente para uma guia em que o painel lateral não está ativado, ele é ocultado. Ele vai aparecer automaticamente de novo quando o usuário mudar para uma guia em que ele estava aberto.
Quando o usuário navegar para um site em que o painel lateral não está ativado, ele será fechado, e a extensão não vai aparecer no menu suspenso do painel lateral.
Para um exemplo completo, consulte o exemplo de painel lateral específico da guia.
Abra o painel lateral clicando no ícone da barra de ferramentas
Os desenvolvedores podem permitir que os usuários abram o painel lateral ao clicar no ícone da barra de ferramentas de ação 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
browser.sidePanel
.setPanelBehavior({ openPanelOnActionClick: true })
.catch((error) => console.error(error));
...
Abrir o painel lateral de forma programática na interação do usuário
O Chrome 116 apresenta o sidePanel.open(). Ele permite que as extensões abram o painel lateral usando uma interação inicial, como clicar no ícone de ação. Ou uma interação do usuário em uma página de extensão ou um 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(), é preciso escolher o contexto em que ele será aberto. Use windowId para abrir um painel lateral global. Como alternativa, defina o tabId para abrir o painel lateral apenas em uma guia específica.
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 });
}
});
Mudar para 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 em runtime.onInstalled(). Quando o usuário navega para uma guia diferente, ele é substituído pelo painel lateral principal.
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 });
}
});
Confira o exemplo de vários painéis laterais para ver o código completo.
Experiência do usuário no painel lateral
Os usuários vão ver os painéis laterais integrados do Chrome primeiro. Cada painel lateral mostra o ícone da extensão no menu do painel lateral. Se nenhum ícone for incluído, um ícone de marcador de posição com a primeira letra do nome da extensão será mostrado.
Abrir o painel lateral
Para permitir que os usuários abram o painel lateral, use um ícone de ação em combinação
com sidePanel.setPanelBehavior(). Como alternativa, 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
- Uma interação 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 fixação quando o painel está aberto. Ao clicar no ícone, o ícone de ação da extensão é fixado. Clicar no ícone de ação depois de fixado vai realizar a ação padrão do ícone e só vai abrir o painel lateral se isso tiver sido configurado explicitamente.
Exemplos
Para mais demonstrações de extensões da API Side Panel, confira as seguintes extensões:
- Painel lateral do dicionário.
- Painel lateral global.
- Vários painéis laterais.
- Abra o painel lateral.
- Painel lateral específico do site.
Tipos
CloseOptions
Propriedades
-
tabId
número optional
A guia em que o painel lateral será fechado. Se um painel lateral específico da guia estiver aberto na guia especificada, ele será fechado para essa guia. Se apenas o painel lateral global estiver aberto, a promessa retornada pela chamada para
close()será rejeitada com um erro. Esse comportamento foi alterado no Chrome 145, e as versões anteriores voltaram a fechar o painel global. É preciso fornecer pelo menos este campo ouwindowId. -
windowId
número optional
A janela em que o painel lateral será fechado. Se um painel lateral global estiver aberto na janela especificada, ele será fechado para todas as guias nessa janela em que nenhum painel específico da guia estiver ativo. É preciso fornecer pelo menos este campo ou
tabId.
GetPanelOptions
Propriedades
-
tabId
número optional
Se especificado, as opções do painel lateral da guia em questão 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 optional
A guia em que o painel lateral será aberto. Se a guia correspondente tiver um painel lateral específico, ele só será aberto para essa guia. Se não houver um painel específico para a guia, o painel global será aberto na guia especificada e em qualquer outra guia sem um painel específico aberto. Isso vai substituir qualquer painel lateral ativo (global ou específico da guia) na guia correspondente. É preciso fornecer pelo menos este campo ou
windowId. -
windowId
número optional
A janela em que o painel lateral será aberto. Isso só é aplicável se a extensão tiver um painel lateral global (não específico da guia) ou se
tabIdtambém for especificado. Isso vai substituir qualquer painel lateral global ativo que o usuário tenha aberto na janela em questão. É preciso fornecer pelo menos este campo outabId.
PanelBehavior
Propriedades
-
openPanelOnActionClick
booleano opcional
Se clicar no ícone da extensão vai alternar a exibição da entrada da extensão no painel lateral. O padrão é "falso".
PanelClosedInfo
Propriedades
-
caminho
string
O caminho do recurso local no pacote de extensão cujo conteúdo é exibido no painel.
-
tabId
número optional
O ID opcional da guia em que o painel lateral foi fechado. Isso é fornecido apenas quando o painel é específico da guia.
-
windowId
número
O ID da janela em que o painel lateral foi fechado. Isso está disponível para painéis globais e específicos de guias.
PanelLayout
Propriedades
-
side
PanelOpenedInfo
Propriedades
-
caminho
string
O caminho do recurso local no pacote de extensão cujo conteúdo é exibido no painel.
-
tabId
número optional
O ID opcional da guia em que o painel lateral é aberto. Isso é fornecido apenas quando o painel é específico da guia.
-
windowId
número
O ID da janela em que o painel lateral é aberto. Isso está disponível para painéis globais e específicos de guias.
PanelOptions
Propriedades
-
ativado
booleano opcional
Se o painel lateral deve ser ativado. Isso é opcional. O valor padrão é true.
-
caminho
string opcional
O caminho para o arquivo HTML do painel lateral que será usado. Precisa ser um recurso local no pacote de extensão.
-
tabId
número optional
Se especificado, as opções do painel lateral serão aplicadas apenas à guia com esse ID. Se omitidas, 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 do tabId padrão.
Side
Define o alinhamento possível para o painel lateral na interface do navegador.
Enumeração
"left"
"right"
SidePanel
Propriedades
-
default_path
string
Caminho especificado pelo desenvolvedor para exibição do painel lateral.
Métodos
close()
browser.sidePanel.close(
options: CloseOptions,
): Promise<void>
Fecha o painel lateral da extensão. Essa é uma operação autônoma se o painel já estiver fechado.
Parâmetros
-
opções
Especifica o contexto em que o painel lateral será fechado.
Retorna
-
Promessa<void>
Retorna uma promessa que é resolvida quando o painel lateral é fechado.
getLayout()
browser.sidePanel.getLayout(): Promise<PanelLayout>
Retorna o layout atual do painel lateral.
Retorna
-
Promise<PanelLayout>
Retorna uma promessa que é resolvida com um
PanelLayout.
getOptions()
browser.sidePanel.getOptions(
options: GetPanelOptions,
): Promise<PanelOptions>
Retorna a configuração do painel ativo.
Parâmetros
-
opções
Especifica o contexto para retornar a configuração.
Retorna
-
Promise<PanelOptions>
Retorna uma promessa que é resolvida com a configuração do painel ativo.
getPanelBehavior()
browser.sidePanel.getPanelBehavior(): Promise<PanelBehavior>
Retorna o comportamento atual do painel lateral da extensão.
Retorna
-
Promise<PanelBehavior>
Retorna uma promessa que é resolvida com o comportamento do painel lateral da extensão.
open()
browser.sidePanel.open(
options: OpenOptions,
): Promise<void>
Abre o painel lateral da extensão. Isso só pode ser chamado em resposta a uma ação do usuário.
Parâmetros
-
opções
Especifica o contexto em que o painel lateral será aberto.
Retorna
-
Promessa<void>
Retorna uma promessa que é resolvida quando o painel lateral é aberto.
setOptions()
browser.sidePanel.setOptions(
options: PanelOptions,
): Promise<void>
Configura o painel lateral.
Parâmetros
-
opções
As opções de configuração a serem aplicadas ao painel.
Retorna
-
Promessa<void>
Retorna uma promessa que é resolvida quando as opções são definidas.
setPanelBehavior()
browser.sidePanel.setPanelBehavior(
behavior: PanelBehavior,
): Promise<void>
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.
Retorna
-
Promessa<void>
Retorna uma promessa que é resolvida quando o novo comportamento é definido.
Eventos
onClosed
browser.sidePanel.onClosed.addListener(
callback: function,
)
Disparado quando o painel lateral da extensão é fechado.
Parâmetros
-
callback
função
O parâmetro
callbacké semelhante a:(info: PanelClosedInfo) => void
-
informações
-
onOpened
browser.sidePanel.onOpened.addListener(
callback: function,
)
Disparado quando o painel lateral da extensão é aberto.
Parâmetros
-
callback
função
O parâmetro
callbacké semelhante a:(info: PanelOpenedInfo) => void
-
informações
-