Esta página foi traduzida pela API Cloud Translation.

Projetar a interface do usuário

A interface do usuário da extensão precisa ser intencional e mínima. Assim como as próprias extensões, a interface precisa personalizar ou melhorar a experiência de navegação sem se distrair.

Este guia explora os recursos obrigatórios e opcionais da interface do usuário. Use-o para entender como e quando implementar diferentes elementos de IU em uma extensão.

Ativar a extensão em todas as páginas

Use um browser_action quando os recursos de uma extensão funcionarem na maioria das situações.

Registrar ação do navegador

O campo "browser_action" é registrado no manifesto.

{
  "name": "My Awesome browser_action Extension",
  ...
  "browser_action": {
    ...
  }
  ...
}

Declarar "browser_action" mantém o ícone colorido, indicando que a extensão está disponível para os usuários.

Adicionar um selo

Os selos exibem um banner colorido com até quatro caracteres na parte superior do ícone do navegador. Elas só podem ser usadas por extensões que declaram "browser_action" no manifesto.

Use ícones para indicar o estado da extensão. O exemplo de Evento de água para bebidas mostra um selo com "ATIVADO" para mostrar ao usuário que ele definiu um alarme e não mostra nada quando a extensão está inativa.

Defina o texto do selo chamando chrome.browserAction.setBadgeText e a cor do banner chamando chrome.browserAction.setBadgeBackgroundColor .

chrome.browserAction.setBadgeText({text: 'ON'});
chrome.browserAction.setBadgeBackgroundColor({color: '#4688F1'});

Ativar a extensão nas páginas selecionadas

Use page_action quando os recursos de uma extensão estiverem disponíveis apenas em circunstâncias definidas.

Declarar ação da página

O campo "page_action" é registrado no manifesto.

{
  "name": "My Awesome page_action Extension",
  ...
  "page_action": {
    ...
  }
  ...
}

Declarar "page_action" vai colorir o ícone somente quando a extensão estiver disponível para os usuários. Caso contrário, ele vai ser mostrado em escala de cinza.

Definir regras para ativar a extensão

Defina regras para quando a extensão puder ser usada chamando chrome.declarativeContent no listener runtime.onInstalled em um script em segundo plano. O exemplo de extensão Ação de página por URL define a condição de que o URL precisa incluir um "g". Se a condição for atendida, a extensão chamará declarativeContent.ShowPageAction().

chrome.runtime.onInstalled.addListener(function() {
  // Replace all rules ...
  chrome.declarativeContent.onPageChanged.removeRules(undefined, function() {
    // With a new rule ...
    chrome.declarativeContent.onPageChanged.addRules([
      {
        // That fires when a page's URL contains a 'g' ...
        conditions: [
          new chrome.declarativeContent.PageStateMatcher({
            pageUrl: { urlContains: 'g' },
          })
        ],
        // And shows the extension's page action.
        actions: [ new chrome.declarativeContent.ShowPageAction() ]
      }
    ]);
  });
});

Ativar ou desativar a extensão

As extensões que usam "page_action" podem ser ativadas e desativadas dinamicamente chamando pageAction.show e pageAction.hide.

A extensão de exemplo Mappy verifica uma página da Web em busca de um endereço e mostra a localização dele em um mapa estático na pop-up. Como a extensão depende do conteúdo da página, ela não pode declarar regras para prever quais páginas serão relevantes. Em vez disso, se um endereço for encontrado em uma página, ele vai chamar pageAction.show para colorir o ícone e indicar que a extensão pode ser usada nessa guia.

chrome.runtime.onMessage.addListener(function(req, sender) {
  chrome.storage.local.set({'address': req.address})
  chrome.pageAction.show(sender.tab.id);
  chrome.pageAction.setTitle({tabId: sender.tab.id, title: req.address});
});

Fornecer os ícones de extensão

As extensões exigem pelo menos um ícone para representá-las. Forneça ícones no formato PNG para obter os melhores resultados visuais, embora qualquer formato compatível com o WebKit, incluindo BMP, GIF, ICO e JPEG seja aceito.

Designar ícones da barra de ferramentas

Os ícones específicos da barra de ferramentas são registrados no campo "default_icon" em browser_action ou page_action no manifesto. Encorajamos a inclusão de vários tamanhos em escala para o espaço de 16 mergulhos. Recomendamos, no mínimo, os tamanhos 16 x 16 e 32 x 32.

{
  "name": "My Awesome page_action Extension",
  ...
  "page_action": {
    "default_icon": {
      "16": "extension_toolbar_icon16.png",
      "32": "extension_toolbar_icon32.png"
    }
  }
  ...
}

Todos os ícones precisam ser quadrados ou podem ficar distorcidos. Se nenhum ícone for fornecido, o Chrome adicionará um genérico à barra de ferramentas.

Criar e registrar ícones adicionais

Inclua outros ícones nos seguintes tamanhos para usos fora da barra de ferramentas.

