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 eingebracht 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. Genau einer von files und func muss angegeben sein.

func Optional

function. Eine JavaScript-Funktion, die eingefügt werden soll. Diese Funktion wird serialisiert und dann zur Injektion deserialisiert. Das bedeutet, dass alle gebundenen Parameter und Ausführungskontexte verloren gehen. Genau einer von files und func muss angegeben sein.

injectImmediately Optional

boolean. Ob die Injektion in das Ziel so schnell wie möglich ausgelöst wird, jedoch nicht unbedingt 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 Promise wird abgelehnt, wenn die Injektion fehlschlägt, z. B. wenn das Injektionsziel ungültig ist. Sobald die Skriptausführung gestartet wurde, ist ihr Ergebnis in dem Ergebnis enthalten, unabhängig davon, ob es erfolgreich (result) oder erfolglos (error) war.

Jedes InjectionResult-Objekt hat folgende Eigenschaften:

documentId

string. Das mit der Injektion verbundene Dokument. Weitere Informationen finden Sie im Artikel Mit documentId arbeiten.

frameId

number. Die mit der Injektion verbundene Frame-ID.

result Optional

any. Das Ergebnis der Skriptausführung.

error Optional

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

Chrome unterstützt die error-Eigenschaft noch nicht (siehe Issue 1271527: Propagate errors from scripting.executeScript to InjectionResult). Alternativ können Laufzeitfehler durch Einwickeln des auszuführenden Codes in eine try-catch-Anweisung abgefangen werden. 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 erzeugt wird. Wenn die letzte Anweisung ein Promise erzeugt, ist das Ergebnis der gesetzte Wert dieses Promise. Dies ist ähnlich den Ergebnissen, die Sie sehen, wenn Sie das Skript in der Web-Konsole ausführen (ausgenommen jede console.log()-Ausgabe). Beispielweise sehen Sie bei einem Skript wie diesem:

let foo = "my result";
foo;

Hier enthält das Ergebnis-Array die Zeichenkette "my result" als Element.

Das Skriptergebnis muss in Firefox einen strukturiert klonbaren Wert oder in Chrome einen JSON-serialisierbaren Wert darstellen. Der Artikel Chrome-Inkompatibilitäten diskutiert diesen Unterschied detaillierter im Abschnitt Datenduplizierungs-Algorithmus.

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 (zusammen mit der Erweiterung gepackt) namens "content-script.js". 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}`);
  }
});

Browser-Kompatibilität