Desenvolver uma extensão para a barra lateral do Microsoft Edge

Como desenvolvedor de extensão do Microsoft Edge, você pode fazer com que sua extensão do Microsoft Edge nova ou existente apareça na barra lateral. Qualquer extensão pode usar a barra lateral, além de sua outra interface do usuário.

Conteúdo detalhado:

Introdução

Use a chrome.sidePanel API para hospedar conteúdo na barra lateral do Microsoft Edge ao lado do conteúdo principal de uma página da Web.

Como desenvolvedor de extensão do Microsoft Edge, você pode fazer com que sua extensão do Microsoft Edge nova ou existente apareça na barra lateral. Qualquer extensão pode usar a barra lateral, além de sua outra interface do usuário.

A barra lateral de uma extensão do Microsoft Edge

Usando a API do painel lateral, você pode aprimorar a experiência de navegação, permitindo que os usuários exibam informações adicionais juntamente com o conteúdo principal de uma página da Web.

A barra lateral é um painel persistente localizado na lateral do Microsoft Edge. O painel da barra lateral coexiste com o conteúdo principal do navegador. A barra lateral reduz a necessidade de alternar constantemente entre as guias, resultando em uma experiência de navegação mais produtiva.

Opcionalmente, uma extensão pode usar a API do Painel Lateral para mostrar uma interface do usuário personalizada na barra lateral do Microsoft Edge. Além disso, a extensão pode continuar aparecendo na barra de ferramentas do Microsoft Edge junto com uma interface do usuário, como pop-ups, e pode injetar scripts.

Terminologia

Termo Definição
a API do Painel Lateral Nome do recurso que você pode usar em suas extensões do Microsoft Edge. A interface do usuário do Chrome usa o termo painel lateral.
sidePanel ou side_panel Nome da API e permissão para habilitar qualquer extensão como uma extensão da barra lateral.
extensão da barra lateral Uma extensão do Microsoft Edge que tenha uma interface do usuário na barra lateral.

Conceitos e uso

A API do Painel Lateral permite que uma extensão exiba sua própria interface do usuário na barra lateral do Microsoft Edge, permitindo uma experiência persistente que complementa a jornada de navegação do usuário.

Interface do usuário da barra lateral do navegador Edge

