Proposer des options aux utilisateurs

Permettre aux utilisateurs de personnaliser le comportement d'une extension en fournissant une page d'options. Pour afficher les options d'une extension, effectuez un clic droit sur l'icône correspondante dans la barre d'outils, puis sélectionnez les options. Sinon, accédez à la page de gestion des extensions sur chrome://extensions, localisez l'extension souhaitée, cliquez sur Détails, puis sélectionnez le lien des options.

Écrire la page d'options

Vous trouverez ci-dessous un exemple de page d'options.

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

Enregistrer les options préférées d'un utilisateur sur plusieurs appareils à l'aide de l'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);

Comportement de la page "Déclarer des options"

Il existe deux types de pages d'options d'extension : page complète et intégrée. Le type des options est déterminé par la manière dont elles sont déclarées dans le fichier manifeste.

Options pleine page

La page d'options d'une extension s'affiche dans un nouvel onglet. Le fichier d'options HTML est enregistré sous le champ options_page.

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

Options pleine page

Options intégrées

Les options intégrées permettent aux utilisateurs d'ajuster les options des extensions sans quitter la page de gestion des extensions dans une zone intégrée. Pour déclarer une option d'intégration, enregistrez le fichier HTML sous le champ options_ui du fichier manifeste de l'extension, avec la clé open_in_tab définie sur "false".

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

Options intégrées

  • page (chaîne)

    Chemin d'accès à la page d'options, en lien avec la racine de l'extension.

  • open_in_tab (boolean)

    Spécifiez false pour déclarer une page d'options intégrée. Si la valeur est true, la page d'options de l'extension est ouverte dans un nouvel onglet au lieu d'être intégrée à chrome://extensions.

Tenez compte des différences

Les pages d'options intégrées à l'intérieur de chrome://extensions présentent de légères différences de comportement, car elles ne sont pas hébergées dans leurs propres onglets.

Créer un lien vers la page des options

Une extension peut créer un lien direct vers la page d'options en appelant 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

Le code de la page des options intégrées de l'extension n'est pas hébergé dans un onglet, ce qui affecte la façon dont l'API Tabs peut être utilisée:

  • La méthode tabs.query ne trouvera jamais d'onglet dans l'URL de la page d'options d'une extension.
  • tabs.onCreated ne se déclenche pas lorsque la page d'options est ouverte.
  • tabs.onUpdated ne se déclenchera pas lorsque l'état de chargement de la page d'options change.
  • Vous ne pouvez pas utiliser tabs.connect ni tabs.sendMessage pour communiquer avec la page d'options.

L'utilisation de runtime.connect et runtime.sendMessage permet de contourner ces restrictions, si la page d'options doit manipuler l'onglet conteneur.

API de messagerie

Si la page d'options d'une extension envoie un message à l'aide de runtime.connect ou runtime.sendMessage, l'onglet de l'expéditeur n'est pas défini, et l'URL de l'expéditeur est l'URL de la page d'options.

Taille

Les options d'intégration doivent déterminer automatiquement leur propre taille en fonction du contenu de la page. Cependant, la zone intégrée peut ne pas trouver une taille adaptée pour certains types de contenu. Ce problème est le plus courant pour les pages d'options qui ajustent la forme de leur contenu en fonction de la taille de la fenêtre.

Si cela pose problème, fournissez des dimensions minimales fixes pour la page d'options afin de vous assurer que la page intégrée trouvera une taille appropriée.