Tamanho do ícone	Uso de ícones
16x16	favicon nas páginas da extensão
32x32	Computadores Windows geralmente exigem esse tamanho. Ao fornecer essa opção, você evita que a distorção de tamanho reduza a opção de 48 x 48.
48x48	é exibida na página de gerenciamento de extensões
128x128	é exibido na instalação e na Chrome Web Store

Registre os ícones no campo "icons" do manifesto.

{
  "name": "My Awesome Extension",
  ...
  "icons": {
    "16": "extension_icon16.png",
    "32": "extension_icon32.png",
    "48": "extension_icon48.png",
    "128": "extension_icon128.png"
  }
  ...
}

Outros recursos da interface

Um pop-up é um arquivo HTML exibido em uma janela especial quando o usuário clica no ícone da barra de ferramentas. Um pop-up funciona de maneira parecida com uma página da Web. Ele pode conter links para folhas de estilo e tags de script, mas não permite JavaScript in-line.

O pop-up de exemplo Evento de hidratação mostra as opções de timer disponíveis. Os usuários definem um alarme clicando em um dos botões fornecidos.

Captura de tela de exemplo de pop-up

<html>
  <head>
    <title>Water Popup</title>
  </head>
  <body>
      <img src='./stay_hydrated.png' id='hydrateImage'>
      <button id='sampleSecond' value='0.1'>Sample Second</button>
      <button id='15min' value='15'>15 Minutes</button>
      <button id='30min' value='30'>30 Minutes</button>
      <button id='cancelAlarm'>Cancel Alarm</button>
    <script src="popup.js"></script>
  </body>
</html>

O pop-up pode ser registrado no manifesto, em ação do navegador ou ação da página.

{
  "name": "Drink Water Event",
  ...
  "browser_action": {
    "default_popup": "popup.html"
  }
  ...
}

Os pop-ups também podem ser definidos dinamicamente chamando browserAction.setPopup ou pageAction.setPopup.

chrome.storage.local.get('signed_in', function(data) {
  if (data.signed_in) {
    chrome.browserAction.setPopup({popup: 'popup.html'});
  } else {
    chrome.browserAction.setPopup({popup: 'popup_sign_in.html'});
  }
});

Use uma dica para dar descrições ou instruções curtas aos usuários quando passarem o cursor sobre o ícone do navegador.

Captura de tela de um exemplo de dica

As dicas são registradas no campo "default_title" browser_action ou page_action no manifesto.

{
"name": "Tab Flipper",
  ...
  "browser_action": {
    "default_title": "Press Ctrl(Win)/Command(Mac)+Shift+Right/Left to flip tabs"
  }
...
}

As dicas também podem ser definidas ou atualizadas chamando browserAction.setTitle e pageAction.setTitle.

chrome.browserAction.onClicked.addListener(function(tab) {
  chrome.browserAction.setTitle({tabId: tab.id, title: "You are on tab:" + tab.id});
});

Strings de localidade especializadas são implementadas com Internacionalização (link em inglês). Crie diretórios para alocar mensagens de idiomas específicos em uma pasta chamada _locales, desta forma:

_locales/en/messages.json
_locales/es/messages.json

Formate mensagens no messages.json de cada idioma.

{
  "__MSG_tooltip__": {
      "message": "Hello!",
      "description": "Tooltip Greeting."
  }
}

{
  "__MSG_tooltip__": {
      "message": "Hola!",
      "description": "Tooltip Greeting."
  }
}

Inclua o nome da mensagem no campo de dica em vez da mensagem para ativar a localização.

{
"name": "Tab Flipper",
  ...
  "browser_action": {
    "default_title": "__MSG_tooltip__"
  }
...
}

omnibox

Os usuários podem invocar a funcionalidade de extensão pela omnibox. Inclua o campo "omnibox" no manifesto e designe uma palavra-chave. O exemplo de extensão Pesquisa em nova guia da omnibox usa "nt" como palavra-chave.

{
  "name": "Omnibox New Tab Search",\
  ...
  "omnibox": { "keyword" : "nt" },
  "default_icon": {
    "16": "newtab_search16.png",
    "32": "newtab_search32.png"
  }
  ...
}

Quando o usuário digita "nt" na omnibox, ele ativa a extensão. Para sinalizar isso ao usuário, o ícone fornecido de 16 x 16 é dimensionado em cinza e o inclui na omnibox ao lado do nome da extensão.

Extensão omnibox ativa

A extensão detecta o evento omnibox.onInputEntered. Depois de acionada, a extensão abre uma nova guia contendo uma pesquisa do Google para a entrada do usuário.

chrome.omnibox.onInputEntered.addListener(function(text) {
  // Encode user input for special characters , / ? : @ & = + $ #
  var newURL = 'https://www.google.com/search?q=' + encodeURIComponent(text);
  chrome.tabs.create({ url: newURL });
});

Menu de contexto

