Mit der Tabs API arbeiten

Berechtigungen und die Tabs API

Für die meisten Funktionen der Tabs API benötigen Sie keine Berechtigungen. Es gibt jedoch einige Ausnahmen:

• Die Berechtigung "tabs" ist erforderlich, um auf die Eigenschaften Tab.url, Tab.title und Tab.favIconUrl des Tab-Objekts zuzugreifen. In Firefox benötigen Sie "tabs" auch, um eine Abfrage anhand der URL durchzuführen.
• Eine Host-Berechtigung ist für tabs.executeScript() oder tabs.insertCSS() erforderlich.

So können Sie die Berechtigung "tabs" in der manifest.json-Datei Ihrer Erweiterung anfordern:

"permissions": [
  "<all_urls>",
  "tabs"
],

Damit können Sie alle Funktionen der Tabs API auf allen Websites verwenden, die der Benutzer besucht. Für tabs.executeScript() und tabs.insertCSS() gibt es mit der Berechtigung activeTab auch eine Möglichkeit, ohne Host-Berechtigung auszukommen. Sie gewährt dieselben Rechte wie "tabs" mit <all_urls>, allerdings mit zwei Einschränkungen:

• Der Benutzer muss über eine Browser- oder Seitenaktion, ein Kontextmenü oder eine Tastenkombination mit der Erweiterung interagieren.
• Die Berechtigung gilt nur für den aktiven Tab.

Der Vorteil dieses Ansatzes ist, dass Benutzer keinen Berechtigungshinweis erhalten, der besagt, dass Ihre Erweiterung „auf Ihre Daten für alle Websites zugreifen“ kann. Die Berechtigung <all_urls> erlaubt einer Erweiterung nämlich, jederzeit Skripte in beliebigen Tabs auszuführen. Die Berechtigung activeTab erlaubt dies dagegen nur für eine vom Benutzer angeforderte Aktion im aktuellen Tab.

Tabs und ihre Eigenschaften ermitteln

Manchmal benötigen Sie eine Liste aller Tabs in allen Browserfenstern. In anderen Fällen möchten Sie nur Tabs finden, die bestimmte Kriterien erfüllen, etwa Tabs, die von einem bestimmten Tab aus geöffnet wurden oder Seiten einer bestimmten Domain anzeigen. Sobald Sie eine Liste der Tabs haben, möchten Sie wahrscheinlich mehr über deren Eigenschaften erfahren.

Hierfür gibt es tabs.query(). Ohne Abfragekriterien liefert die Methode alle Tabs. Über das Objekt queryInfo können Sie Kriterien festlegen, etwa ob ein Tab aktiv ist oder sich im aktuellen Fenster befindet. Insgesamt stehen 17 Kriterien zur Verfügung. tabs.query() gibt ein Array von tabs.Tab-Objekten mit Informationen über die Tabs zurück.

Wenn Sie nur Informationen zum aktuellen Tab benötigen, erhalten Sie dessen tabs.Tab-Objekt mit tabs.getCurrent(). Wenn Sie die ID eines Tabs kennen, können Sie sein tabs.Tab-Objekt mit tabs.get() abrufen.

Praxisbeispiel

Sehen wir uns anhand des Beispiels tabs-tabs-tabs an, wie tabs.query() und tabs.Tab verwendet werden. Das Beispiel fügt dem Popup einer Symbolleistenschaltfläche eine Liste zum Wechseln zwischen Tabs hinzu.

manifest.json

Hier ist die Datei manifest.json:

json

{
  "browser_action": {
    "default_title": "Tabs, tabs, tabs",
    "default_popup": "tabs.html"
  },
  "description": "A list of methods you can perform on a tab.",
  "homepage_url": "https://github.com/mdn/webextensions-examples/tree/main/tabs-tabs-tabs",
  "manifest_version": 2,
  "name": "Tabs, tabs, tabs",
  "permissions": ["tabs"],
  "version": "1.0"
}

Hinweis:

• tabs.html ist in browser_action als default_popup festgelegt. Es wird angezeigt, wenn der Benutzer auf das Symbol der Erweiterung in der Symbolleiste klickt.
• Die Berechtigungen enthalten "tabs". Das ist für die Tab-Liste erforderlich, da die Erweiterung die Titel der Tabs liest, um sie im Popup anzuzeigen.

