scripting.executeScript()

Syntax

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

Parameter

details

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

args Optional

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

files Optional

array von string. Ein Array von Pfaden der JavaScript-Dateien, die eingefügt werden sollen, relativ zum Wurzelverzeichnis der Erweiterung. Genau eines von files und func muss angegeben werden.

func Optional

function. Eine in JavaScript geschriebene Funktion, die eingefügt werden soll. Diese Funktion wird serialisiert und dann zur Injektion deserialisiert. Dies bedeutet, dass alle gebundenen Parameter und der Ausführungskontext verloren gehen. Genau eines von files und func muss angegeben werden.

injectImmediately Optional

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

target

scripting.InjectionTarget. Details, die das Ziel angeben, in das das Skript eingefügt werden soll.

world Optional

scripting.ExecutionWorld. Die Ausführungsumgebung, in der ein Skript ausgeführt werden soll.

Rückgabewert

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

Das Versprechen wird abgelehnt, wenn die Injektion fehlschlägt, beispielsweise wenn das Injektionsziel ungültig ist. Wenn die Skriptausführung begonnen hat, ist das Ergebnis in dem Ergebnis enthalten, ob erfolgreich (als result) oder nicht erfolgreich (als error).

Jedes InjectionResult-Objekt hat folgende Eigenschaften:

frameId

number. Die Frame-ID, die mit der Injektion verbunden ist.

result Optional

any. Das Ergebnis der Skriptausführung.

error Optional

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

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

Das Ergebnis eines Skripts ist der Wert, der durch die letzte ausgewertete Anweisung erzeugt wird. Wenn die letzte Anweisung ein Versprechen erzeugt, ist das Ergebnis der abgewickelte Wert dieses Versprechens. Dies ist ähnlich wie die Ergebnisse, die Sie sehen, wenn Sie das Skript in der Web-Konsole ausführen (ohne jegliche console.log() Ausgabe). Zum Beispiel wird ein Skript wie dieses:

let foo = "my result";
foo;

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

Das Skriptergebnis muss ein strukturierter, klonbarer Wert in Firefox oder ein JSON-serialisierbarer Wert in Chrome sein. Der Artikel zu Chrome-Inkompatibilitäten diskutiert diesen Unterschied ausführlicher im Abschnitt Datenklonierungsalgorithmus.

Beispiele

Dieses Beispiel führt ein einzeiliges Code-Snippet im aktiven Tab 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 verpackt ist) namens "content-script.js". Das Skript wird im aktiven Tab ausgeführt. Das Skript wird in Unterrahmen und dem 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