Adicione novas opções de menu de contexto concedendo a permissão "contextMenus" no manifesto.

{
  "name": "Global Google Search",
  ...
  "permissions": [
    "contextMenus",
    "storage"
  ],
  "icons": {
    "16": "globalGoogle16.png",
    "48": "globalGoogle48.png",
    "128": "globalGoogle128.png"
  }
  ...
}

O ícone de 16 x 16 é exibido ao lado da nova entrada do menu.

Crie um menu de contexto chamando contextMenus.create no script em segundo plano. Isso precisa ser feito no evento do listener runtime.onInstalled.

chrome.runtime.onInstalled.addListener(function() {
  for (let key of Object.keys(kLocales)) {
    chrome.contextMenus.create({
      id: key,
      title: kLocales[key],
      type: 'normal',
      contexts: ['selection'],
    });
  }
});

const kLocales = {
  'com.au': 'Australia',
  'com.br': 'Brazil',
  'ca': 'Canada',
  'cn': 'China',
  'fr': 'France',
  'it': 'Italy',
  'co.in': 'India',
  'co.jp': 'Japan',
  'com.ms': 'Mexico',
  'ru': 'Russia',
  'co.za': 'South Africa',
  'co.uk': 'United Kingdom'
};

O exemplo do menu de contexto da Pesquisa global do Google cria várias opções da lista em locales.js . Quando uma extensão contém mais de um menu de contexto, o Google Chrome os recolhe automaticamente em um único menu pai.

Vários menus de contexto serão recolhidos

Comandos

As extensões podem definir comandos específicos e vinculá-los a uma combinação de teclas. Registre um ou mais comandos no manifesto, no campo "commands".

{
  "name": "Tab Flipper",
  ...
  "commands": {
    "flip-tabs-forward": {
      "suggested_key": {
        "default": "Ctrl+Shift+Right",
        "mac": "Command+Shift+Right"
      },
      "description": "Flip tabs forward"
    },
    "flip-tabs-backwards": {
      "suggested_key": {
        "default": "Ctrl+Shift+Left",
        "mac": "Command+Shift+Left"
      },
      "description": "Flip tabs backwards"
    }
  }
  ...
}

Os comandos podem ser usados para fornecer atalhos do navegador novos ou alternativos. A extensão de exemplo Tab Flipper detecta o evento commands.onCommand no script em segundo plano e define a funcionalidade para cada combinação registrada.

chrome.commands.onCommand.addListener(function(command) {
  chrome.tabs.query({currentWindow: true}, function(tabs) {
    // Sort tabs according to their index in the window.
    tabs.sort((a, b) => { return a.index < b.index; });
    let activeIndex = tabs.findIndex((tab) => { return tab.active; });
    let lastTab = tabs.length - 1;
    let newIndex = -1;
    if (command === 'flip-tabs-forward')
      newIndex = activeIndex === 0 ? lastTab : activeIndex - 1;
    else  // 'flip-tabs-backwards'
      newIndex = activeIndex === lastTab ? 0 : activeIndex + 1;
    chrome.tabs.update(tabs[newIndex].id, {active: true, highlighted: true});
  });
});

Os comandos também podem criar uma vinculação de teclas que funciona especialmente com a extensão. O exemplo Hello Extensions fornece um comando para abrir o pop-up.

{
  "name": "Hello Extensions",
  "description" : "Base Level Extension",
  "version": "1.0",
  "browser_action": {
    "default_popup": "hello.html",
    "default_icon": "hello_extensions.png"
  },
  "manifest_version": 2,
  "commands": {
    "_execute_browser_action": {
      "suggested_key": {
        "default": "Ctrl+Shift+F",
        "mac": "MacCtrl+Shift+F"
      },
      "description": "Opens hello.html"
    }
  }
}

Como a extensão define um browser_action, ela pode especificar "execute_browser_action" nos comandos para abrir o arquivo pop-up sem incluir um script em segundo plano. Se estiver usando page_action, ele poderá ser substituído por "execute_page_action". Os comandos de navegador e de extensão podem ser usados na mesma extensão.

Substituir páginas

Uma extensão pode substituir e substituir a página da Web "Histórico", "Nova guia" ou "Favoritos" por um arquivo HTML personalizado. Como um pop-up, ele pode incluir lógica e estilo especializados, mas não permite JavaScript inline. Uma única extensão é limitada a substituir apenas uma das três páginas possíveis.

Registre uma página de substituição no manifesto no campo "chrome_url_overrides".

{
  "name": "Awesome Override Extension",
  ...

  "chrome_url_overrides" : {
    "newtab": "override_page.html"
  },
  ...
}

O campo "newtab" precisa ser substituído por "bookmarks" ou "history" ao substituir essas páginas.

<html>
  <head>
  <title>New Tab</title>
  </head>
  <body>
    <h1>Hello World</h1>
  <script src="logic.js"></script>
  </body>
</html>