Projetar a interface do usuário

A interface do usuário da extensão precisa ser útil e mínima. Assim como as extensões, a interface precisa personalizar ou melhorar a experiência de navegação sem 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 interface em uma extensão.

Ativar a extensão em todas as páginas

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

Registrar a 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 mostram um banner colorido com até quatro caracteres na parte de cima do ícone do navegador. Eles só podem ser usados por extensões que declaram "browser_action" no manifesto.

Use selos para indicar o estado da extensão. O exemplo de evento "Beber água" mostra um selo com "ON" para indicar 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 em páginas selecionadas

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

Declarar a 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 apenas quando a extensão estiver disponível para os usuários. Caso contrário, ele será mostrado em tons de cinza.

Definir regras para ativar a extensão

Defina regras para quando a extensão pode ser usada chamando chrome.declarativeContent no runtime.onInstalled listener em um script de plano de fundo. A extensão de exemplo Ação de página por URL define uma condição de que o URL precisa incluir um 'g'. Se a condição for atendida, a extensão vai 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 em um mapa estático no 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 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. É recomendável incluir vários tamanhos para escalonar o espaço de 16 dip. No mínimo, os tamanhos 16x16 e 32x32 são recomendados.

{
  "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 ser distorcidos. Se nenhum ícone for fornecido, o Chrome vai adicionar um genérico à barra de ferramentas.

Criar e registrar ícones adicionais

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

Registre ícones no manifesto no campo "icons".

{
  "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

Pop-up

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

O pop-up de exemplo do evento "Beber água" mostra as opções de timer disponíveis. Os usuários definem um alarme clicando em um dos botões fornecidos.

<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'});
  }
});

Dica

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

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});
});

As strings de localidade especializadas são implementadas com a internacionalização. Crie diretórios para hospedar mensagens específicas do idioma em uma pasta chamada _locales, como esta:

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

Formate mensagens dentro de 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. A extensão de exemplo Pesquisa na 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, a extensão é ativada. Para sinalizar isso ao usuário, ela mostra o ícone 16x16 fornecido em tons de cinza e o inclui na omnibox ao lado do nome da extensão.

A extensão detecta o omnibox.onInputEntered evento. 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 16x16 é mostrado ao lado da nova entrada de menu.

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

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 de menu de contexto Pesquisa global do Google cria várias opções na 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.

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 de navegador novos ou alternativos. A extensão de exemplo Tab Flipper detecta o evento commands.onCommand no script de plano de fundo e define 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 oferece 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" em os comandos para abrir o arquivo pop-up sem incluir um script de plano de fundo. Se você estiver usando page_action, ele poderá ser substituído por "execute_page_action". Os comandos do navegador e da 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 aquelas páginas.

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