Proposer des options aux utilisateurs

Tout comme les extensions permettent aux utilisateurs de personnaliser le navigateur Chrome, la page d'options permet de personnaliser l'extension. Utilisez des options pour activer des fonctionnalités et permettre aux utilisateurs de choisir celles qui répondent à leurs besoins.

Accéder à la page des options

Les utilisateurs peuvent accéder à la page d'options par lien direct ou en effectuant un clic droit sur l'icône de l'extension dans la barre d'outils, puis en sélectionnant "Options". Les utilisateurs peuvent également accéder à la page d'options en ouvrant chrome://extensions, en recherchant l'extension souhaitée, en cliquant sur Détails, puis en sélectionnant le lien vers les options.

Lien vers la page des options dans l'interface utilisateur
Lien vers la page des options.
Page des options du menu contextuel
Effectuez un clic droit sur l'icône de l'extension.

Écrire la page d'options

Voici un exemple de page d'options :

options.html:

<!DOCTYPE html>
<html>
  <head>
    <title>My Test Extension Options</title>
  </head>
  <body>
    <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>

Vous trouverez ci-dessous un exemple de script d'options. Enregistrez-le dans le même dossier que options.html. Cela permet d'enregistrer les options préférées de l'utilisateur sur tous les appareils à l'aide de l'API storage.sync.

options.js:

// Saves options to browser.storage
const saveOptions = () => {
  const color = document.getElementById('color').value;
  const likesColor = document.getElementById('like').checked;

  browser.storage.sync.set(
    { favoriteColor: color, likesColor: likesColor },
    () => {
      // Update status to let user know options were saved.
      const status = document.getElementById('status');
      status.textContent = 'Options saved.';
      setTimeout(() => {
        status.textContent = '';
      }, 750);
    }
  );
};

// Restores select box and checkbox state using the preferences
// stored in browser.storage.
const restoreOptions = () => {
  browser.storage.sync.get(
    { favoriteColor: 'red', likesColor: true },
    (items) => {
      document.getElementById('color').value = items.favoriteColor;
      document.getElementById('like').checked = items.likesColor;
    }
  );
};

document.addEventListener('DOMContentLoaded', restoreOptions);
document.getElementById('save').addEventListener('click', saveOptions);

Enfin, ajoutez l'autorisation "storage" au fichier manifeste de l'extension :

manifest.json:

{
  "name": "My extension",
  ...
  "permissions": [
    "storage"
  ]
  ...
}

Déclarer le comportement de la page d'options

Il existe deux types de pages d'options d'extension : pleine page et intégrée. Le type de page d'options est déterminé par la façon dont elle est déclarée dans le fichier manifeste.

Options de page entière

Une page d'options en plein écran s'affiche dans un nouvel onglet. Enregistrez le fichier HTML des options dans le fichier manifeste, dans le champ "options_page".

manifest.json:

{
  "name": "My extension",
  ...
  "options_page": "options.html",
  ...
}
Options de page entière
Options de la page entière dans un nouvel onglet.

Options intégrées

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

manifest.json:

{
  "name": "My extension",
  ...
  "options_ui": {
    "page": "options.html",
    "open_in_tab": false
  },
  ...
}
Options intégrées
Options d'intégration.
page (chaîne)
Spécifie le chemin d'accès à la page d'options, par rapport à la racine de l'extension.
open_in_tab (booléen)
Indique si la page d'options de l'extension doit s'ouvrir dans un nouvel onglet. Si la valeur est définie sur false, la page d'options de l'extension est intégrée à chrome://extensions au lieu d'être ouverte dans un nouvel onglet.

Tenir compte des différences

Les pages d'options intégrées dans chrome://extensions présentent de légères différences de comportement par rapport aux pages d'options dans les onglets.

Lien vers la page des options

Une extension peut être associée directement à la page d'options en appelant browser.runtime.openOptionsPage(). Par exemple, il peut être ajouté à un pop-up :

popup.html:

<button id="go-to-options">Go to options</button>
<script src="popup.js"></script>

popup.js:

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

API Tabs

Étant donné que le code des options intégrées n'est pas hébergé dans un onglet, l'API Tabs ne peut pas être utilisée. Utilisez plutôt runtime.connect() et runtime.sendMessage() si la page d'options doit manipuler l'onglet contenant.

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 ne sera pas défini et l'URL de l'expéditeur sera celle de la page d'options.

Taille

Les options intégrées doivent déterminer automatiquement leur propre taille en fonction du contenu de la page. Toutefois, il est possible que la boîte intégrée ne trouve pas la taille idéale pour certains types de contenus. Ce problème est plus fréquent 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, indiquez des dimensions minimales fixes pour la page d'options afin de vous assurer que la page intégrée trouve une taille appropriée.