Oferecer opções aos usuários

Permite que os usuários personalizem o comportamento de uma extensão fornecendo uma página de opções. Para ver as opções de uma extensão, o usuário pode clicar com o botão direito do mouse no ícone dela na barra de ferramentas e selecionar "Opções" ou acessar a página de gerenciamento de extensões em chrome://extensions, localizar a extensão desejada, clicar em Detalhes e selecionar o link de opções.

Escrever a página de opções

Confira abaixo um exemplo de página de opções.

<!DOCTYPE html>
<html>
<head><title>My Test Extension Options</title></head>
<body>

Favorite color:
<select id="color">
 <option value="red">red</option>
 <option value="green">green</option>
 <option value="blue">blue</option>
 <option value="yellow">yellow</option>
</select>

<label>
  <input type="checkbox" id="like">
  I like colors.
</label>

<div id="status"></div>
<button id="save">Save</button>

<script src="options.js"></script>
</body>
</html>

Salve as opções preferidas de um usuário em todos os dispositivos usando a API storage.sync.

// Saves options to chrome.storage
function save_options() {
  var color = document.getElementById('color').value;
  var likesColor = document.getElementById('like').checked;
  chrome.storage.sync.set({
    favoriteColor: color,
    likesColor: likesColor
  }, function() {
    // Update status to let user know options were saved.
    var status = document.getElementById('status');
    status.textContent = 'Options saved.';
    setTimeout(function() {
      status.textContent = '';
    }, 750);
  });
}

// Restores select box and checkbox state using the preferences
// stored in chrome.storage.
function restore_options() {
  // Use default value color = 'red' and likesColor = true.
  chrome.storage.sync.get({
    favoriteColor: 'red',
    likesColor: true
  }, function(items) {
    document.getElementById('color').value = items.favoriteColor;
    document.getElementById('like').checked = items.likesColor;
  });
}
document.addEventListener('DOMContentLoaded', restore_options);
document.getElementById('save').addEventListener('click',
    save_options);

Declarar o comportamento da página de opções

Há dois tipos de páginas de opções de extensão disponíveis: página inteira e incorporada. O tipo de opções é determinado pela forma como ele é declarado no manifesto.

Opções de página inteira

A página de opções de uma extensão será exibida em uma nova guia. O arquivo HTML de opções está listado registrado no campo options_page.

{
  "name": "My extension",
  ...
  "options_page": "options.html",
  ...
}

Opções de página inteira

Opções incorporadas

Com as opções incorporadas, os usuários podem ajustar as opções de extensão sem sair da página de gerenciamento de extensões em uma caixa incorporada. Para declarar opções incorporadas, registre o arquivo HTML no campo options_ui do manifesto da extensão, com a chave open_in_tab definida como false.

{
  "name": "My extension",
  ...
  "options_ui": {
    "page": "options.html",
    "open_in_tab": false
  },
  ...
}

Opções incorporadas

  • page (string)

    Caminho para a página de opções, relativo à raiz da extensão.

  • open_in_tab (booleano)

    Especifique como false para declarar uma página de opções incorporada. Se true, a página de opções da extensão será aberta em uma nova guia em vez de ser incorporada em chrome://extensions.

Considere as diferenças

As páginas de opções incorporadas em chrome://extensions têm algumas diferenças sutis de comportamento relacionadas a não serem hospedadas nas próprias guias.

Inserir links para a página de opções

Uma extensão pode se vincular diretamente à página de opções chamando chrome.runtime.openOptionsPage() .

<button id="go-to-options">Go to options</button>

document.querySelector('#go-to-options').addEventListener('click', function() {
  if (chrome.runtime.openOptionsPage) {
    chrome.runtime.openOptionsPage();
  } else {
    window.open(chrome.runtime.getURL('options.html'));
  }
});

API Tabs

O código da página de opções incorporadas da extensão não é hospedado em uma guia, afetando a forma como a API Tabs pode ser usada:

  • tabs.query nunca vai encontrar uma guia no URL da página de opções de uma extensão.
  • tabs.onCreated não será acionado quando a página de opções for aberta.
  • tabs.onUpdated não será acionado quando o estado de carregamento da página de opções mudar.
  • tabs.connect ou tabs.sendMessage não podem ser usados para se comunicar com a página de opções.

Usar runtime.connect e runtime.sendMessage é uma solução alternativa para essas restrições, se a página de opções precisar manipular a guia que a contém.

APIs de mensagens

Se a página de opções de uma extensão enviar uma mensagem usando runtime.connect ou runtime.sendMessage, a guia do remetente não será definida, e o URL do remetente será o URL da página de opções.

Dimensionamento

As opções incorporadas determinam automaticamente o próprio tamanho com base no conteúdo da página. No entanto, a caixa incorporada pode não encontrar um bom tamanho para alguns tipos de conteúdo. Esse problema é mais comum em páginas de opções que ajustam o formato do conteúdo com base no tamanho da janela.

Se isso for um problema, forneça dimensões mínimas fixas para a página de opções e garanta que a página incorporada encontre um tamanho adequado.