activeTab-Berechtigung

Die activeTab-Berechtigung anfordern

Ihre Erweiterung fordert activeTab über den Manifest-Schlüssel permissions an:

"permissions": ["activeTab"]

activeTab ist eine API-Berechtigung, keine Host-Berechtigung.

Sie können activeTab auch in optional_permissions aufnehmen und zur Laufzeit mit permissions.request() anfordern. Diese Berechtigung wird ohne Nachfrage beim Benutzer erteilt.

Wie activeTab erteilt wird

Der Browser erteilt activeTab, wenn der Benutzer mit der Erweiterung interagiert. Solche Interaktionen heißen Benutzeraktionen. Dazu gehört, dass der Benutzer:

• auf die Symbolleistenschaltfläche oder page action der Erweiterung klickt.
• einen Kontextmenüeintrag der Erweiterung auswählt, wodurch das Ereignis menus.onClicked ausgelöst wird.
• ein von der Erweiterung über die API commands definiertes Tastenkürzel verwendet, wodurch das Ereignis commands.onCommand ausgelöst wird.
• auf einen Vorschlag der Erweiterung in der Adressleiste (Omnibox) klickt, wodurch das Ereignis omnibox.onInputEntered ausgelöst wird (ab Firefox 142).

In der Regel wird activeTab für den aktiven Tab erteilt. Es gibt eine Ausnahme: Eine Erweiterung kann mit der API menus einen Menüeintrag erstellen, der erscheint, wenn der Benutzer das Kontextmenü eines Tabs in der Tableiste öffnet. Wählt der Benutzer diesen Eintrag aus, wird activeTab für den angeklickten Tab erteilt – auch wenn dieser nicht aktiv ist.

Welche Möglichkeiten activeTab gewährt

Solange activeTab für einen Tab erteilt ist, kann die Erweiterung:

• mit der API scripting JavaScript oder CSS in den Tab einfügen (oder in Manifest V2 mit tabs.executeScript() und tabs.insertCSS()). Siehe Content Scripts laden.
• die geschützten Eigenschaften url, title und favIconUrl des tabs.Tab-Objekts lesen. Andernfalls ist dafür die Berechtigung "tabs" oder eine passende Host-Berechtigung erforderlich.
• den Inhalt des Tabs mit tabs.captureVisibleTab() erfassen (ab Firefox 126).
• mit declarativeNetRequest.getMatchedRules() die Regeln auslesen, die auf den Tab zutreffen, ohne die Berechtigung "declarativeNetRequestFeedback" zu benötigen.

Umfang des Zugriffs

activeTab gewährt Skriptzugriff auf die oberste Seite im Tab und auf darin enthaltene Frames desselben Ursprungs. Um Skripte in ursprungsübergreifenden Frames auszuführen oder deren Formatvorlagen zu ändern, sind zusätzliche Host-Berechtigungen erforderlich.

Die Einschränkungen und Beschränkungen für bestimmte Websites und URI-Schemata gelten auch für activeTab. Auf einigen speziellen Seiten können keine Skripte eingefügt werden. Dazu gehören die Leseansicht, die Quelltextansicht, der PDF-Betrachter und andere integrierte Seiten der Browseroberfläche.

Wann der Zugriff endet

Die Erweiterung kann nur auf den Tab beziehungsweise die Daten zugreifen, die zum Zeitpunkt der Benutzeraktion vorhanden waren. Wenn im Tab zu einer anderen Seite navigiert wird, verliert die Erweiterung die Zugriffsberechtigung. Sie muss ihre Arbeit mit dem Tab daher innerhalb des gewährten Zeitraums abschließen oder die benötigten Daten in diesem Zeitraum erfassen. Benötigt sie später erneut Zugriff, muss der Benutzer die Aktion wiederholen.

Wann genau der Zugriff endet, hängt vom Browser ab. Siehe Wann der Zugriff widerrufen wird.

Beispiel

Diese Erweiterung fügt ein Skript in die aktuelle Seite ein, wenn der Benutzer auf ihre Symbolleistenschaltfläche klickt. Sie benötigt keine Host-Berechtigungen.

manifest.json:

{
  "manifest_version": 3,
  "name": "Heading highlighter",
  "version": "1.0",
  "permissions": ["activeTab", "scripting"],
  "action": {
    "default_title": "Highlight headings"
  },
  "background": {
    "scripts": ["background.js"]
  }
}

background.js:

function highlightHeadings() {
  for (const heading of document.querySelectorAll("h1, h2, h3")) {
    heading.style.backgroundColor = "yellow";
  }
}

browser.action.onClicked.addListener((tab) => {
  // activeTab is granted for `tab` because the user clicked the toolbar button.
  browser.scripting.executeScript({
    target: { tabId: tab.id },
    func: highlightHeadings,
  });
});

Durch denselben Klick werden auch die geschützten Tab-Eigenschaften lesbar. tab.url und tab.title enthalten daher tatsächliche Werte statt undefined.

Weitere Beispiele

Die folgenden Beispiele für die Verwendung der Berechtigung activeTab finden Sie im Repository mit Beispielerweiterungen unter https://github.com/mdn/webextensions-examples:

Browser-Kompatibilität

Firefox, Safari und Chromium-basierte Browser, darunter Chrome und Edge, unterstützen activeTab. Es gibt jedoch Unterschiede darin, wann die Berechtigung erteilt wird, welche Möglichkeiten sie bietet und wann sie widerrufen wird.

Aktionen, die activeTab gewähren

Gewährte Möglichkeiten

Auch der Zugriff, den Browser mit activeTab gewähren, unterscheidet sich:

• Firefox und Safari gewähren nur Zugriff auf den aktiven Tab.
• Chrome gewährt die aus der URL des Tabs abgeleiteten Host-Berechtigungen.

Dadurch kann Chrome beispielsweise mehr Zugriff gewähren als Firefox:

• In Chrome kann ein Skript in einem anderen Tab desselben Ursprungs ausgeführt werden, in Firefox nicht.
• Ein Erweiterungsskript (etwa ein Hintergrundskript oder das Skript eines Popups) kann in Chrome eine ursprungsübergreifende Anfrage an die URL des Tabs senden, in Firefox nicht.
• Die API cookies benötigt Host-Berechtigungen, um auf Cookies bestimmter Domains zuzugreifen. Chrome erlaubt dies mit activeTab, Firefox nicht.

Diese Liste ist nicht vollständig.

Wann der Zugriff widerrufen wird

In allen Browsern wird der Zugriff widerrufen, wenn der Tab geschlossen wird. Navigationen innerhalb desselben Dokuments – etwa eine Änderung des Fragments (Hashs) oder ein Aufruf von History.pushState() – widerrufen ihn dagegen nicht: Das Dokument und sein Ursprung bleiben unverändert, sodass der Zugriff erhalten bleibt.

Bei Navigationen, die ein neues Dokument laden, unterscheidet sich das Verhalten:

• Chrome: Der Zugriff bleibt bestehen, solange der Tab denselben Ursprung beibehält, auch nach einem erneuten Laden. Er wird widerrufen, wenn im Tab zu einem anderen Ursprung navigiert wird.
• Safari: Der Zugriff ist an das Dokument gebunden, das sich zum Zeitpunkt der Benutzeraktion im Tab befand. Er wird widerrufen, wenn im Tab zu einer anderen URL navigiert wird.
• Firefox: Der Zugriff ist an das Dokument gebunden, das sich zum Zeitpunkt der Benutzeraktion im Tab befand. Jede Navigation, die zu einem neuen Dokument führt, beendet den Zugriff; der Benutzer muss die Aktion wiederholen. Wird das Dokument aus dem Back/Forward-Cache wiederhergestellt, erhält es den Zugriff zurück.

Weitere Unterschiede

• Berechtigungsabfragen: Firefox und Chrome erteilen einer Erweiterung die angeforderten Host-Berechtigungen bei der Installation. Mit activeTab lässt sich daher eine Warnung bei der Installation vermeiden. Safari setzt Host-Berechtigungen dagegen standardmäßig auf „Nachfragen“ und fragt den Benutzer beim ersten Zugriffsversuch auf eine Website, ob er Für einen Tag erlauben oder Immer erlauben möchte. Mit activeTab entfällt diese Abfrage, da Safari die Interaktion des Benutzers mit der Erweiterung als Erteilung der Berechtigung wertet.
• Manifest V2 und V3: In Manifest V3 funktioniert activeTab in den Browsern auf dieselbe Weise. In Firefox gewährt activeTab unter Manifest V2 zusätzlich scripting.executeScript() Zugriff auf ein iframe mit einem anderen Ursprung (siehe Bug 1839200). Dieses Verhalten wurde in MV3 entfernt.

Siehe auch

• Manifest-Schlüssel permissions
• Manifest-Schlüssel optional_permissions
• Benutzeraktionen
• Content Scripts
• Die richtigen Berechtigungen anfordern im Extension Workshop
• Die „activeTab“-Berechtigung in der Dokumentation zu Chrome-Erweiterungen