JavaScript-APIs
JavaScript-APIs für WebExtensions können innerhalb der Hintergrundskripte der Erweiterung und in allen anderen mit der Erweiterung gebündelten Dokumenten verwendet werden, einschließlich Browseraktionen oder Seitenaktionen Popups, Seitenleisten, Optionsseiten oder neue Tab-Seiten. Einige dieser APIs können auch von den Inhaltsskripten einer Erweiterung aufgerufen werden. (Siehe die Liste im Inhaltsskript-Leitfaden.)
Um die leistungsfähigeren APIs zu nutzen, müssen Sie in der manifest.json
Ihrer Erweiterung Berechtigungen anfordern.
Sie können auf die APIs mit dem browser
-Namespace zugreifen:
function logTabs(tabs) {
console.log(tabs);
}
browser.tabs.query({ currentWindow: true }, logTabs);
Viele der APIs sind asynchron und geben ein Promise
zurück:
function logCookie(c) {
console.log(c);
}
function logError(e) {
console.error(e);
}
let setCookie = browser.cookies.set({ url: "https://developer.mozilla.org/" });
setCookie.then(logCookie, logError);
Unterschiede zwischen Browser-APIs
Beachten Sie, dass dies sich von Googles Chromes Erweiterungssystem unterscheidet, das den chrome
-Namespace anstelle von browser
verwendet und Callbacks anstelle von Promises für asynchrone Funktionen einsetzt. Als Portierungshilfe unterstützt die Firefox-Implementierung der WebExtensions-APIs sowohl chrome
und Callbacks als auch browser
und Promises. Mozilla hat außerdem ein Polyfill geschrieben, das es ermöglicht, dass Code, der browser
und Promises verwendet, unverändert in Chrome funktioniert: https://github.com/mozilla/webextension-polyfill.
Firefox implementiert diese APIs auch unter dem chrome
-Namespace mit Callbacks. Dies ermöglicht es, dass Code, der für Chrome geschrieben wurde, weitgehend unverändert in Firefox für die hier dokumentierten APIs funktioniert.
Microsoft Edge verwendet den browser
-Namespace, unterstützt jedoch noch keine auf Promises basierende asynchrone APIs. In Edge müssen vorerst asynchrone APIs Callbacks verwenden.
Nicht alle Browser unterstützen alle APIs: Details finden Sie unter Browserunterstützung für JavaScript-APIs und Chrome-Inkompatibilitäten.
Beispiele
Durch die JavaScript-API-Auflistungen hinweg veranschaulichen kurze Codebeispiele, wie die API verwendet wird. Sie können mit den meisten dieser Beispiele in der Konsole im Toolbox experimentieren. Sie müssen jedoch Toolbox im Kontext einer Web-Erweiterung ausführen. Öffnen Sie dazu about:debugging
, wählen Sie dann Dieser Firefox, klicken Sie auf Untersuchen bei einer installierten oder temporären Erweiterung und öffnen Sie die Konsole. Sie können dann den Beispielcode in die Konsole einfügen und ausführen.
Zum Beispiel sehen Sie hier das erste Codebeispiel auf dieser Seite, ausgeführt in der Toolbox-Konsole in Firefox Developer Edition:
JavaScript-API-Auflistung
Siehe unten für eine vollständige Liste der JavaScript-APIs:
- action
Lesen und Ändern von Attributen und Abhören von Klicks auf den Browsersymbolleisten-Button, der mit dem
action
-Manifest-Schlüssel definiert ist.- alarms
Planen Sie Code so, dass er zu einem bestimmten Zeitpunkt in der Zukunft ausgeführt wird. Dies ähnelt
Window.setTimeout()
undWindow.setInterval()
, mit dem Unterschied, dass diese Funktionen nicht mit Hintergrundseiten funktionieren, die bei Bedarf geladen werden.- bookmarks
Die WebExtensions
bookmarks
API ermöglicht es einer Erweiterung, mit dem Lesezeichen-System des Browsers zu interagieren und es zu manipulieren. Sie können es verwenden, um Seiten zu bookmarken, vorhandene Lesezeichen abzurufen und Lesezeichen zu bearbeiten, zu entfernen und zu organisieren.- browserAction
Lesen und Ändern von Attributen sowie Reagieren auf Klicks auf die Schaltfläche in der Browser-Symbolleiste, die mit dem Manifest-Key
browser_action
definiert ist.- browserSettings
Ermöglicht einer Erweiterung, bestimmte globale Browsereinstellungen zu ändern. Jede Eigenschaft dieser API ist ein
types.BrowserSetting
-Objekt, das die Möglichkeit bietet, eine bestimmte Einstellung zu ändern.- browsingData
Ermöglicht Erweiterungen, die Daten zu löschen, die beim Surfen des Nutzers angesammelt werden.
- captivePortal
Bestimmen Sie den Zustand des Captive Portals der Verbindung des Benutzers. Ein Captive Portal ist eine Webseite, die angezeigt wird, wenn ein Benutzer sich erstmals mit einem Wi-Fi-Netzwerk verbindet. Der Benutzer gibt Informationen an oder führt auf der Captive-Portal-Webseite eine Aktion aus, um umfassenderen Zugang zu Netzwerkressourcen zu erhalten, wie beispielsweise das Akzeptieren von Bedingungen oder das Durchführen einer Zahlung.
- clipboard
Die WebExtension
clipboard
API (die sich von der standardmäßigen Clipboard-API unterscheidet) ermöglicht einer Erweiterung, Elemente in die Systemzwischenablage zu kopieren. Derzeit unterstützt die WebExtensionclipboard
API nur das Kopieren von Bildern, aber es ist geplant, auch das Kopieren von Text und HTML in der Zukunft zu unterstützen.- commands
Hören Sie darauf, wenn der Benutzer Befehle ausführt, die Sie mit dem
commands
manifest.json-Schlüssel registriert haben.- contentScripts
Verwenden Sie diese API, um Inhaltsskripte zu registrieren. Das Registrieren eines Inhaltsskripts weist den Browser an, die angegebenen Inhaltsskripte in Seiten einzufügen, die den angegebenen URL-Mustern entsprechen.
- contextualIdentities
Arbeiten Sie mit kontextuellen Identitäten: auflisten, erstellen, entfernen und aktualisieren von kontextuellen Identitäten.
- cookies
Ermöglicht Erweiterungen das Abrufen und Setzen von Cookies sowie Benachrichtigungen über deren Änderungen.
- declarativeNetRequest
Diese API ermöglicht es Erweiterungen, Bedingungen und Aktionen festzulegen, die beschreiben, wie Netzwerkanforderungen gehandhabt werden sollen. Diese deklarativen Regeln ermöglichen es dem Browser, Netzwerkanforderungen zu bewerten und zu ändern, ohne die Erweiterungen über einzelne Netzwerkanforderungen zu benachrichtigen.
- devtools
Ermöglicht Erweiterungen, mit den Developer_Tools des Browsers zu interagieren. Sie verwenden diese API, um Entwicklerwerkzeug-Seiten zu erstellen, mit dem Fenster zu interagieren, das inspiziert wird, und die Netzwerkverwendung der Seite zu inspizieren.
- dns
Ermöglicht einer Erweiterung das Auflösen von Domainnamen.
- dom
Zugriff auf spezielle, nur für Erweiterungen verfügbare DOM-Funktionen.
- downloads
Ermöglicht Erweiterungen, mit dem Download-Manager des Browsers zu interagieren. Sie können dieses API-Modul verwenden, um Dateien herunterzuladen, Downloads zu stornieren, zu pausieren, fortzusetzen und heruntergeladene Dateien im Dateimanager anzuzeigen.
- events
Gewöhnliche Typen, die von APIs verwendet werden, die Ereignisse auslösen.
- extension
Dienstprogramme im Zusammenhang mit Ihrer Erweiterung. Erhalten Sie URLs zu Ressourcensammlungen mit Ihrer Erweiterung. Erhalten Sie das
Window
-Objekt für die Seiten Ihrer Erweiterung. Erhalten Sie die Werte für verschiedene Einstellungen.- extensionTypes
Einige allgemeine Typen, die in anderen WebExtension-APIs verwendet werden.
- find
Findet Text auf einer Webseite und hebt die Übereinstimmungen hervor.
- history
Verwenden Sie die
history
API, um mit dem Browserverlauf zu interagieren.- i18n
Funktionen zur Internationalisierung Ihrer Erweiterung. Sie können diese APIs verwenden, um lokalisierte Zeichenfolgen aus mit Ihrer Erweiterung verpackten Lokalisierungsdateien zu erhalten, die aktuelle Sprache des Browsers zu ermitteln und den Wert des Accept-Language Headers herauszufinden.
- identity
Verwenden Sie die
identity
API, um einen OAuth2 Autorisierungscode oder Zugriffstoken zu erhalten, mit dem eine Erweiterung dann auf Benutzerdaten von einem Dienst zugreifen kann, der OAuth2-Zugriff unterstützt (wie Google oder Facebook).- idle
Ermitteln Sie, wann das System des Benutzers im Leerlauf, gesperrt oder aktiv ist.
- management
Erhalten Sie Informationen über installierte Add-ons.
Fügen Sie Elemente zum Menüsystem des Browsers hinzu.
- notifications
Zeigen Sie Benachrichtigungen dem Benutzer an, indem Sie den Benachrichtigungsmechanismus des zugrunde liegenden Betriebssystems verwenden. Da diese API den Benachrichtigungsmechanismus des Betriebssystems nutzt, können die Details, wie Benachrichtigungen erscheinen und sich verhalten, abhängig vom Betriebssystem und den Einstellungen des Benutzers unterschiedlich sein.
- omnibox
Ermöglicht Erweiterungen die Implementierung von benutzerdefiniertem Verhalten, wenn der Benutzer in die Adressleiste des Browsers tippt.
- pageAction
Lesen und Ändern von Attributen und Hören auf Klicks auf den mit dem
page_action
Manifest-Schlüssel definierten Schaltfläche in der Adressleiste.- permissions
Ermöglicht es Erweiterungen, zur Laufzeit zusätzliche Berechtigungen anzufordern, nachdem sie installiert wurden.
- pkcs11
Die
pkcs11
API ermöglicht es einer Erweiterung, PKCS #11-Sicherheitsmodule aufzulisten und sie dem Browser als Quellen für Schlüssel und Zertifikate zugänglich zu machen.- privacy
Zugriff auf verschiedene datenschutzbezogene Browsereinstellungen und deren Änderung.
- proxy
Verwenden Sie die proxy-API, um Webanfragen zu proxieren. Sie können den
proxy.onRequest
-Ereignislistener verwenden, um Webanfragen abzufangen und ein Objekt zurückzugeben, das beschreibt, ob und wie sie zu proxieren sind.- runtime
Dieses Modul stellt Informationen über Ihre Erweiterung und die Umgebung, in der sie ausgeführt wird, bereit.
- scripting
Fügt JavaScript und CSS in Websites ein. Diese API bietet zwei Ansätze zum Einfügen von Inhalten:
- search
Verwenden Sie die
search
API, um die installierten Suchmaschinen abzurufen und Suchvorgänge auszuführen.- sessions
Verwenden Sie die sessions API, um Tabs und Fenster aufzulisten und wiederherzustellen, die während der Ausführung des Browsers geschlossen wurden.
- sidebarAction
Ruft Eigenschaften der Seitenleiste einer Erweiterung ab und setzt diese.
- storage
Ermöglicht es Erweiterungen, Daten zu speichern und abzurufen sowie Änderungen an gespeicherten Elementen zu überwachen.
- tabs
Interagieren Sie mit dem Tab-System des Browsers.
- theme
Ermöglicht es Browser-Erweiterungen, Details zum Browser-Design zu erhalten und das Design zu aktualisieren.
- topSites
Verwenden Sie die
topSites
API, um ein Array mit Seiten zu erhalten, die der Benutzer häufig besucht hat.- types
Definiert den
BrowserSetting
-Typ, der verwendet wird, um eine Browsereinstellung darzustellen.- userScripts
Verwenden Sie diese API, um Benutzer-Skripte zu registrieren, Drittanbieter-Skripte, die darauf ausgelegt sind, Webseiten zu manipulieren oder neue Funktionen bereitzustellen. Die Registrierung eines Benutzer-Skripts weist den Browser an, das Skript an Seiten anzuhängen, die den während der Registrierung angegebenen URL-Mustern entsprechen.
Fügen Sie Ereignislistener für die verschiedenen Phasen einer Navigation hinzu. Eine Navigation besteht aus einem Frame im Browser, der von einer URL zu einer anderen wechselt, normalerweise (aber nicht immer) als Reaktion auf eine Benutzeraktion, wie das Klicken auf einen Link oder das Eingeben einer URL in die Adressleiste.
- webRequest
Fügen Sie Ereignislistener für die verschiedenen Phasen einer HTTP-Anfrage hinzu, die auch Websocket-Anfragen auf
ws://
undwss://
umfassen. Der Ereignislistener erhält detaillierte Informationen über die Anfrage und kann die Anfrage ändern oder abbrechen.- windows
Interagieren Sie mit Browserfenstern. Sie können diese API verwenden, um Informationen über offene Fenster zu erhalten sowie Fenster zu öffnen, zu ändern und zu schließen. Außerdem können Sie auf Ereignisse wie das Öffnen, Schließen und Aktivieren von Fenstern lauschen.