tabs.html

tabs.html definiert den Inhalt des Erweiterungs-Popups:

html

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <link rel="stylesheet" href="tabs.css" />
  </head>

  <body>
    <div class="panel">
      <div class="panel-section panel-section-header">
        <div class="text-section-header">Tabs-tabs-tabs</div>
      </div>

      <a href="#" id="tabs-move-beginning">
        Move active tab to the beginning of the window
      </a>
      <br />

      <!-- Define the other menu items -->

      <div class="switch-tabs">
        <p>Switch to tab</p>
        <div id="tabs-list"></div>
      </div>
    </div>

    <script src="tabs.js"></script>
  </body>
</html>

Die Datei führt Folgendes aus:

1. Sie definiert die Menüpunkte.
2. Sie definiert ein leeres div mit der ID tabs-list, das die Tab-Liste aufnehmen soll.
3. Sie bindet tabs.js ein.

tabs.js

In tabs.js sehen wir, wie die Tab-Liste erstellt und dem Popup hinzugefügt wird.

Das Popup erstellen

Zunächst wird ein Event-Handler hinzugefügt, der listTabs() ausführt, sobald tabs.html geladen ist:

document.addEventListener("DOMContentLoaded", listTabs);

Als Erstes ruft listTabs() die Funktion getCurrentWindowTabs() auf. Dort wird tabs.query() verwendet, um tabs.Tab-Objekte für die Tabs im aktuellen Fenster abzurufen:

function getCurrentWindowTabs() {
  return browser.tabs.query({ currentWindow: true });
}

Nun kann listTabs() den Inhalt des Popups erstellen.

Zunächst werden folgende Schritte ausgeführt:

1. Das Element <div id="tabs-list"> abrufen.
2. Ein Dokumentfragment erstellen, in dem die Liste aufgebaut wird.
3. Zähler initialisieren.
4. Den Inhalt des Elements <div id="tabs-list"> löschen.

function listTabs() {
  getCurrentWindowTabs().then((tabs) => {
    const tabsList = document.getElementById("tabs-list");
    const currentTabs = document.createDocumentFragment();
    const limit = 5;
    let counter = 0;

    tabsList.textContent = "";
    // ...
  });
}

Anschließend werden die Links für die einzelnen Tabs erstellt:

1. Die ersten fünf Einträge aus dem Array von tabs.Tab-Objekten durchlaufen.
2. Für jeden Eintrag einen Hyperlink zum Dokumentfragment hinzufügen.
   • Als Beschriftung des Links, also als sein Text, dient der title des Tabs (oder seine id, falls er keinen title hat).
   • Als Linkadresse wird die id des Tabs verwendet.

function listTabs() {
  getCurrentWindowTabs().then((tabs) => {
    // ...
    for (const tab of tabs) {
      if (!tab.active && counter <= limit) {
        const tabLink = document.createElement("a");

        tabLink.textContent = tab.title || tab.id;

        tabLink.setAttribute("href", tab.id);
        tabLink.classList.add("switch-tabs");
        currentTabs.appendChild(tabLink);
      }

      counter += 1;
    }
    // ...
  });
}

Abschließend wird das Dokumentfragment in das Element <div id="tabs-list"> eingefügt:

function listTabs() {
  getCurrentWindowTabs().then((tabs) => {
    // ...
    tabsList.appendChild(currentTabs);
  });
}

Mit dem aktiven Tab arbeiten

Ein weiteres Beispiel ist die Info-Option „Alert active tab“. Sie zeigt alle Eigenschaften des tabs.Tab-Objekts für den aktiven Tab in einem Hinweisdialog an:

// Other if conditions...
if (e.target.id === "tabs-alert-info") {
  callOnActiveTab((tab) => {
    let props = "";
    for (const item in tab) {
      props += `${item} = ${tab[item]} \n`;
    }
    alert(props);
  });
}

Dabei findet callOnActiveTab() das Objekt des aktiven Tabs, indem es die tabs.Tab-Objekte durchläuft und nach dem Eintrag sucht, bei dem active gesetzt ist:

document.addEventListener("click", (e) => {
  function callOnActiveTab(callback) {
    getCurrentWindowTabs().then((tabs) => {
      for (const tab of tabs) {
        if (tab.active) {
          callback(tab, tabs);
        }
      }
    });
  }
});

Tabs erstellen, duplizieren, verschieben, aktualisieren, neu laden und entfernen

Nachdem Sie Informationen über die Tabs gesammelt haben, möchten Sie wahrscheinlich etwas mit ihnen tun – etwa Benutzern Funktionen zur Verwaltung von Tabs anbieten oder Funktionen Ihrer Erweiterung umsetzen.

Dafür stehen folgende Methoden zur Verfügung:

• Einen neuen Tab erstellen (tabs.create()).
• Einen Tab duplizieren (tabs.duplicate()).
• Einen Tab entfernen (tabs.remove()).
• Einen Tab verschieben (tabs.move()).
• Die URL eines Tabs aktualisieren und damit zu einer neuen Seite navigieren (tabs.update()).
• Die Seite eines Tabs neu laden (tabs.reload()).

Praxisbeispiel

Das Beispiel tabs-tabs-tabs demonstriert alle diese Funktionen außer dem Aktualisieren der URL eines Tabs. Die APIs werden auf ähnliche Weise verwendet. Deshalb betrachten wir eine der aufwendigeren Implementierungen: die Option „Move active tab to the beginning of the window list“.

Zunächst sehen Sie hier die Funktion in Aktion:

manifest.json

Für keine dieser Funktionen ist eine Berechtigung erforderlich. In der Datei manifest.json gibt es daher nichts hervorzuheben.

tabs.html

tabs.html definiert das im Popup angezeigte „Menü“. Es enthält die Option „Move active tab to the beginning of the window list“ und besteht aus einer Reihe von <a>-Tags, die durch sichtbare Trennlinien gruppiert sind. Jeder Menüpunkt erhält eine id. Anhand dieser ID ermittelt tabs.js, welcher Menüpunkt angeklickt wurde.

html

<a href="#" id="tabs-move-beginning">
  Move active tab to the beginning of the window
</a>
<br />
<a href="#" id="tabs-move-end">Move active tab to the end of the window</a>
<br />

<div class="panel-section-separator"></div>

<a href="#" id="tabs-duplicate">Duplicate active tab</a><br />
<a href="#" id="tabs-reload">Reload active tab</a><br />
<a href="#" id="tabs-alert-info">Alert active tab info</a><br />

tabs.js

Um das in tabs.html definierte „Menü“ umzusetzen, enthält tabs.js einen Listener für Klicks in tabs.html:

js

document.addEventListener("click", (e) => {
  function callOnActiveTab(callback) {
    getCurrentWindowTabs().then((tabs) => {
      for (const tab of tabs) {
        if (tab.active) {
          callback(tab, tabs);
        }
      }
    });
  }
});

Anschließend prüfen mehrere if-Anweisungen die id des angeklickten Elements.

Dieser Codeausschnitt gehört zur Option „Move active tab to the beginning of the window list“:

js

if (e.target.id === "tabs-move-beginning") {
  callOnActiveTab((tab, tabs) => {
    let index = 0;
    if (!tab.pinned) {
      index = firstUnpinnedTab(tabs);
    }
    console.log(`moving ${tab.id} to ${index}`);
    browser.tabs.move([tab.id], { index });
  });
}

Beachten Sie die Verwendung von console.log(). Damit können Sie Informationen in der Konsole des Debuggers ausgeben. Das kann bei der Behebung von Problemen während der Entwicklung hilfreich sein.

Der Code zum Verschieben ruft zuerst callOnActiveTab() auf. Diese Funktion ruft wiederum getCurrentWindowTabs() auf, um tabs.Tab-Objekte für die Tabs des aktiven Fensters zu erhalten. Anschließend durchläuft sie die Objekte, um das Objekt des aktiven Tabs zu finden und zurückzugeben:

js

function callOnActiveTab(callback) {
  getCurrentWindowTabs().then((tabs) => {
    for (const tab of tabs) {
      if (tab.active) {
        callback(tab, tabs);
      }
    }
  });
}

