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. Diese Interaktionen werden als Benutzeraktionen bezeichnet. Dazu gehört, dass der Benutzer:

• auf die Symbolleistenschaltfläche oder Page Action der Erweiterung klickt.
• einen Kontextmenüeintrag der Erweiterung auswählt und dadurch das Ereignis menus.onClicked auslöst.
• eine von der Erweiterung mit der commands-API definierte Tastenkombination verwendet und dadurch das Ereignis commands.onCommand auslöst.
• auf einen Vorschlag der Erweiterung in der Adressleiste (Omnibox) klickt und dadurch das Ereignis omnibox.onInputEntered auslöst (ab Firefox 142).

Normalerweise wird activeTab für den aktiven Tab erteilt. Es gibt eine Ausnahme: Eine Erweiterung kann mit der menus-API 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 der aktive Tab ist.

Was activeTab ermöglicht

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

• Mit der scripting-API JavaScript oder CSS in den Tab einfügen (oder mit tabs.executeScript() und tabs.insertCSS() in Manifest V2). Siehe Content Scripts laden.
• Die geschützten Eigenschaften url, title und favIconUrl des tabs.Tab-Objekts des Tabs lesen. Andernfalls sind 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 lesen, die auf den Tab zutreffen, ohne die Berechtigung "declarativeNetRequestFeedback" zu benötigen.

Umfang des Zugriffs

activeTab gewährt Skriptzugriff auf die Seite auf oberster Ebene im Tab und auf Frames innerhalb dieser Seite, die denselben Ursprung haben. Um Skripte in Frames mit anderem Ursprung auszuführen oder deren Stile zu ändern, sind zusätzliche Host-Berechtigungen erforderlich.

Die Einschränkungen und Begrenzungen für bestimmte Websites und URI-Schemata gelten auch für activeTab. Einige spezielle Seiten erlauben das Einfügen von Skripten nicht, darunter 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 Benutzerinteraktion vorhanden waren. Navigiert der Tab zu einer anderen Seite, 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 dieser Zeit erfassen. Benötigt sie 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 aus dem Repository für Beispielerweiterungen unter https://github.com/mdn/webextensions-examples verwenden die Berechtigung activeTab:

Browser-Kompatibilität

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

Aktionen, durch die activeTab erteilt wird

Gewährte Möglichkeiten

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

• Firefox und Safari gewähren ausschließlich Zugriff auf den aktiven Tab.
• Chrome gewährt die Host-Berechtigungen, die sich aus der URL des Tabs ableiten.

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

• In Chrome kann ein Skript in einem anderen Tab mit demselben Ursprung ausgeführt werden, in Firefox nicht.
• Ein Erweiterungsskript (beispielsweise ein Hintergrundskript oder das Skript eines Popups) kann in Chrome eine Cross-Origin-Anfrage an die URL des Tabs senden, in Firefox nicht.
• Die cookies-API 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 die Änderung eines Fragments (Hash) 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 beim selben Ursprung bleibt, auch beim erneuten Laden. Er wird widerrufen, wenn der Tab zu einem anderen Ursprung navigiert.
• Safari: Der Zugriff ist an das Dokument gebunden, das sich zum Zeitpunkt der Benutzeraktion im Tab befand. Er wird widerrufen, wenn der Tab zu einer anderen URL navigiert.
• 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 ursprüngliche Dokument aus dem Back/Forward-Cache wiederhergestellt, wird auch sein Zugriff wiederhergestellt.

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 der Erweiterung auf eine Website. Dabei stehen Für einen Tag erlauben und Immer erlauben zur Auswahl. Mit activeTab entfällt diese Nachfrage, da Safari die Interaktion des Benutzers mit der Erweiterung als Berechtigungserteilung wertet.
• Manifest V2 und V3: In Browsern funktioniert activeTab unter Manifest V3 auf dieselbe Weise. In Firefox ermöglicht activeTab unter Manifest V2 mit scripting.executeScript() zusätzlich den Zugriff auf einen iframe mit anderem 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 für Chrome-Erweiterungen