Arbeiten mit userScripts
Warnung:
Dies ist die Dokumentation für die veraltete userScripts
API. Sie ist in Firefox für Manifest V2 verfügbar. Für die Funktionalität mit Benutzerskripten in Manifest V3 siehe die neue userScripts
API.
Durch die Implementierung von userScripts können Erweiterungsentwickler ändern, wie Webseiten aussehen und/oder funktionieren, um besser den Bedürfnissen der Benutzer gerecht zu werden.
Implementieren Sie userScripts in Ihrer Erweiterung mit den folgenden Schritten:
- Definieren Sie das Skript im Manifest der Erweiterung mithilfe des Schlüssels
"user_scripts"
. - Registrieren Sie das userScript
- Implementieren Sie die Funktionen des userScripts
Gehen wir die Schritte anhand einer kleinen Beispiel-Webextension durch, die den Prozess veranschaulicht. Das Beispiel ist im webextensions-examples Repository auf GitHub verfügbar.
userScripts Manifest
Ein Benutzerskript wird durch den Inhalt des user_scripts Schlüssels des Manifests der Erweiterung identifiziert. Die Mindestinformationen für den user_scripts
Schlüssel wären:
"user_scripts": {
"api_script": "customUserScriptAPIs.js"
}
Die Eigenschaft "api_script" gibt den Pfad zur JavaScript-Datei an, die den Code für das userScript
enthält.
Laden der Beispielerweiterung
Nachdem Sie das Beispiel heruntergeladen haben:
Navigieren Sie zu about:debugging, klicken Sie auf Temporäres Add-on laden… und doppelklicken Sie auf das Manifest der Erweiterung.
Der standardmäßig mit dem Beispiel enthaltene Code ermöglicht es Ihnen, ein userScript
zu laden, das den Inhalt von Seiten frisst, die dem Hosteintrag entsprechen. Nehmen Sie alle gewünschten Änderungen vor, bevor Sie unten im Panel auf die Schaltfläche Skript registrieren klicken.
Im folgenden Bild wird die Erweiterung den Inhalt von Seiten "fressen", deren Domainname mit .org endet. Dies ist das Standardverhalten für diese Erweiterung.
Nichts wird passieren, bis Sie auf die Schaltfläche Skript registrieren klicken. Die Schaltfläche implementiert das Benutzerskript gemäß den Einstellungen in diesem Dialog. Das bedeutet, dass Sie mit dem Verhalten des Skripts experimentieren können, ohne selbst eine Erweiterung implementieren zu müssen.
Registrieren des userScripts
Bevor ein userScript ausgeführt werden kann, muss es mithilfe der Methode userScripts.register()
registriert werden. Hier ist der Code zum Registrieren der Beispielerweiterung:
async function registerScript() {
const params = {
hosts: stringToArray(hostsInput.value),
code: codeInput.value,
excludeMatches: stringToArray(excludeMatchesInput.value),
includeGlobs: stringToArray(includeGlobsInput.value),
excludeGlobs: stringToArray(excludeGlobsInput.value),
runAt: runAtInput.value,
matchAboutBlank: stringToBool(matchAboutBlankInput.value),
allFrames: stringToBool(allFramesInput.value),
scriptMetadata: { name: scriptNameInput.value || null },
};
// Store the last submitted values to the extension storage
// (so that they can be restored when the popup is opened
// the next time).
await browser.storage.local.set({
lastSetValues: params,
});
try {
// Clear the last userScripts.register result.
lastResultEl.textContent = "";
await browser.runtime.sendMessage(params);
lastResultEl.textContent = "UserScript successfully registered";
// Clear the last userScripts.register error.
lastErrorEl.textContent = "";
// Clear the last error stored.
await browser.storage.local.remove("lastError");
} catch (e) {
// There was an error on registering the userScript,
// let's show the error message in the popup and store
// the last error into the extension storage.
const lastError = `${e}`;
// Show the last userScripts.register error.
lastErrorEl.textContent = lastError;
// Store the last error.
await browser.storage.local.set({ lastError });
}
}
Dieser Code initialisiert zuerst das Parameterobjekt, um Werte an die userScripts.register Methode zu übergeben.
Implementieren der Funktionen des userScript
Sobald das Skript registriert ist, navigieren Sie zu einer Seite, deren Domainname mit .org endet, und Sie werden etwas Ähnliches sehen: