Implementieren einer Einstellungsseite
Eine Einstellungsseite gibt den Benutzern eine Möglichkeit, Einstellungen (manchmal auch als "Präferenzen" oder "Optionen" bezeichnet) für die Erweiterung zu sehen und zu ändern.
Mit den WebExtension-APIs werden Einstellungen in der Regel über die storage
API gespeichert. Die Implementierung einer Einstellungsseite erfolgt in drei Schritten:
- Schreiben Sie eine HTML-Datei, die Einstellungen anzeigt und dem Benutzer ermöglicht, diese zu ändern.
- Schreiben Sie ein Skript, das von der HTML-Datei eingebunden wird, um die Einstellungsseite aus dem Speicher zu füllen und gespeicherte Einstellungen zu aktualisieren, wenn der Benutzer sie ändert.
- Setzen Sie den Pfad zur HTML-Datei als den
options_ui
Schlüssel inmanifest.json
. Dadurch wird das HTML-Dokument im Add-on-Manager des Browsers neben dem Namen und der Beschreibung der Erweiterung angezeigt.
Hinweis: Sie können diese Seite auch programmgesteuert mit der runtime.openOptionsPage()
Funktion öffnen.
Eine einfache Erweiterung
Zuerst schreiben wir eine Erweiterung, die jeder Seite, die der Benutzer besucht, einen blauen Rand hinzufügt.
Erstellen Sie ein neues Verzeichnis namens settings
und dann darin eine Datei namens manifest.json
mit folgendem Inhalt:
{
"manifest_version": 2,
"name": "Settings example",
"version": "1.0",
"content_scripts": [
{
"matches": ["<all_urls>"],
"js": ["borderify.js"]
}
]
}
Diese Erweiterung weist den Browser an, ein Inhalts-Skript namens "borderify.js" in alle Webseiten zu laden, die der Benutzer besucht.
Erstellen Sie als nächstes eine Datei namens borderify.js
im Verzeichnis settings
und geben Sie ihr folgenden Inhalt:
document.body.style.border = "10px solid blue";
Dies fügt der Seite lediglich einen blauen Rand hinzu.
Nun installieren und testen Sie die Erweiterung.
Einstellungen hinzufügen
Erstellen wir nun eine Einstellungsseite, die es dem Benutzer erlaubt, die Farbe des Randes festzulegen.
Aktualisieren Sie zunächst manifest.json
, sodass es diesen Inhalt hat:
{
"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"
}
}
}
Wir haben drei neue Manifest-Schlüssel hinzugefügt:
options_ui
-
Dies legt ein HTML-Dokument als Einstellungsseite (auch als Optionsseite bezeichnet) für diese Erweiterung fest.
permissions
-
Wir nutzen die
storage
API, um die Einstellungen zu speichern, und müssen um Erlaubnis bitten, diese API zu verwenden. browser_specific_settings
-
Sie müssen eine Erweiterungs-ID angeben, um Einstellungen aus dem synchronisierten Speicher speichern und abrufen zu können.
Da wir versprochen haben, options.html
bereitzustellen, erstellen wir es als Nächstes. Erstellen Sie eine Datei mit diesem Namen im Verzeichnis settings
und geben Sie ihr folgenden Inhalt:
<!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>
Dies definiert ein <form>
mit einem beschrifteten Text-<input>
und einem <button>
zum Absenden. Es enthält auch ein Skript namens options.js
.
Erstellen Sie options.js
ebenfalls im Verzeichnis settings
und geben Sie ihr folgenden Inhalt:
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);
Dies tut zwei Dinge:
- Wenn das Dokument geladen ist, ruft es den Wert von
"color"
aus dem Speicher mitstorage.sync.get()
ab. Wenn der Wert nicht gesetzt ist, wird der Standardwert"blue"
verwendet. Dies ruft die Werte aus demsync
Speicherbereich ab. - Wenn der Benutzer das Formular durch Klicken auf "Speichern" absendet, speichert es den Wert des Textfeldes mit
storage.sync.set()
. Dies speichert den Wert imsync
Speicherbereich.
Hinweis: Es ist erforderlich, eine separate .js
Datei anzugeben. Sie können kein JavaScript inline verwenden.
Sie könnten die Einstellungswerte stattdessen im lokalen Speicher speichern, wenn Sie der Meinung sind, dass der lokale Speicher für Ihre Erweiterung vorzuziehen ist.
Hinweis: Die Implementierung von storage.sync
in Firefox stützt sich auf die Add-on-ID. Wenn Sie storage.sync
verwenden, müssen Sie eine ID für Ihre Erweiterung mit dem browser_specific_settings
Schlüssel in manifest.json
festlegen, wie im obigen Beispielmanifest gezeigt. Siehe Firefox Bug 1323228 für verwandte Informationen.
Aktualisieren Sie schließlich borderify.js
, um die Randfarbe aus dem Speicher zu lesen:
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);
An diesem Punkt sollte die vollständige Erweiterung wie folgt aussehen:
settings/ borderify.js manifest.json options.html options.js
Jetzt:
- laden Sie die Erweiterung erneut
- laden Sie eine Webseite
- besuchen Sie "
about:addons
", um die Einstellungen zu öffnen, und klicken Sie auf die Schaltfläche "Einstellungen" neben dem Eintrag der Erweiterung, um die Randfarbe zu ändern. - laden Sie die Webseite erneut, um den Unterschied zu sehen.
Mehr erfahren
-
options_ui
Schlüssel dermanifest.json
Referenzdokumentation -
storage
API Referenzdokumentation -
Öffnen Sie die Einstellungsseite direkt von Ihrer Erweiterung mit der
runtime.openOptionsPage()
API -
Einstellungsseitenbeispiel: