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:

Darstellung eines Schnipsels von Web-Erweiterungscode, ausgeführt von der Konsole in der Toolbox

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() und Window.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 WebExtension clipboard 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.
menus: 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.
webNavigation: 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:// und wss:// 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.