Angeheftete Tabs

Benutzer können Tabs in einem Fenster anheften. Angeheftete Tabs stehen am Anfang der Tab-Liste und können nicht verschoben werden. Die früheste Position, an die ein anderer Tab verschoben werden kann, ist daher direkt hinter den angehefteten Tabs. firstUnpinnedTab() durchläuft das tabs-Objekt, um die Position des ersten nicht angehefteten Tabs zu finden:

function firstUnpinnedTab(tabs) {
  for (const tab of tabs) {
    if (!tab.pinned) {
      return tab.index;
    }
  }
}

Nun haben wir alles, was zum Verschieben des Tabs benötigt wird: das Objekt des aktiven Tabs, aus dem wir seine id entnehmen können, und die Zielposition. Damit können wir den Tab verschieben:

browser.tabs.move([tab.id], { index });

Die übrigen Funktionen zum Duplizieren, Neuladen, Erstellen und Entfernen von Tabs sind ähnlich implementiert.

Die Zoomstufe eines Tabs ändern

Mit den nächsten Methoden können Sie die Zoomstufe eines Tabs abrufen (tabs.getZoom) und festlegen (tabs.setZoom). Sie können auch die Zoomeinstellungen abrufen (tabs.getZoomSettings). Zum Zeitpunkt der Erstellung dieses Artikels konnten die Einstellungen in Firefox jedoch nicht mit tabs.setZoomSettings festgelegt werden.

Die Zoomstufe kann zwischen 30 % und 500 % liegen (dargestellt durch die Dezimalwerte 0.3 bis 5).

In Firefox gelten standardmäßig folgende Zoomeinstellungen:

• Standard-Zoomstufe: 100 %.
• Zoommodus: automatisch (der Browser verwaltet, wie Zoomstufen festgelegt werden).
• Geltungsbereich von Zoomänderungen: "per-origin". Wenn Sie eine Website erneut besuchen, wird also die bei Ihrem letzten Besuch festgelegte Zoomstufe verwendet.

Praxisbeispiel

Das Beispiel tabs-tabs-tabs demonstriert drei Zoomfunktionen: Vergrößern, Verkleinern und Zurücksetzen. Hier sehen Sie die Funktionen in Aktion:

Sehen wir uns an, wie das Vergrößern implementiert ist.

manifest.json

Für keine der Zoomfunktionen sind Berechtigungen erforderlich. In der Datei manifest.json gibt es daher nichts hervorzuheben.

tabs.html

Wie tabs.html die Optionen dieser Erweiterung definiert, haben wir bereits besprochen. Für die Zoomoptionen wird nichts Neues oder Besonderes benötigt.

tabs.js

tabs.js definiert zunächst mehrere Konstanten, die im Zoomcode verwendet werden:

js

const ZOOM_INCREMENT = 0.2;
const MAX_ZOOM = 5;
const MIN_ZOOM = 0.3;
const DEFAULT_ZOOM = 1;

Anschließend wird derselbe Listener verwendet, den wir bereits besprochen haben, um auf Klicks in tabs.html zu reagieren.

Für die Vergrößerungsfunktion wird Folgendes ausgeführt:

js

// Other if conditions...
if (e.target.id === "tabs-add-zoom") {
  callOnActiveTab((tab) => {
    browser.tabs.getZoom(tab.id).then((zoomFactor) => {
      // The maximum zoomFactor is 5, it can't go higher
      if (zoomFactor >= MAX_ZOOM) {
        alert("Tab zoom factor is already at max!");
      } else {
        let newZoomFactor = zoomFactor + ZOOM_INCREMENT;
        // If the newZoomFactor is set to higher than the max accepted
        // it won't change, and does not alert that it's at maximum
        newZoomFactor = newZoomFactor > MAX_ZOOM ? MAX_ZOOM : newZoomFactor;
        browser.tabs.setZoom(tab.id, newZoomFactor);
      }
    });
  });
}

