chrome.sidePanel

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

Chrome 114+ MV3+

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.

Menu suspenso do painel lateral
Interface do painel lateral do navegador Chrome.

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:

Fixar o painel lateral

Ícone de fixação na interface do painel lateral.
Ícone de fixação na interface do 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:

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

Chrome 116 ou mais recente

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 ou tabId.

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()

Promessa 
chrome.sidePanel.getOptions(
  options: GetPanelOptions,
  callback?: function,
)

Retorna a configuração do painel ativo.

Parâmetros

  • do modelo.

    GetPanelOptions

    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

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()

Promessa 
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

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()

Promise Chrome 116+ 
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.

    OpenOptions

    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()

Promessa 
chrome.sidePanel.setOptions(
  options: PanelOptions,
  callback?: function,
)

Configura o painel lateral.

Parâmetros

  • do modelo.

    PanelOptions

    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()

Promessa 
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

    PanelBehavior

    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.