Oferecer opções aos usuários

Permita que os usuários personalizem o comportamento de uma extensão oferecendo uma página de opções. Um usuário pode ver as opções de uma extensão clicando com o botão direito do mouse no ícone da extensão na barra de ferramentas e selecionando as opções. Ou acessando a página de gerenciamento de extensões em chrome://extensions, localizando a extensão desejada, clicando em Detalhes e selecionando o link de opções.

Escrever a página de opções

Veja 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>

Use a API storage.sync para salvar as opções preferidas de um usuário em vários dispositivos.

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

Comportamento da página "Declarar opções"

Há dois tipos disponíveis de páginas de opções de extensão, página completa e incorporada. O tipo de opções é determinado pela forma como elas são declaradas 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 é listado registrado no campo options_page.

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

Opções de página inteira

Opções incorporadas

As opções incorporadas permitem que os usuários ajustem as opções de extensões sem sair da página de gerenciamento de extensões dentro de uma caixa incorporada. Para declarar uma opção incorporada, registre o arquivo HTML no campo options_ui do manifesto de extensão, com a chave open_in_tab definida como falsa.

{
  "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, em relação à raiz da extensão.

  • open_in_tab (boolean)

    Especifique como false para declarar uma página de opções incorporadas. Se for true, a página de opções da extensão será aberta em uma nova guia em vez de 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 à não hospedagem nas próprias guias.

Link para a página de opções

Uma extensão pode ser vinculada 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, o que afeta a forma como a API Tabs pode ser usada:

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

O uso de 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 o 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.

Tamanho

O tamanho das opções incorporadas deve ser determinado automaticamente com base no conteúdo da página. No entanto, a caixa incorporada pode não ter um tamanho adequado para alguns tipos de conteúdo. Esse problema é mais comum para páginas de opções que ajustam a forma 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 para garantir que a página incorporada encontre um tamanho adequado.