Dieser Code ruft mit callOnActiveTab() die Informationen zum aktiven Tab ab. Danach ermittelt tabs.getZoom den aktuellen Zoomfaktor des Tabs. Der aktuelle Wert wird mit dem festgelegten Höchstwert (MAX_ZOOM) verglichen. Wenn der Tab bereits maximal vergrößert ist, wird ein Hinweis angezeigt. Andernfalls wird die Zoomstufe erhöht, ohne den Höchstwert zu überschreiten, und anschließend festgelegt.

Das CSS eines Tabs bearbeiten

Eine weitere wichtige Funktion der Tabs API ist das Bearbeiten des CSS innerhalb eines Tabs: Sie können einem Tab neues CSS hinzufügen (tabs.insertCSS()) oder CSS aus einem Tab entfernen (tabs.removeCSS()).

Das ist beispielsweise nützlich, wenn Sie bestimmte Seitenelemente hervorheben oder das Standardlayout einer Seite ändern möchten.

Praxisbeispiel

Das Beispiel apply-css verwendet diese Funktionen, um der Webseite im aktiven Tab einen roten Rahmen hinzuzufügen. Hier sehen Sie die Funktion in Aktion:

Sehen wir uns an, wie das Beispiel eingerichtet ist.

manifest.json

Die Datei manifest.json fordert die Berechtigungen an, die für die CSS-Funktionen erforderlich sind. Sie benötigen entweder:

• die Berechtigung "tabs" und eine Host-Berechtigung oder
• die Berechtigung "activeTab".

Letztere ist meist hilfreicher: Sie erlaubt einer Erweiterung, tabs.insertCSS() und tabs.removeCSS() im aktiven Tab zu verwenden, wenn der Aufruf über eine Browser- oder Seitenaktion der Erweiterung, ein Kontextmenü oder eine Tastenkombination erfolgt.

json

{
  "description": "Adds a page action to toggle applying CSS to pages.",

  "manifest_version": 2,
  "name": "apply-css",
  "version": "1.0",
  "homepage_url": "https://github.com/mdn/webextensions-examples/tree/main/apply-css",

  "background": {
    "scripts": ["background.js"]
  },

  "page_action": {
    "default_icon": "icons/off.svg"
  },

  "permissions": ["activeTab", "tabs"]
}

Beachten Sie, dass zusätzlich zu "activeTab" auch die Berechtigung "tabs" angefordert wird. Diese zusätzliche Berechtigung ist erforderlich, damit das Skript der Erweiterung auf die URL des Tabs zugreifen kann. Warum das wichtig ist, sehen wir gleich.

Die weiteren wichtigen Bestandteile der manifest.json-Datei sind die Definitionen von:

• einem Hintergrundskript, das ausgeführt wird, sobald die Erweiterung geladen ist.
• einer „page action“, die ein Symbol definiert, das der Adressleiste des Browsers hinzugefügt wird.

background.js

Beim Start legt background.js einige Konstanten fest: das anzuwendende CSS, Titel für die „page action“ und eine Liste der Protokolle, mit denen die Erweiterung funktioniert.

js

const CSS = "body { border: 20px solid red; }";
const TITLE_APPLY = "Apply CSS";
const TITLE_REMOVE = "Remove CSS";
const APPLICABLE_PROTOCOLS = ["http:", "https:"];

Beim ersten Laden verwendet die Erweiterung tabs.query(), um alle Tabs im aktuellen Browserfenster abzurufen. Anschließend durchläuft sie die Tabs und ruft für jeden initializePageAction() auf.

js

browser.tabs.query({}).then((tabs) => {
  for (const tab of tabs) {
    initializePageAction(tab);
  }
});

initializePageAction verwendet protocolIsApplicable(), um festzustellen, ob die URL des aktiven Tabs die Anwendung des CSS erlaubt:

js

function protocolIsApplicable(url) {
  const anchor = document.createElement("a");
  anchor.href = url;
  return APPLICABLE_PROTOCOLS.includes(anchor.protocol);
}

Wenn das Beispiel auf den Tab angewendet werden kann, setzt initializePageAction() das Symbol und den Titel der pageAction des Tabs (in der Navigationsleiste) auf die Varianten für den deaktivierten Zustand. Anschließend wird die pageAction sichtbar gemacht:

js