Assim como acontece com outros recursos de extensão, a página HTML exibida na barra lateral é executada em um contexto de extensão confiável na origem da extensão (extension://<id>). A barra lateral tem o mesmo acesso à API que outros contextos de extensão confiáveis.

Todas as APIs de extensões existentes estão disponíveis para extensões da barra lateral, para que você possa aproveitar todos os recursos atuais da estrutura de extensibilidade em sua extensão habilitada para barra lateral.

Alguns recursos da barra lateral incluem:

  • A barra lateral permanece aberta enquanto navega entre as guias.

    • Problema conhecido: a barra lateral não é exibida automaticamente novamente quando o usuário alterna para uma guia na qual a barra lateral estava aberta anteriormente (Problema #142).

  • Uma extensão na barra lateral pode ser disponibilizada para sites específicos.

  • Uma extensão na barra lateral dá acesso a todas as APIs com suporte para extensões do Microsoft Edge.

  • Nas configurações do Microsoft Edge, o usuário pode especificar várias configurações da barra lateral.

Adicione a permissão sidePanel no arquivo de manifesto

Para usar a API do painel lateral, adicione a "sidePanel" permissão no arquivo de manifesto da extensão (manifest.json):

{
  ...
  "name": "My sidebar extension",
  ...
  "side_panel": {
    "default_path": "sidepanel.html"
  },
  "permissions": [
    "sidePanel"
  ]
   ...
}

Cada extensão para o Microsoft Edge tem um arquivo de manifesto formatado em JSON, chamado manifest.json. O arquivo de manifesto é o blueprint da extensão.

Um arquivo de manifesto completo é incluído em cada amostra; consulte Exemplos de extensão, abaixo.

Veja também:

Casos de uso para a API do painel lateral

As seções a seguir demonstram alguns casos de uso comuns para a API do painel lateral.

Para obter exemplos completos de extensão, consulte Exemplos de extensão, abaixo.

Exibir a mesma barra lateral em todos os sites

Uma barra lateral pode ser definida como padrão para mostrar a mesma extensão em todas as guias abertas do navegador. Os valores padrão persistem entre as sessões do navegador.

Em manifest.json, defina a "default_path" chave, por exemplo "sidepanel.html":

{
  "name": "My sidebar extension",
  ...
  "side_panel": {
    "default_path": "sidepanel.html"
  }
  ...
}

O arquivo que você especificou como padrão, como sidepanel.html, é exibido em todas as guias abertas do navegador:

<!DOCTYPE html>
<html>
  <head>
    <title>Global side panel</title>
  </head>
  <body>
    <h1>All sites sidepanel extension</h1>
    <p>This side panel is enabled on all sites</p>
  </body>
</html>

Veja também:

Habilitar uma barra lateral somente para um site específico

Uma extensão pode usar sidepanel.setOptions() para habilitar uma barra lateral em uma guia específica. Pode ser um site específico, portanto, a extensão será aberta na barra lateral quando o usuário acessar esse site.

Este exemplo usa chrome.tabs.onUpdated() para escutar todas as atualizações feitas na guia. Ele verifica se a URL está www.bing.com e, em caso afirmativo, habilita a barra lateral. Caso contrário, desativará a barra lateral.

service-worker.js:

const BING_ORIGIN = 'https://www.bing.com';

chrome.tabs.onUpdated.addListener(async (tabId, info, tab) => {
  if (!tab.url) return;
  const url = new URL(tab.url);
  // Enables the sidebar when at bing.com
  if (url.origin === BING_ORIGIN) {
    await chrome.sidePanel.setOptions({
      tabId,
      path: 'sidepanel.html',
      enabled: true
    });
  } else {
    // Disables the sidebar when at other sites
    await chrome.sidePanel.setOptions({
      tabId,
      enabled: false
    });
  }
});

Em addListener(), fazemos o seguinte:

  1. Teste url.origin para ver se é a guia desejada.
  2. Em sidePanel.setOptions(), defina enabled como true ou false.

Quando um usuário alterna para uma guia ou site para o qual a barra lateral não está habilitada, a barra lateral fica oculta.

Problema conhecido: a barra lateral não é exibida automaticamente novamente quando o usuário alterna para uma guia na qual a barra lateral estava aberta anteriormente (Problema #142).

Para obter um exemplo completo, consulte Exemplo de painel lateral específico do site.

Habilitar o ícone de atalho da extensão para abrir a barra lateral

Para permitir que os usuários abram a barra lateral clicando no ícone da barra de ferramentas de ação, use sidePanel.setPanelBehavior(). Primeiro, declare a "action" chave em manifest.json:

{
  "name": "My sidebar extension",
  ...
   "action": {
    "default_title": "Click to open sidebar"
  },
  ...
}

Em seguida, adicione o seguinte código à service-worker.js listagem de código que está em Habilitar uma barra lateral somente para um site específico, acima:

// Allow users to open the sidebar by clicking the action toolbar icon
chrome.sidePanel
  .setPanelBehavior({ openPanelOnActionClick: true })
  .catch((error) => console.error(error));

Abrir a barra lateral após a interação do usuário

sidePanel.open() Permite que as extensões abram a barra lateral por meio de um gesto do usuário, como clicar no ícone de ação, ou por meio de qualquer interação do usuário em uma página de extensão ou script de conteúdo, como clicar em um botão.

O código a seguir mostra como abrir uma barra lateral global na janela atual quando o usuário clica em um menu de contexto. Ao usar sidePanel.open(), escolha o contexto no qual a barra lateral deve ser aberta:

  • Use windowId para abrir uma barra lateral global, conforme mostrado no exemplo a seguir.
  • Ou defina como tabId para abrir a barra lateral somente em uma guia específica.
// service-worker.js:
chrome.runtime.onInstalled.addListener(() => {
  chrome.contextMenus.create({
    id: 'openSidePanel',
    title: 'Open sidebar',
    contexts: ['all']
  });
});

chrome.contextMenus.onClicked.addListener((info, tab) => {
  if (info.menuItemId === 'openSidePanel') {
    // Open the sidebar in all the tabs of the current window.
    chrome.sidePanel.open({ windowId: tab.windowId });
  }
});

Para obter uma demonstração completa, consulte Abrindo o painel lateral por meio de uma interação do usuário.

Alternar para uma barra lateral diferente

Uma extensão pode usar sidepanel.getOptions() para recuperar a barra lateral atual e, em seguida, habilitar uma barra lateral diferente para uma guia específica.

Este exemplo define uma barra lateral contendo uma mensagem de boas-vindas em runtime.onInstalled(). Quando o usuário navega para uma guia diferente, a barra lateral é substituída pela barra lateral no nível do navegador.

// service-worker.js:
const welcomePage = 'sidebar/welcome-sb.html';
const mainPage = 'sidebar/main-sb.html';

chrome.runtime.onInstalled.addListener(() => {
  chrome.sidePanel.setOptions({ path: welcomePage });
});

chrome.tabs.onActivated.addListener(async ({ tabId }) => {
  const { path } = await chrome.sidePanel.getOptions({ tabId });
  if (path === welcomePage) {
    chrome.sidePanel.setOptions({ path: mainPage });
  }
});

Para obter o código completo, consulte Exemplo de vários painéis laterais.

Desenvolva uma extensão para a barra lateral do Microsoft Edge tenha esses recursos de experiência do usuário (UX).

Abrir a extensão na barra lateral

Para permitir que os usuários abram a barra lateral, siga um destes procedimentos:

Os detalhes estão abaixo.

Ao clicar em um ícone

Os usuários podem clicar no ícone Abrir na barra lateral (ícone Abrir na barra lateral), que é exibido ao lado do nome da extensão no hub Extensões:

Caixa de diálogo da barra lateral

Ou os usuários podem clicar no ícone personalizado da extensão na barra de ferramentas, se ela estiver habilitada. Essa experiência do usuário requer que a extensão tenha habilitado o ícone de atalho para abrir a barra lateral, conforme descrito em Habilitar o ícone de atalho da extensão para abrir a barra lateral, acima. Neste exemplo, o ícone personalizado da extensão é um círculo (ícone personalizado da extensão):

Clicando no ícone da extensão na barra de ferramentas

Veja também:

Clicando com o botão direito do mouse no ícone da extensão

Os usuários podem clicar com o botão direito do mouse no ícone da extensão na barra de ferramentas e selecionar Abrir na barra lateral ou Fechar barra lateral:

Clicando com o botão direito do mouse no atalho da barra de ferramentas para abrir a extensão

Clicando com o botão direito do mouse no atalho da barra de ferramentas para fechar a extensão

O ícone da extensão aparecerá na barra de ferramentas se o usuário tiver clicado no ícone Mostrar na barra de ferramentas (Mostrar no ícone da barra de ferramentas) ao lado do nome da extensão no hub Extensões.

Veja também:

Ao pressionar um atalho de teclado

Os usuários podem pressionar um atalho de teclado se o comando de ação estiver ativado e o ícone de ação estiver ativado para abrir a barra lateral.

  • Para ativar o comando de ação, consulte Comandos de ação em chrome.commands na referência de API.
  • Para ativar o ícone de ação, consulte Abra o painel lateral clicando no ícone da barra de ferramentas em chrome.sidePanel na referência da API.

Se a openPanelOnActionClick() propriedade do tipo PanelBehavior estiver definida como true, o usuário poderá abrir a barra lateral usando um atalho de teclado. Para habilitar isso, você especifica um comando de ação no manifesto.

Veja também:

Abrir através de um gesto

A barra lateral também pode ser aberta através das seguintes interações:

Exemplos de extensão

Para obter mais demonstrações de extensões da API do Painel Lateral, explore qualquer uma das seguintes extensões:

Veja também:

Tipos e métodos

Consulte Tipos e métodos na página de referência da API chrome.sidePanel em developer.chrome.com.

Confira também

Observação

Partes desta página são modificações baseadas no trabalho criado e compartilhado pelo Google e usadas de acordo com os termos descritos na Licença Creative Commons Atribuição 4.0 Internacional. A página original é encontrada aqui.

Licença Creative Commons Este trabalho está licenciado sob uma Licença Creative Commons Atribuição 4.0 Internacional.

  • Last updated on