scripting.executeScript()

Syntax

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

Parameter

details

Ein Objekt, das das zu injizierende Skript beschreibt. Es enthält diese Eigenschaften:

args Optional

Ein Array von Argumenten, die in die Funktion übernommen werden sollen. 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 zu den zu injizierenden JS-Dateien, relativ zum Stammverzeichnis der Erweiterung. Genau eines von files und func muss angegeben werden.

func Optional

function. Eine zu injizierende JavaScript-Funktion. Diese Funktion wird serialisiert und dann zur Injektion deserialisiert. Das bedeutet, dass alle gebundenen Parameter und Ausführungskontexte 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, jedoch nicht unbedingt vor dem Laden der Seite.

target

scripting.InjectionTarget. Details, die das Ziel für das Skript beschreiben.

world Optional

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

Rückgabewert

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

Das Promise wird abgelehnt, wenn die Injektion fehlschlägt, beispielsweise wenn das Injektionsziel ungültig ist. Wenn die Skriptausführung begonnen hat, ist ihr Ergebnis im Ergebnis enthalten, sowohl bei erfolgreicher (als result) als auch bei erfolgloser (als error) Ausführung.

Jedes InjectionResult-Objekt hat diese Eigenschaften:

frameId

number. Die Frame-ID, die der Injektion zugeordnet ist.

result Optional

any. Das Ergebnis der Skriptausführung.

error Optional

any. Tritt ein Fehler auf, enthält er den Wert, mit dem das Skript eine Ausnahme ausgelöst oder abgelehnt hat. Typischerweise ist dies ein Fehlerobjekt mit einer Nachrichten-Eigenschaft, aber es könnte jeder Wert sein (einschließlich primitiver Typen und undefined).

Chrome unterstützt die error-Eigenschaft noch nicht (siehe Issue 1271527: Propagate errors from scripting.executeScript to InjectionResult). Alternativ können Laufzeitfehler abgefangen werden, indem der Code zur Ausführung in einer try-catch-Anweisung umschlossen wird. Ungefangene Fehler werden ebenfalls an die 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 erfüllte Wert dieses Promise. Dies ähnelt den Ergebnissen, die Sie sehen würden, wenn Sie das Skript in der Web-Konsole ausführen (ohne jegliche console.log() Ausgaben). Betrachten Sie zum Beispiel ein Skript wie dieses:

let foo = "my result";
foo;

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

Das Skriptergebnis muss ein strukturiert klonbarer Wert in Firefox oder ein JSON-serisierbarer Wert in Chrome sein. Der Chrome-Inkompatibilitäten Artikel behandelt diesen Unterschied ausführlicher im Abschnitt Datenklonierungsalgorithmus.

Beispiele

Dieses Beispiel führt einen Einzeilen-Codeausschnitt 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 (mit der Erweiterung gepackt) 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