Реализация страницы настроек

Страница настроек предоставляет пользователям возможность просмотра и изменения настроек (иногда также называемых «предпочтениями» или «параметрами») расширения.

С помощью API WebExtension настройки обычно хранятся с использованием API storage. Реализация страницы настроек состоит из трех шагов:

Напишите HTML-файл, отображающий настройки и позволяющий пользователю их изменять.
Напишите скрипт, подключаемый из HTML-файла, который заполняет страницу настроек данными из хранилища и обновляет сохраненные настройки, когда пользователь их меняет.
Укажите путь к HTML-файлу в качестве ключа options_ui в manifest.json. Таким образом, HTML-документ будет отображаться в менеджере дополнений браузера вместе с именем и описанием расширения.

Примечание: Вы также можете открыть эту страницу программно с помощью функции runtime.openOptionsPage().

Простое расширение

Сначала мы напишем расширение, которое добавляет синюю границу к каждой странице, которую посещает пользователь.

Создайте новую директорию под названием settings, затем создайте в ней файл под названием manifest.json со следующим содержимым:

{
  "manifest_version": 2,
  "name": "Settings example",
  "version": "1.0",

  "content_scripts": [
    {
      "matches": ["<all_urls>"],
      "js": ["borderify.js"]
    }
  ]
}

Это расширение сообщает браузеру загрузить скрипт содержимого под названием "borderify.js" на все веб-страницы, которые посещает пользователь.

Далее создайте файл под названием borderify.js в директории settings, и заполните его следующим содержимым:

document.body.style.border = "10px solid blue";

Это просто добавляет синюю границу к странице.

Теперь установите и протестируйте расширение.

Добавление настроек

Теперь давайте создадим страницу настроек, чтобы позволить пользователю устанавливать цвет границы.

Сначала обновите manifest.json со следующим содержимым:

{
  "manifest_version": 2,
  "name": "Settings example",
  "version": "1.0",

  "content_scripts": [
    {
      "matches": ["<all_urls>"],
      "js": ["borderify.js"]
    }
  ],

  "options_ui": {
    "page": "options.html"
  },

  "permissions": ["storage"],

  "browser_specific_settings": {
    "gecko": {
      "id": "addon@example.com"
    }
  }
}

Мы добавили три новых ключа манифеста:

options_ui: Это устанавливает HTML-документ в качестве страницы настроек (также называемой страницей параметров) для этого расширения.
permissions: Мы будем использовать API storage для хранения настроек, и нам необходимо запросить разрешение на использование этого API.
browser_specific_settings: Вы должны включить идентификатор расширения, чтобы сохранять и извлекать настройки из синхронизированного хранилища.

Далее, так как мы обещали предоставить options.html, давайте создадим его. Создайте файл с этим именем в директории settings и заполните его следующим содержимым:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
  </head>

  <body>
    <form>
      <label>Border color <input type="text" id="color" name="color" /></label>
      <button type="submit">Save</button>
    </form>

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

Это определяет форму <form> с текстовым полем <input> и кнопкой отправки <button>. Также он включает скрипт под названием options.js.

Создайте options.js, снова в директории settings, и заполните его следующим содержимым:

function saveOptions(e) {
  e.preventDefault();
  browser.storage.sync.set({
    color: document.querySelector("#color").value
  });
}

function restoreOptions() {
  function setCurrentChoice(result) {
    document.querySelector("#color").value = result.color || "blue";
  }

  function onError(error) {
    console.log(`Error: ${error}`);
  }

  let getting = browser.storage.sync.get("color");
  getting.then(setCurrentChoice, onError);
}

document.addEventListener("DOMContentLoaded", restoreOptions);
document.querySelector("form").addEventListener("submit", saveOptions);

Это делает две вещи:

При загрузке документа он извлекает значение "color" из хранилища с помощью storage.sync.get(). Если значение не задано, используется значение по умолчанию "blue". Это извлекает значения из хранилища типа sync.
Когда пользователь отправляет форму, нажав «Сохранить», он сохраняет значение текстового поля с помощью storage.sync.set(). Это сохраняет значение в хранилище типа sync.

Примечание: Необходимо указать отдельный файл .js. Вы не можете использовать встроенный JavaScript.

Вы можете сохранить значения настроек в локальном хранилище, если считаете, что локальное хранилище предпочтительнее для вашего расширения.

Примечание: Реализация storage.sync в Firefox зависит от идентификатора дополнения. Если вы используете storage.sync, вы должны установить идентификатор для вашего расширения, используя ключ browser_specific_settings в manifest.json, как показано в примере манифеста выше. См. ошибку Firefox 1323228 для получения дополнительной информации.

Наконец, обновите borderify.js для считывания цвета границы из хранилища:

function onError(error) {
  console.log(`Error: ${error}`);
}

function onGot(item) {
  let color = "blue";
  if (item.color) {
    color = item.color;
  }
  document.body.style.border = `10px solid ${color}`;
}

const getting = browser.storage.sync.get("color");
getting.then(onGot, onError);

На этом этапе полное расширение должно выглядеть так:

settings/
    borderify.js
    manifest.json
    options.html
    options.js

Теперь:

перезагрузите расширение
загрузите веб-страницу
перейдите в "about:addons", чтобы открыть настройки, нажмите кнопку "Настройки" рядом с записью расширения и измените цвет границы.
перезагрузите веб-страницу, чтобы увидеть разницу.

Дополнительная информация

options_ui документация по ключу manifest.json
storage справочная документация по API
открытие страницы настроек напрямую из вашего расширения с помощью API runtime.openOptionsPage()
Пример страницы настроек:
- favourite-colour

© 2005–2023 MDN contributors.
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Implement_a_settings_page