tabs.executeScript()
Injiziert JavaScript-Code in eine Seite.
Hinweis: Bei der Verwendung von Manifest V3 oder höher sollte scripting.executeScript()
verwendet werden, um Skripte auszuführen.
Sie können Code in Seiten injizieren, deren URL mit einem Match-Muster ausgedrückt werden kann. Dazu muss das Schema eines der folgenden sein: http
, https
oder file
.
Sie müssen die Berechtigung für die URL der Seite haben—entweder explizit als Host-Berechtigung—oder über die activeTab-Berechtigung. Beachten Sie, dass einige spezielle Seiten diese Berechtigung nicht zulassen, darunter die Leseansicht, view-source und PDF-Viewer-Seiten.
Sie können auch Code in Seiten injizieren, die mit Ihrer eigenen Erweiterung verpackt sind:
browser.tabs.create({ url: "/my-page.html" }).then(() => {
browser.tabs.executeScript({
code: `console.log('location:', window.location.href);`,
});
});
Dafür benötigen Sie keine besonderen Berechtigungen.
Sie können keinen Code in eine der eingebauten Seiten des Browsers injizieren, wie: about:debugging
, about:addons
oder die Seite, die sich öffnet, wenn Sie eine neue leere Registerkarte öffnen.
Die Skripte, die Sie injizieren, werden Content-Skripte genannt.
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 die aktive Registerkarte des aktuellen Fensters.
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 ausgegeben. (frameId
undallFrames
schließen sich gegenseitig aus.)Ist
false
, wird der Code nur in den obersten Frame injiziert.Standardmäßig
false
. code
Optional-
string
. Zu injizierender Code als Textzeichenfolge.Warnung: Verwenden Sie diese Eigenschaft nicht, um nicht vertrauenswürdige Daten in JavaScript zu interpolieren, da dies zu einem Sicherheitsproblem führen könnte.
file
Optional-
string
. Pfad zu einer Datei, die den zu injizierenden Code enthält.- In Firefox werden relative URLs, die nicht am Erweiterungsstamm beginnen, relativ zur URL der aktuellen Seite 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 beim Stamm der Erweiterung, so:
"/path/to/script.js"
. frameId
Optional-
integer
. Der Frame, in dem der Code injiziert werden soll.Standardmäßig
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.Standardmäßig
false
. runAt
Optional-
extensionTypes.RunAt
. Der früheste Zeitpunkt, zu dem der Code in die Registerkarte injiziert wird.Standardmäßig
"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, vergleichbar mit dem, was in der Webkonsole ausgegeben würde (die Ergebnisse, nicht die Ausgabe von console.log()
). Zum Beispiel ein Skript wie folgt:
let foo = "my result";
foo;
Hier enthält das Ergebnisarray die Zeichenkette "my result
" als Element.
Die Ergebniswerte müssen strukturklonierbar sein (siehe Datenklonierungsalgorithmus).
Hinweis: Die letzte Anweisung kann auch ein Promise
sein, aber diese Funktion wird von der webextension-polyfill Bibliothek nicht unterstützt.
Wenn ein Fehler auftritt, wird das Versprechen mit einer Fehlermeldung abgelehnt.
Beispiele
Dieses Beispiel führt einzeiligen Code im aktuell aktiven Tab 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 mit der Erweiterung gepacktes Skript aus einer Datei namens "content-script.js"
aus. Das Skript wird im aktuell aktiven Tab ausgeführt. Das Skript wird sowohl in Subframes 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 mit der Erweiterung gepackten Datei namens "content-script.js"
aus. Das Skript wird im Tab 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);
Beispiel-Erweiterungen
Browser-Kompatibilität
BCD tables only load in the browser
Hinweis: Diese API basiert auf Chromiums chrome.tabs
API. Diese Dokumentation leitet sich von tabs.json
im Chromium-Code ab.