scripting.executeScript()

Syntax

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

Parameter

details

Ein Objekt, das das zu injizierende Script beschreibt. Es enthält folgende Eigenschaften:

args Optional

Ein Array von Argumenten, das in die Funktion eingebracht wird. 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 von Pfaden der zu injizierenden JS-Dateien, relativ zum Stammverzeichnis der Erweiterung. Genau eine der Eigenschaften files und func muss angegeben sein.

func Optional

function. Eine JavaScript-Funktion, die injiziert wird. Diese Funktion wird serialisiert und dann zur Injektion deserialisiert. Das bedeutet, dass alle gebundenen Parameter und der Ausführungskontext verloren gehen. Genau eine der Eigenschaften files und func muss angegeben sein.

injectImmediately Optional

boolean. Ob die Injektion in das Ziel so schnell wie möglich ausgelöst wird, aber nicht unbedingt vor dem Laden der Seite.

target

scripting.InjectionTarget. Details, die das Ziel angeben, in das das Script injiziert werden soll.

world Optional

scripting.ExecutionWorld. Die Ausführungsumgebung, in der ein Script ausgeführt wird.

Rückgabewert

Ein Promise, das mit einem Array von InjectionResult-Objekten erfüllt wird, die das Ergebnis des injizierten Scripts in jedem injizierten Frame darstellen.

Das Promise wird abgelehnt, wenn die Injektion fehlschlägt, zum Beispiel wenn das Injektionsziel ungültig ist. Sobald die Skriptausführung begonnen hat, wird das Ergebnis in das Resultat aufgenommen, unabhängig davon, ob erfolgreich (als result) oder erfolglos (als error).

Jedes InjectionResult-Objekt hat folgende Eigenschaften:

documentId

string. Das mit der Injektion verbundene Dokument.

frameId

number. Die mit der Injektion verbundene Frame-ID.

result Optional

any. Das Ergebnis der Skriptausführung.

error Optional

any. Wenn ein Fehler auftritt, enthält es den Wert, den das Script geworfen oder abgelehnt hat. Typischerweise ist dies ein Fehlerobjekt mit einer Nachrichteneigenschaft, aber es könnte jeder Wert sein (einschließlich primitiver Typen und undefined).

Chrome unterstützt die Eigenschaft error noch nicht (siehe Issue 1271527: Propagate errors from scripting.executeScript to InjectionResult). Alternativ können Laufzeitfehler abgefangen werden, indem der auszuführende Code in eine try-catch-Anweisung eingewickelt wird. Nicht abgefangene Fehler werden auch in der Konsole des Ziel-Tabs gemeldet.

Das Ergebnis eines Skripts ist der Wert, der durch die letzte ausgewertete Anweisung produziert wird. Wenn die letzte Anweisung ein Promise erzeugt, ist das Ergebnis der festgelegte Wert dieses Promises. Dies ist ähnlich den Ergebnissen, die Sie sehen, wenn Sie das Script in der Web-Konsole ausführen (ohne jegliche console.log()-Ausgaben). Zum Beispiel, betrachten Sie ein Script wie dieses:

let foo = "my result";
foo;

Hier enthält das Ergebnis-Array den String "my result" als ein Element.

Das Skriptergebnis muss ein strukturierbarer klonbarer Wert in Firefox oder ein JSON-serialisierbarer Wert in Chrome sein. Der Artikel über Chrome-Inkompatibilitäten behandelt diesen Unterschied ausführlicher im Abschnitt Datenklon-Algorithmus.

Beispiele

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

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

Dieses Beispiel führt ein Skript aus einer Datei aus (die mit der Erweiterung gepackt ist) namens "content-script.js". Das Skript wird im aktiven Tab ausgeführt. Das Skript wird in Subframes und 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}`);
  }
});

Browser-Kompatibilität