tabs.executeScript()

Fügt JavaScript-Code in eine Seite ein.

Hinweis: Bei der Verwendung von Manifest V3 oder höher verwenden Sie scripting.executeScript(), um Skripte auszuführen.

Sie können Code in Seiten injizieren, deren URL sich durch ein Muster zum Abgleich ausdrücken lässt. Zu diesem Zweck muss das Schema eines der folgenden sein: http, https oder file.

Sie müssen die Berechtigung für die URL der Seite haben - entweder explizit als Host-Berechtigung - oder über die activeTab-Berechtigung. Beachten Sie, dass einige spezielle Seiten diese Berechtigung nicht zulassen, einschließlich der Leseansicht, view-source und PDF-Viewer-Seiten.

Sie können auch Code in Seiten injizieren, die mit Ihrer eigenen Erweiterung gepackt sind:

browser.tabs.create({ url: "/my-page.html" }).then(() => {
  browser.tabs.executeScript({
    code: `console.log('location:', window.location.href);`,
  });
});

Dazu benötigen Sie keine besonderen Berechtigungen.

Sie können keinen Code in eine der eingebauten Seiten des Browsers injizieren, wie z.B.: about:debugging, about:addons oder die Seite, die beim Öffnen eines neuen leeren Tabs geöffnet wird.

Die von Ihnen injizierten Skripte werden Content-Skripte genannt.

Dies ist eine asynchrone Funktion, die ein Promise zurückgibt.

Syntax

let executing = browser.tabs.executeScript(
  tabId,                 // optional integer
  details                // object
)

Parameter

tabId Optional

integer. Die ID des Tabs, in dem das Skript ausgeführt werden soll.

Standardmäßig wird der aktive Tab des aktuellen Fensters verwendet.

details

Ein Objekt, das das auszuführende Skript beschreibt.

Es enthält die folgenden Eigenschaften:

allFrames Optional

boolean. Wenn true, wird der Code in alle Frames der aktuellen Seite injiziert.

Ist true und frameId gesetzt, wird ein Fehler ausgelöst. (frameId und allFrames schließen sich gegenseitig aus.)

Ist es false, wird der Code nur in den obersten Frame injiziert.

Der Standardwert ist false.

code Optional

string. Der zu injizierende Code als Textzeichenfolge.

Warnung: Verwenden Sie diese Eigenschaft nicht, um nicht vertrauenswürdige Daten in JavaScript zu interpolieren, da dies zu einem Sicherheitsproblem führen könnte.

file Optional

string. Pfad zu einer Datei, die den zu injizierenden Code enthält.

In Firefox werden relative URLs, die nicht im Wurzelverzeichnis der Erweiterung beginnen, relativ zur aktuellen Seiten-URL aufgelöst.
In Chrome werden diese URLs relativ zur Basis-URL der Erweiterung aufgelöst.

Um in mehreren Browsern zu funktionieren, können Sie den Pfad als relative URL angeben, beginnend am Wurzelverzeichnis der Erweiterung, wie folgt: "/path/to/script.js".

frameId Optional

integer. Der Frame, in den der Code injiziert werden soll.

Der Standardwert ist 0 (der oberste Frame).

matchAboutBlank Optional

boolean. Wenn true, wird der Code in eingebettete about:blank und about:srcdoc Frames injiziert, wenn Ihre Erweiterung Zugriff auf deren Elterndokument hat. Der Code kann nicht in oberste about: Frames eingefügt werden.

Der Standardwert ist false.

runAt Optional

extensionTypes.RunAt. Der früheste Zeitpunkt, zu dem der Code in den Tab injiziert wird.

Der Standardwert ist "document_idle".

Rückgabewert

Ein Promise, das in ein Array von Objekten aufgelöst wird. Die Werte des Arrays stellen das Ergebnis des Skripts in jedem injizierten Frame dar.

Das Ergebnis des Skripts ist die letzte ausgewertete Anweisung, ähnlich wie das, was (die Ergebnisse, nicht der console.log()-Output) ausgegeben würde, wenn Sie das Skript in der Web-Konsole ausführen. Betrachten Sie zum Beispiel ein Skript wie dieses:

let foo = "my result";
foo;

Hier wird das Ergebnis-Array die Zeichenfolge "my result" als Element enthalten.

Die Ergebniswerte müssen structured cloneable sein (siehe Datenklon-Algorithmus).

Hinweis: Die letzte Anweisung kann auch ein Promise sein, aber diese Funktion wird von der webextension-polyfill-Bibliothek nicht unterstützt.

Tritt ein Fehler auf, wird das Promise mit einer Fehlermeldung abgelehnt.

Beispiele

Dieses Beispiel führt ein einzeiliges Code-Snippet im aktuell aktiven Tab aus:

function onExecuted(result) {
  console.log(`We made it green`);
}

function onError(error) {
  console.log(`Error: ${error}`);
}

const makeItGreen = 'document.body.style.border = "5px solid green"';

const executing = browser.tabs.executeScript({
  code: makeItGreen,
});
executing.then(onExecuted, onError);

Dieses Beispiel führt ein Skript aus einer Datei aus (die mit der Erweiterung gepackt ist) namens "content-script.js". Das Skript wird im aktuell aktiven Tab ausgeführt. Das Skript wird sowohl in Subframes als auch im Hauptdokument ausgeführt:

function onExecuted(result) {
  console.log(`We executed in all subframes`);
}

function onError(error) {
  console.log(`Error: ${error}`);
}

const executing = browser.tabs.executeScript({
  file: "/content-script.js",
  allFrames: true,
});
executing.then(onExecuted, onError);

Dieses Beispiel führt ein Skript aus einer Datei aus (die mit der Erweiterung gepackt ist) namens "content-script.js". Das Skript wird im Tab mit der ID 2 ausgeführt:

function onExecuted(result) {
  console.log(`We executed in tab 2`);
}

function onError(error) {
  console.log(`Error: ${error}`);
}

const executing = browser.tabs.executeScript(2, {
  file: "/content-script.js",
});
executing.then(onExecuted, onError);

Beispielerweiterungen

Browser-Kompatibilität

Hinweis: Diese API basiert auf Chromiums chrome.tabs API. Diese Dokumentation ist abgeleitet von tabs.json im Chromium-Code.