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" ao arquivo manifesto da extensão:

manifest.json:

{
  "name": "My side panel extension",
  ...
  "permissions": [
    "sidePanel"
  ]
}

Disponibilidade

Chrome 114 ou mais recente MV3+

Conceitos e uso

A API Side Panel permite que as extensões mostrem a própria interface 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 permanece aberto durante a navegação entre guias (se configurado para fazer isso).
  • Ela 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 para a API Side Panel. Consulte Amostras de extensões para ver exemplos completos de extensões.

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. Isso precisa apontar 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 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á mostrado de novo automaticamente quando o usuário alternar para uma guia em que estava aberta anteriormente.

Quando o usuário navega para 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 do painel lateral.

Para ver um exemplo completo, consulte o exemplo do painel lateral específico para guias.

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 clicar no ícone da barra de ferramentas de ações 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(). Ele permite que as extensões abram o painel lateral com um gesto do usuário da extensão, 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 a extensão de exemplo 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 o 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 });
  }
});

Alternar para um painel diferente

As extensões podem usar sidepanel.getOptions() para extrair o painel lateral atual. O exemplo a seguir define um painel lateral de boas-vindas no runtime.onInstalled(). Quando o usuário navegar para uma guia diferente, ela será 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 });
  }
});

Consulte o exemplo Vários painéis laterais para ver o código completo.

Experiência do usuário no painel lateral

Os usuários verão os painéis laterais integrados do Chrome primeiro. Cada painel lateral exibe o ícone da extensão no menu do painel lateral. Se nenhum ícone estiver incluído, será mostrado 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, combine um ícone de ação com sidePanel.setPanelBehavior(). Como alternativa, 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 exibe um ícone de alfinete quando o painel lateral está aberto. Clicar no ícone fixa o ícone de ação da sua extensão. Clicar no ícone de ação depois da fixação, realizará a ação padrão para seu ícone de ação e só abrir o painel lateral se isso tiver sido explicitamente configurado.

Exemplos

Para ver mais demonstrações de extensões da API Side Panel, conheça qualquer uma destas extensões:

Tipos

GetPanelOptions

Propriedades

  • tabId

    número opcional

    Se especificado, as opções do painel lateral para a 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 versões mais recentes

Propriedades

  • tabId

    número opcional

    A guia em que o painel lateral será aberto. Se a guia correspondente tiver um painel lateral específico, ele só será aberto nessa guia. Se não houver um painel específico da guia, o painel global será aberto na guia especificada e nas outras sem um painel específico da guia aberto no momento. Isso substituirá qualquer painel lateral ativo no momento (global ou específico por guia) na guia correspondente. É necessário fornecer pelo menos um valor correspondente 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 da guia) ou se tabId também for especificado. Isso substitui qualquer painel lateral global ativo no momento que o usuário tenha aberto na janela especificada. É necessário fornecer pelo menos um valor correspondente ou tabId.

PanelBehavior

Propriedades

  • openPanelOnActionClick

    booleano opcional

    Se clicar no ícone da extensão alternará a exibição da entrada da extensão no painel lateral. O padrão é "false".

PanelOptions

Propriedades

  • ativado

    booleano opcional

    Indica 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 dentro do pacote de extensão.

  • tabId

    número opcional

    Se especificado, as opções do painel lateral só se aplicarão à guia com esse ID. Se omitida, essas opções definirão 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.

SidePanel

Propriedades

  • default_path

    string

    Caminho especificado pelo desenvolvedor para 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

  • opções

    GetPanelOptions

    Especifica o contexto para o qual a configuração deve ser retornada.

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    (options: PanelOptions) => void

Retorna

  • Promise&lt;PanelOptions&gt;

    O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.

getPanelBehavior()

Promessa 
chrome.sidePanel.getPanelBehavior(
  callback?: function,
)

Retorna o comportamento atual do painel lateral da extensão.

Parâmetros

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    (behavior: PanelBehavior) => void

Retorna

  • Promise&lt;PanelBehavior&gt;

    O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.

open()

Promessa Chrome 116 ou versões mais recentes 
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

  • opções

    OpenOptions

    Especifica o contexto em que o painel lateral será aberto.

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    () => void

Retorna

  • Promessa<void>

    O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.

setOptions()

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

Configura o painel lateral.

Parâmetros

  • opções

    PanelOptions

    As opções de configuração a serem aplicadas ao painel.

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    () => void

Retorna

  • Promessa<void>

    O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.

setPanelBehavior()

Promessa 
chrome.sidePanel.setPanelBehavior(
  behavior: PanelBehavior,
  callback?: function,
)

Configura o comportamento do painel lateral da extensão. Essa é uma operação de inserção e inserção.

Parâmetros

  • comportamento do consumidor

    PanelBehavior

    O novo comportamento a ser definido.

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    () => void

Retorna

  • Promessa<void>

    O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.