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 Skripts auszuführen.

Sie können Code in Seiten injizieren, deren URL mit einem Match-Muster ausgedrückt werden kann. Dafür 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 Leseransicht, Quellenansicht und PDF-Viewer-Seiten.

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

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

Dafür benötigen Sie keine speziellen 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 sich öffnet, wenn Sie einen neuen leeren Tab öffnen.

Die von Ihnen injizierten Skripte werden als Content-Skripte bezeichnet.

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

Syntax

js
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 folgende Eigenschaften:

allFrames Optional

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

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

Wenn es false ist, wird der Code nur in den Hauptframe injiziert.

Standardmäßig ist es false.

code Optional

string. Der zu injizierende Code als Textstring.

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 am Erweiterungs-Root beginnen, relativ zur aktuellen Seiten-URL aufgelöst.
  • In Chrome werden diese URLs relativ zur Basis-URL der Erweiterung aufgelöst.

Um plattformübergreifend zu arbeiten, können Sie den Pfad als relative URL angeben, beginnend am Root der Erweiterung, etwa so: "/path/to/script.js".

frameId Optional

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

Standardmäßig 0 (der Hauptframe).

matchAboutBlank Optional

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

Standardmäßig ist es false.

runAt Optional

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

Standardmäßig "document_idle".

Rückgabewert

Ein Promise, das auf ein Array von Objekten auflöst. Die Werte des Arrays repräsentieren das Ergebnis des Skripts in jedem injizierten Frame.

Das Ergebnis des Skripts ist die zuletzt ausgewertete Anweisung, die ähnlich dem wäre, was als Ergebnis (nicht die console.log()-Ausgabe) ausgegeben würde, wenn Sie das Skript in der Webkonsole ausführen. Zum Beispiel, betrachten Sie ein Skript wie dieses:

js
let foo = "my result";
foo;

Hier wird das Ergebnis-Array den String "my result" als Element enthalten.

Die Ergebniswerte müssen strukturierter clonbar 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.

Wenn ein Fehler auftritt, wird das Promise mit einer Fehlermeldung abgelehnt.

Beispiele

Dieses Beispiel führt ein einzeiliges Codeschnipsel im derzeit aktiven Tab aus:

js
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 (die mit der Erweiterung gebündelt ist) namens "content-script.js" aus. Das Skript wird im derzeit aktiven Tab ausgeführt. Das Skript wird sowohl in Subframes als auch im Hauptdokument ausgeführt:

js
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 (die mit der Erweiterung gebündelt ist) namens "content-script.js" aus. Das Skript wird im Tab mit einer ID von 2 ausgeführt:

js
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 dem chrome.tabs API von Chromium. Diese Dokumentation ist abgeleitet von tabs.json im Chromium-Code.