tabs.executeScript()
Injiziert JavaScript-Code in eine Seite.
Hinweis:
Bei der Verwendung von Manifest V3 oder höher verwenden Sie scripting.executeScript()
zum Ausführen von Skripten.
Sie können Code in Seiten injizieren, deren URL mithilfe eines Übereinstimmungsmusters ausgedrückt werden kann. Dazu muss das Schema http
, https
oder file
sein.
Sie müssen die Berechtigung für die Seiten-URL entweder explizit als Host-Berechtigung oder über die activeTab-Berechtigung haben. Beachten Sie, dass einige spezielle Seiten diese Berechtigung nicht zulassen, einschließlich Leseansicht, Quelltextansicht und PDF-Viewer-Seiten.
Sie können auch Code in mit Ihrer eigenen Erweiterung gepackte Seiten injizieren:
browser.tabs.create({ url: "/my-page.html" }).then(() => {
browser.tabs.executeScript({
code: `console.log('location:', window.location.href);`,
});
});
Dazu benötigen Sie keine besonderen Berechtigungen.
Sie können keinen Code in eine der eingebauten Seiten des Browsers injizieren, wie z. B.: about:debugging
, about:addons
oder die Seite, die geöffnet wird, wenn Sie eine neue leere Registerkarte öffnen.
Die von Ihnen injizierten Skripte werden als Content-Skripte bezeichnet.
Dies ist eine asynchrone Funktion, die ein Promise
zurückgibt.
Syntax
let executing = browser.tabs.executeScript(
tabId, // optional integer
details // object
)
Parameter
tabId
Optional-
integer
. Die ID der Registerkarte, in der das Skript ausgeführt werden soll.Standardmäßig wird die aktive Registerkarte des aktuellen Fensters verwendet.
details
-
Ein Objekt, das das auszuführende Skript beschreibt.
Es enthält die folgenden Eigenschaften:
allFrames
Optional-
boolean
. Wenntrue
, wird der Code in alle Frames der aktuellen Seite injiziert.Wenn
true
undframeId
gesetzt sind, wird ein Fehler ausgelöst. (frameId
undallFrames
schließen sich gegenseitig aus.)Wenn es
false
ist, wird der Code nur in den obersten Frame injiziert.Standard ist
false
. code
Optional-
string
. Code, der als Textzeichenfolge injiziert werden soll.Warnung: Verwenden Sie diese Eigenschaft nicht, um nicht vertrauenswürdige Daten in JavaScript zu interpolieren, da dies ein Sicherheitsproblem darstellen könnte.
file
Optional-
string
. Pfad zu einer Datei, die den zu injizierenden Code enthält.- In Firefox werden relative URLs, die nicht am Erweiterungsroot beginnen, relativ zur aktuellen Seiten-URL aufgelöst.
- In Chrome werden diese URLs relativ zur Basis-URL der Erweiterung aufgelöst.
Um browserübergreifend zu arbeiten, können Sie den Pfad als relative URL angeben, beginnend am Root der Erweiterung, etwa so:
"/path/to/script.js"
. frameId
Optional-
integer
. Der Frame, in den der Code injiziert werden soll.Standardwert ist
0
(der oberste Frame). matchAboutBlank
Optional-
boolean
. Wenntrue
, wird der Code in eingebetteteabout:blank
- undabout:srcdoc
-Frames injiziert, wenn Ihre Erweiterung Zugriff auf deren übergeordnetes Dokument hat. Der Code kann nicht in obersteabout:
-Frames eingefügt werden.Standard ist
false
. runAt
Optional-
extensionTypes.RunAt
. Der früheste Zeitpunkt, zu dem der Code in die Registerkarte injiziert wird.Standard ist
"document_idle"
.
Rückgabewert
Ein Promise
, das zu einem Array von Objekten aufgelöst wird. Die Werte des Arrays repräsentieren das Ergebnis des Skripts in jedem injizierten Frame.
Das Ergebnis des Skripts ist die zuletzt ausgewertete Anweisung, die dem ähnlich ist, was (die Ergebnisse, nicht etwa console.log()
-Ausgaben) ausgegeben würde, wenn Sie das Skript in der Webkonsole ausgeführt hätten. Betrachten Sie beispielsweise ein Skript wie dieses:
let foo = "my result";
foo;
Hier enthält das Ergebnissarray die Zeichenkette "my result"
als Element.
Die Ergebniswerte müssen strukturklonbar sein (siehe Datenklonierungs-Algorithmus).
Hinweis:
Die letzte Anweisung kann auch ein Promise
sein, aber diese Funktion wird von der webextension-polyfill Bibliothek nicht unterstützt.
Tritt ein Fehler auf, wird das Promise mit einer Fehlermeldung abgelehnt.
Beispiele
Dieses Beispiel führt ein einzeiliges Codesnippet in der momentan aktiven Registerkarte aus:
function onExecuted(result) {
console.log(`We made it green`);
}
function onError(error) {
console.log(`Error: ${error}`);
}
const makeItGreen = 'document.body.style.border = "5px solid green"';
const executing = browser.tabs.executeScript({
code: makeItGreen,
});
executing.then(onExecuted, onError);
Dieses Beispiel führt ein Skript aus einer Datei aus (mit der Erweiterung gepackt) mit dem Namen "content-script.js"
. Das Skript wird in der aktuell aktiven Registerkarte ausgeführt. Das Skript wird sowohl in Unterrahmen als auch im Hauptdokument ausgeführt:
function onExecuted(result) {
console.log(`We executed in all subframes`);
}
function onError(error) {
console.log(`Error: ${error}`);
}
const executing = browser.tabs.executeScript({
file: "/content-script.js",
allFrames: true,
});
executing.then(onExecuted, onError);
Dieses Beispiel führt ein Skript aus einer Datei aus (mit der Erweiterung gepackt) mit dem Namen "content-script.js"
. Das Skript wird in der Registerkarte mit der ID 2
ausgeführt:
function onExecuted(result) {
console.log(`We executed in tab 2`);
}
function onError(error) {
console.log(`Error: ${error}`);
}
const executing = browser.tabs.executeScript(2, {
file: "/content-script.js",
});
executing.then(onExecuted, onError);
Beispielerweiterungen
Browser-Kompatibilität
Hinweis:
Diese API basiert auf Chromium's chrome.tabs
API. Diese Dokumentation wird abgeleitet von tabs.json
im Chromium-Code.