function initializePageAction(tab) {
  if (protocolIsApplicable(tab.url)) {
    browser.pageAction.setIcon({ tabId: tab.id, path: "icons/off.svg" });
    browser.pageAction.setTitle({ tabId: tab.id, title: TITLE_APPLY });
    browser.pageAction.show(tab.id);
  }
}

Danach wartet ein Listener für pageAction.onClicked darauf, dass auf das Symbol der pageAction geklickt wird, und ruft dann toggleCSS auf.

js

browser.pageAction.onClicked.addListener(toggleCSS);

toggleCSS() liest den Titel der pageAction und führt die entsprechende Aktion aus:

• Bei „Apply CSS“:

  • Symbol und Titel der pageAction werden auf die Varianten für „Remove CSS“ umgestellt.
  • Das CSS wird mit tabs.insertCSS() angewendet.

• Bei „Remove CSS“:

  • Symbol und Titel der pageAction werden auf die Varianten für „Apply CSS“ umgestellt.
  • Das CSS wird mit tabs.removeCSS() entfernt.

js

function toggleCSS(tab) {
  function gotTitle(title) {
    if (title === TITLE_APPLY) {
      browser.pageAction.setIcon({ tabId: tab.id, path: "icons/on.svg" });
      browser.pageAction.setTitle({ tabId: tab.id, title: TITLE_REMOVE });
      browser.tabs.insertCSS({ code: CSS });
    } else {
      browser.pageAction.setIcon({ tabId: tab.id, path: "icons/off.svg" });
      browser.pageAction.setTitle({ tabId: tab.id, title: TITLE_APPLY });
      browser.tabs.removeCSS({ code: CSS });
    }
  }

  browser.pageAction.getTitle({ tabId: tab.id }).then(gotTitle);
}

Damit die pageAction nach jeder Aktualisierung des Tabs gültig bleibt, ruft ein Listener für tabs.onUpdated bei jeder Aktualisierung initializePageAction() auf. So wird geprüft, ob der Tab weiterhin ein Protokoll verwendet, auf das das CSS angewendet werden kann.

js

browser.tabs.onUpdated.addListener((id, changeInfo, tab) => {
  initializePageAction(tab);
});

Mit geteilten Tab-Ansichten arbeiten

Mit der Tab-Funktion für geteilte Ansichten können Benutzer zwei Tabs nebeneinander anzeigen.

In der Benutzeroberfläche wird eine geteilte Ansicht als Einheit behandelt: Verschiebt jemand einen Tab der Ansicht, wird der andere mitverschoben und die Ansicht bleibt erhalten. Ihre Erweiterung kann den verschobenen Tab mit tabs.onMoved beobachten. Dasselbe Verhalten gilt, wenn ein Tab der geteilten Ansicht mit tabs.move verschoben wird. Wenn jedoch beide Tabs beim Verschieben angegeben werden und ein Tab zwischen ihnen platziert wird, wird die geteilte Ansicht geschlossen.

Wenn jemand einen der Tabs einer geteilten Ansicht schließt, wird die geteilte Ansicht geschlossen und der andere Tab bleibt erhalten. Ihre Erweiterung kann einen Tab der geteilten Ansicht mit tabs.remove entfernen.

Ob sich ein Tab in einer geteilten Ansicht befindet, kann Ihre Erweiterung anhand seiner Eigenschaft splitViewId feststellen. Änderungen an der Zugehörigkeit zu einer geteilten Ansicht lassen sich mit tabs.onUpdated beobachten.

Weitere interessante Funktionen

Einige weitere Funktionen der Tabs API passen nicht in die vorherigen Abschnitte:

• Den sichtbaren Inhalt eines Tabs mit tabs.captureVisibleTab erfassen.
• Die vorherrschende Sprache des Inhalts eines Tabs mit tabs.detectLanguage erkennen. Damit könnten Sie beispielsweise die Sprache der Benutzeroberfläche Ihrer Erweiterung an die Sprache der angezeigten Seite anpassen.

Weitere Informationen

Weitere Informationen zur Tabs API finden Sie unter:

• Referenz zur Tabs API
• Beispielerweiterungen (viele davon verwenden die Tabs API)