scripting.executeScript()

Syntax

let results = await browser.scripting.executeScript(
  details             // object
)

Parameter

details

Ein Objekt, das das einzufügende Skript beschreibt. Es enthält die folgenden Eigenschaften:

args Optional

Ein Array von Argumenten, die an die Funktion übergeben werden. Dies ist nur gültig, wenn der Parameter func angegeben ist. Die Argumente müssen JSON-serialisierbar sein.

files Optional

array von string. Ein Array mit Pfaden zu den einzufügenden JS-Dateien, relativ zum Stammverzeichnis der Erweiterung. Genau eine der Eigenschaften files und func muss angegeben werden.

func Optional

function. Eine einzufügende JavaScript-Funktion. Diese Funktion wird zur Einfügung serialisiert und anschließend deserialisiert. Dabei gehen gebundene Parameter und der Ausführungskontext verloren. Genau eine der Eigenschaften files und func muss angegeben werden.

Die Funktion wird anhand ihres Quelltexts serialisiert, der ein gültiger Funktionsausdruck sein muss. Verwenden Sie eine Funktionsdeklaration, einen Funktionsausdruck oder eine Pfeilfunktion. Eine mit Methodensyntax definierte Funktion, etwa method() {} in einem Objektliteral oder einer Klasse, lässt sich nicht als gültiger Funktionsausdruck serialisieren und kann daher nicht ausgeführt werden. Firefox gibt einen SyntaxError in der Eigenschaft error des InjectionResult zurück, während Chrome den Fehler nur in der Konsole des Ziel-Tabs meldet.

injectImmediately Optional

boolean. Gibt an, ob die Einfügung in das Ziel so früh wie möglich ausgelöst wird, jedoch nicht unbedingt vor dem Laden der Seite.

target

scripting.InjectionTarget. Angaben zum Ziel, in das das Skript eingefügt werden soll.

world Optional

scripting.ExecutionWorld. Die Ausführungsumgebung des Skripts.

Rückgabewert

Ein Promise, das mit einem Array von InjectionResult-Objekten erfüllt wird. Diese enthalten das Ergebnis des eingefügten Skripts in jedem Frame, in den es eingefügt wurde.

Das Promise wird zurückgewiesen, wenn die Einfügung fehlschlägt, beispielsweise weil das Ziel ungültig ist. Sobald die Einfügung begonnen hat, wird das Promise auch dann erfüllt, wenn das Skript nicht geparst werden kann oder einen Fehler auslöst. In diesem Fall enthält das InjectionResult des betreffenden Frames den Fehler in seiner Eigenschaft error statt eines result. Um alle Fehler zu behandeln, fangen Sie das zurückgewiesene Promise ab und prüfen Sie die Eigenschaft error jedes Ergebnisses.

Jedes InjectionResult-Objekt hat die folgenden Eigenschaften:

documentId

string. Das Dokument, das der Einfügung zugeordnet ist. Weitere Informationen finden Sie im Artikel Mit documentId arbeiten.

frameId

number. Die Frame-ID, die der Einfügung zugeordnet ist.

result Optional

any. Das Ergebnis der Skriptausführung.

error Optional

any. Wenn ein Fehler auftritt, enthält diese Eigenschaft den Wert, den das Skript ausgelöst oder mit dem es das Promise zurückgewiesen hat. Üblicherweise ist dies ein Fehlerobjekt mit einer Nachrichten-Eigenschaft, es kann aber ein beliebiger Wert sein (einschließlich primitiver Werte und undefined).

Chrome unterstützt die Eigenschaft error noch nicht (siehe Issue 1271527: Fehler von scripting.executeScript an InjectionResult weitergeben). Alternativ können Laufzeitfehler abgefangen werden, indem Sie den auszuführenden Code in eine try-catch-Anweisung einschließen. Nicht abgefangene Fehler werden außerdem in der Konsole des Ziel-Tabs gemeldet.

Das Ergebnis eines Skripts ist der Wert, den die zuletzt ausgewertete Anweisung erzeugt. Wenn die letzte Anweisung ein Promise erzeugt, ist das Ergebnis der Wert, mit dem dieses Promise abgeschlossen wurde. Das ist vergleichbar mit den Ergebnissen, die Sie bei der Ausführung des Skripts in der Web-Konsole sehen (ohne Ausgaben von console.log()). Betrachten Sie beispielsweise ein Skript wie dieses:

let foo = "my result";
foo;

Hier enthält das Ergebnisarray den String "my result" als Element.

Das Skriptergebnis muss in Firefox ein Wert sein, der sich mit dem Structured-Clone-Algorithmus klonen lässt, und in Chrome ein JSON-serialisierbarer Wert. Der Artikel Chrome-Inkompatibilitäten erläutert diesen Unterschied ausführlicher im Abschnitt Algorithmus zum Klonen von Daten.

Beispiele

Dieses Beispiel führt ein einzeiliges Codefragment im aktiven Tab aus. Es fängt die Zurückweisung des Promise ab, die bei einer fehlgeschlagenen Einfügung auftritt, und prüft jedes Ergebnis auf einen Fehler bei der Skriptausführung:

browser.action.onClicked.addListener(async (tab) => {
  try {
    const results = await browser.scripting.executeScript({
      target: {
        tabId: tab.id,
      },
      func: () => {
        document.body.style.border = "5px solid green";
      },
    });
    for (const { frameId, error } of results) {
      if (error) {
        console.error(`script failed in frame ${frameId}: ${error}`);
      }
    }
  } catch (err) {
    console.error(`failed to execute script: ${err}`);
  }
});

Dieses Beispiel führt ein Skript aus einer Datei namens "content-script.js" aus, die mit der Erweiterung ausgeliefert wird. Das Skript wird im aktiven Tab sowohl in Unterframes als auch im Hauptdokument ausgeführt:

browser.action.onClicked.addListener(async (tab) => {
  try {
    await browser.scripting.executeScript({
      target: {
        tabId: tab.id,
        allFrames: true,
      },
      files: ["content-script.js"],
    });
  } catch (err) {
    console.error(`failed to execute script: ${err}`);
  }
});

Beispielerweiterungen

• menu-demo

Browser-Kompatibilität