scripting.executeScript()

details

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

args Optional

Ein Array von Argumenten, die in 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 von Pfaden der JS-Dateien, die eingefügt werden sollen, relativ zum Stammverzeichnis der Erweiterung. Es muss entweder files oder func angegeben werden.

func Optional

function. Eine JavaScript-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. Es muss entweder files oder func 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 spezifizieren, in das das Skript eingefügt werden soll.

world Optional

scripting.ExecutionWorld. Die Ausführungsumgebung für ein Skript.

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

Das Promise wird abgelehnt, wenn die Injektion fehlschlägt, zum Beispiel wenn das Injektionsziel ungültig ist. Wenn die Skriptausführung gestartet wurde, ist ihr Ergebnis im Resultat enthalten, ob erfolgreich (als result) oder erfolglos (als error).

Jedes InjectionResult-Objekt hat die folgenden Eigenschaften:

frameId

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

result Optional

any. Das Ergebnis der Skriptausführung.

error Optional

any. Falls ein Fehler auftritt, enthält es den Wert, den das Skript ausgelöst oder abgelehnt hat. Typischerweise ist dies ein Fehlerobjekt mit einer Nachrichteneigenschaft, aber es könnte jeder Wert sein (einschließlich primitiver und undefinierter Werte).

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 ausführende Code in eine try-catch-Anweisung eingebettet wird. Nicht abgefangene Fehler werden ebenfalls in die Konsole des Ziel-Tabs gemeldet.

Das Ergebnis des Skripts ist die zuletzt ausgewertete Anweisung, ähnlich den Ergebnissen, die Sie sehen würden, wenn Sie das Skript in der Web-Konsole ausführen (nicht die Ausgabe von console.log()). Zum Beispiel, betrachten Sie 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 structured cloneable Wert oder in Chrome ein JSON-serializable Wert sein. Der Artikel Chrome-Inkompatibilitäten behandelt diesen Unterschied ausführlicher im Abschnitt Data cloning algorithm.

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 (im Paket mit der Erweiterung), die "content-script.js" genannt wird. Das Skript wird im aktiven Tab ausgeführt. Das Skript wird in Unterrahmen 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}`);
  }
});