browser.scripting

Beschreibung

Verwenden Sie die chrome.scripting API, um Skripts in verschiedenen Kontexten auszuführen.

Berechtigungen

scripting

Verfügbarkeit

Chrome 88 oder höher browser.* seit Chrome 148 MV3 oder höher

Manifest

Wenn du die browser.scripting API verwenden möchtest, deklariere die Berechtigung "scripting" im Manifest sowie die Hostberechtigungen für die Seiten, in die Scripts eingefügt werden sollen. Verwenden Sie den Schlüssel "host_permissions" oder die Berechtigung "activeTab", die temporäre Hostberechtigungen gewährt. Im folgenden Beispiel wird die Berechtigung „activeTab“ verwendet.

{
  "name": "Scripting Extension",
  "manifest_version": 3,
  "permissions": ["scripting", "activeTab"],
  ...
}

Konzepte und Verwendung

Mit der browser.scripting API können Sie JavaScript und CSS in Websites einfügen. Das ist ähnlich wie bei Inhaltsskripts. Mit dem Namespace browser.scripting können Erweiterungen jedoch Entscheidungen zur Laufzeit treffen.

Injektionsziele

Mit dem Parameter target können Sie ein Ziel angeben, in das JavaScript oder CSS eingefügt werden soll.

Das einzige erforderliche Feld ist tabId. Standardmäßig wird eine Injektion im Hauptframe des angegebenen Tabs ausgeführt.

function getTabId() { ... }

browser.scripting
    .executeScript({
      target : {tabId : getTabId()},
      files : [ "script.js" ],
    })
    .then(() => console.log("script injected"));

Wenn die Ausführung in allen Frames des angegebenen Tabs erfolgen soll, können Sie den booleschen Wert allFrames auf true setzen.

function getTabId() { ... }

browser.scripting
    .executeScript({
      target : {tabId : getTabId(), allFrames : true},
      files : [ "script.js" ],
    })
    .then(() => console.log("script injected in all frames"));

Sie können auch in bestimmte Frames eines Tabs einfügen, indem Sie einzelne Frame-IDs angeben. Weitere Informationen zu Frame-IDs finden Sie in der browser.webNavigation API.

function getTabId() { ... }

browser.scripting
    .executeScript({
      target : {tabId : getTabId(), frameIds : [ frameId1, frameId2 ]},
      files : [ "script.js" ],
    })
    .then(() => console.log("script injected on target frames"));

Hinweis: Sie können nicht sowohl die Property "frameIds" als auch die Property "allFrames" angeben.

Eingeschleuster Code

Erweiterungen können den einzufügenden Code entweder über eine externe Datei oder eine Laufzeitvariable angeben.

Dateien

Dateien werden als Strings angegeben, die Pfade relativ zum Stammverzeichnis der Erweiterung sind. Mit dem folgenden Code wird die Datei script.js in den Hauptframe des Tabs eingefügt.

function getTabId() { ... }

browser.scripting
    .executeScript({
      target : {tabId : getTabId()},
      files : [ "script.js" ],
    })
    .then(() => console.log("injected script file"));

Laufzeitfunktionen

Wenn Sie JavaScript mit scripting.executeScript() einfügen, können Sie eine Funktion angeben, die anstelle einer Datei ausgeführt werden soll. Diese Funktion sollte eine Funktionsvariable sein, die im aktuellen Erweiterungskontext verfügbar ist.

function getTabId() { ... }
function getTitle() { return document.title; }

browser.scripting
    .executeScript({
      target : {tabId : getTabId()},
      func : getTitle,
    })
    .then(() => console.log("injected a function"));

function getTabId() { ... }
function getUserColor() { ... }

function changeBackgroundColor() {
  document.body.style.backgroundColor = getUserColor();
}

browser.scripting
    .executeScript({
      target : {tabId : getTabId()},
      func : changeBackgroundColor,
    })
    .then(() => console.log("injected a function"));

Sie können dieses Problem umgehen, indem Sie die Property args verwenden:

function getTabId() { ... }
function getUserColor() { ... }
function changeBackgroundColor(backgroundColor) {
  document.body.style.backgroundColor = backgroundColor;
}

browser.scripting
    .executeScript({
      target : {tabId : getTabId()},
      func : changeBackgroundColor,
      args : [ getUserColor() ],
    })
    .then(() => console.log("injected a function"));

Laufzeitstrings

Wenn Sie CSS in eine Seite einfügen, können Sie auch einen String angeben, der im Attribut css verwendet werden soll. Diese Option ist nur für scripting.insertCSS() verfügbar. Sie können einen String nicht mit scripting.executeScript() ausführen.

function getTabId() { ... }
const css = "body { background-color: red; }";

browser.scripting
    .insertCSS({
      target : {tabId : getTabId()},
      css : css,
    })
    .then(() => console.log("CSS injected"));

Ergebnisse verarbeiten

Die Ergebnisse der JavaScript-Ausführung werden an die Erweiterung übergeben. Pro Frame ist ein einzelnes Ergebnis enthalten. Der Hauptframe ist garantiert der erste Index im resultierenden Array. Alle anderen Frames sind in einer nicht deterministischen Reihenfolge.

function getTabId() { ... }
function getTitle() { return document.title; }

browser.scripting
    .executeScript({
      target : {tabId : getTabId(), allFrames : true},
      func : getTitle,
    })
    .then(injectionResults => {
      for (const {frameId, result} of injectionResults) {
        console.log(`Frame ${frameId} result:`, result);
      }
    });

scripting.insertCSS() gibt keine Ergebnisse zurück.

Promise-Objekte

Wenn der resultierende Wert der Skriptausführung ein Promise ist, wartet Chrome, bis das Promise erfüllt ist, und gibt den resultierenden Wert zurück.

function getTabId() { ... }
async function addIframe() {
  const iframe = document.createElement("iframe");
  const loadComplete =
      new Promise(resolve => iframe.addEventListener("load", resolve));
  iframe.src = "https://example.com";
  document.body.appendChild(iframe);
  await loadComplete;
  return iframe.contentWindow.document.title;
}

browser.scripting
    .executeScript({
      target : {tabId : getTabId(), allFrames : true},
      func : addIframe,
    })
    .then(injectionResults => {
      for (const frameResult of injectionResults) {
        const {frameId, result} = frameResult;
        console.log(`Frame ${frameId} result:`, result);
      }
    });

Beispiele

Registrierung aller dynamischen Inhaltsskripts aufheben

Das folgende Snippet enthält eine Funktion, mit der alle dynamischen Inhaltsskripts abgemeldet werden, die die Erweiterung zuvor registriert hat.

async function unregisterAllDynamicContentScripts() {
  try {
    const scripts = await browser.scripting.getRegisteredContentScripts();
    const scriptIds = scripts.map(script => script.id);
    return browser.scripting.unregisterContentScripts({ ids: scriptIds });
  } catch (error) {
    const message = [
      "An unexpected error occurred while",
      "unregistering dynamic content scripts.",
    ].join(" ");
    throw new Error(message, {cause : error});
  }
}

Wichtiger Hinweis: Durch das Abmelden von Inhaltsskripts werden bereits eingefügte Skripts oder Stile nicht entfernt.

Wenn Sie die browser.scripting API ausprobieren möchten, installieren Sie das Scripting-Beispiel aus dem Repository mit Beispielen für Chrome-Erweiterungen.

Typen

ContentScriptFilter

Chrome 96+ browser.* seit Chrome 148

Attribute

• ids

  string[] optional

  Wenn angegeben, werden von getRegisteredContentScripts nur Skripts mit einer ID zurückgegeben, die in dieser Liste angegeben ist.

CSSInjection

Attribute

• css

  String optional

  Ein String, der das einzufügende CSS enthält. Es muss genau eines von files und css angegeben werden.

• Dateien

  string[] optional

  Der Pfad der einzufügenden CSS-Dateien, relativ zum Stammverzeichnis der Erweiterung. Es muss genau eines von files und css angegeben werden.

• origin

  StyleOrigin optional

  Der Stilursprung für die Injektion. Die Standardeinstellung ist 'AUTHOR'.

• Ziel

  InjectionTarget

  Details, die das Ziel angeben, in das das CSS eingefügt werden soll.

ExecutionWorld

Chrome 95 und höher browser.* seit Chrome 148

Die JavaScript-Welt, in der ein Script ausgeführt werden soll.

Enum

"ISOLATED"
Gibt die isolierte Welt an, d. h. die Ausführungsumgebung, die für diese Erweiterung eindeutig ist.

"MAIN"
Gibt die Hauptwelt des DOM an, d. h. die Ausführungsumgebung, die mit dem JavaScript der Hostseite geteilt wird.

InjectionResult

Attribute

• documentId

  String

  Chrome 106 und höher browser.* seit Chrome 148

  Das mit der Injektion verknüpfte Dokument.

• frameId

  Zahl

  Chrome 90 und höher browser.* seit Chrome 148

  Der mit der Injektion verknüpfte Frame.

• Ergebnis

  any optional

  Das Ergebnis der Skriptausführung.

InjectionTarget

Attribute

• allFrames

  Boolesch optional

  Gibt an, ob das Script in alle Frames im Tab eingefügt werden soll. Die Standardeinstellung ist "false". Dies darf nicht „true“ sein, wenn frameIds angegeben ist.

• documentIds

  string[] optional

  Chrome 106 und höher browser.* seit Chrome 148

  Die IDs bestimmter documentIds, in die eingefügt werden soll. Diese darf nicht festgelegt werden, wenn frameIds festgelegt ist.

• frameIds

  number[] optional

  Die IDs bestimmter Frames, in die eingefügt werden soll.

• tabId

  Zahl

  Die ID des Tabs, in den der Code eingefügt werden soll.

RegisteredContentScript

Chrome 96+ browser.* seit Chrome 148

Attribute

• allFrames

  Boolesch optional

  Wenn „true“ angegeben ist, wird das Script in alle Frames eingefügt, auch wenn der Frame nicht der oberste Frame im Tab ist. Jeder Frame wird unabhängig auf Anforderungen an URLs geprüft. Wenn die Anforderungen an URLs nicht erfüllt sind, wird das Skript nicht in untergeordnete Frames eingefügt. Die Standardeinstellung ist „false“, d. h., dass nur der oberste Frame abgeglichen wird.

• css

  string[] optional

  Die Liste der CSS-Dateien, die in übereinstimmende Seiten eingefügt werden sollen. Sie werden in der Reihenfolge eingefügt, in der sie in diesem Array angezeigt werden, bevor ein DOM für die Seite erstellt oder angezeigt wird.

• excludeMatches

  string[] optional

  Schließt Seiten aus, in die dieses Inhaltsskript sonst eingefügt werden würde. Weitere Informationen zur Syntax dieser Strings finden Sie unter Übereinstimmungsmuster.

• id

  String

  Die ID des Inhaltsskripts, die im API-Aufruf angegeben ist. Darf nicht mit einem „_“ beginnen, da dieses Zeichen als Präfix für generierte Script-IDs reserviert ist.

• js

  string[] optional

  Die Liste der JavaScript-Dateien, die in übereinstimmende Seiten eingefügt werden sollen. Diese werden in der Reihenfolge eingefügt, in der sie in diesem Array angezeigt werden.

• matchOriginAsFallback

  Boolesch optional

  Chrome 119 und höher browser.* seit Chrome 148

  Gibt an, ob das Script in Frames eingefügt werden kann, deren URL ein nicht unterstütztes Schema enthält, insbesondere: about:, data:, blob: oder filesystem:. In diesen Fällen wird der Ursprung der URL geprüft, um festzustellen, ob das Script eingefügt werden soll. Wenn der Ursprung null ist (wie bei data:-URLs), ist der verwendete Ursprung entweder der Frame, der den aktuellen Frame erstellt hat, oder der Frame, der die Navigation zu diesem Frame initiiert hat. Beachten Sie, dass dies möglicherweise nicht der übergeordnete Frame ist.

• stimmt überein mit

  string[] optional

  Gibt an, in welche Seiten dieses Inhaltsskript eingefügt wird. Weitere Informationen zur Syntax dieser Strings finden Sie unter Übereinstimmungsmuster. Muss für registerContentScripts angegeben werden.

• persistAcrossSessions

  Boolesch optional

  Gibt an, ob dieses Inhaltsskript in zukünftigen Sitzungen beibehalten wird. Die Standardeinstellung ist "true".

• runAt

  RunAt optional

  Gibt an, wann JavaScript-Dateien in die Webseite eingefügt werden. Der bevorzugte und Standardwert ist document_idle.

• Welt

  ExecutionWorld optional

  Chrome 102 und höher browser.* seit Chrome 148

  Die JavaScript-„Welt“, in der das Script ausgeführt werden soll. Die Standardeinstellung ist ISOLATED.

ScriptInjection

Attribute

• args

  any[] optional

  Chrome 92+ browser.* seit Chrome 148

  Die Argumente, die an die bereitgestellte Funktion übergeben werden sollen. Dies ist nur gültig, wenn der Parameter func angegeben ist. Diese Argumente müssen JSON-serialisierbar sein.

• Dateien

  string[] optional

  Der Pfad der einzufügenden JS- oder CSS-Dateien, relativ zum Stammverzeichnis der Erweiterung. Es muss genau eines von files und func angegeben werden.

• injectImmediately

  Boolesch optional

  Chrome 102 und höher browser.* seit Chrome 148

  Gibt an, ob die Injektion im Ziel so schnell wie möglich ausgelöst werden soll. Das ist jedoch keine Garantie dafür, dass die Einfügung vor dem Seitenaufbau erfolgt, da die Seite möglicherweise bereits geladen wurde, wenn das Skript das Ziel erreicht.

• Ziel

  InjectionTarget

  Details, die das Ziel angeben, in das das Script eingefügt werden soll.

• Welt

  ExecutionWorld optional

  Chrome 95 und höher browser.* seit Chrome 148

  Die JavaScript-„Welt“, in der das Script ausgeführt werden soll. Die Standardeinstellung ist ISOLATED.

• func

  void optional

  Chrome 92+ browser.* seit Chrome 148

  Eine JavaScript-Funktion, die eingefügt werden soll. Diese Funktion wird serialisiert und dann für die Injektion deserialisiert. Das bedeutet, dass alle gebundenen Parameter und der Ausführungskontext verloren gehen. Es muss genau eines von files und func angegeben werden.

  Die Funktion func sieht so aus:

  () => {...}

StyleOrigin

Der Ursprung einer Stiländerung. Weitere Informationen finden Sie unter Stilursprünge.

Enum

"AUTHOR"

"USER"

Methoden

executeScript()

browser.scripting.executeScript(
  injection: ScriptInjection,
): Promise<InjectionResult[]>

Fügt ein Script in einen Zielkontext ein. Standardmäßig wird das Script bei document_idle ausgeführt oder sofort, wenn die Seite bereits geladen wurde. Wenn das Attribut injectImmediately festgelegt ist, wird das Script ohne Wartezeit eingefügt, auch wenn die Seite noch nicht vollständig geladen ist. Wenn das Skript zu einem Promise ausgewertet wird, wartet der Browser, bis das Promise erfüllt ist, und gibt den resultierenden Wert zurück.

Parameter

• Injektion

  ScriptInjection

  Die Details des einzufügenden Skripts.

Ausgabe

• Promise<InjectionResult[]>

  Chrome 90 und höher browser.* seit Chrome 148

  Gibt ein Promise zurück, das nach Abschluss der Injektion aufgelöst wird. Das resultierende Array enthält das Ergebnis der Ausführung für jeden Frame, in dem die Injektion erfolgreich war.

getRegisteredContentScripts()

Chrome 96+ browser.* seit Chrome 148

browser.scripting.getRegisteredContentScripts(
  filter?: ContentScriptFilter,
): Promise<RegisteredContentScript[]>

Gibt alle dynamisch registrierten Inhaltsskripts für diese Erweiterung zurück, die dem angegebenen Filter entsprechen.

Parameter

• Filter

  ContentScriptFilter optional

  Ein Objekt, mit dem die dynamisch registrierten Skripts der Erweiterung gefiltert werden.

Ausgabe

• Promise<RegisteredContentScript[]>

insertCSS()

browser.scripting.insertCSS(
  injection: CSSInjection,
): Promise<void>

Fügt ein CSS-Stylesheet in einen Zielkontext ein. Wenn mehrere Frames angegeben sind, werden fehlgeschlagene Injektionen ignoriert.

Parameter

• Injektion

  CSSInjection

  Die Details der einzufügenden Stile.

Ausgabe

• Promise<void>

  Chrome 90 und höher browser.* seit Chrome 148

  Gibt ein Promise zurück, das nach Abschluss des Einfügens aufgelöst wird.

registerContentScripts()

Chrome 96+ browser.* seit Chrome 148

browser.scripting.registerContentScripts(
  scripts: RegisteredContentScript[],
): Promise<void>

Registriert ein oder mehrere Inhaltsskripts für diese Erweiterung.

Parameter

• Skripts

  RegisteredContentScript[]

  Enthält eine Liste der zu registrierenden Skripts. Wenn beim Parsen des Scripts oder bei der Dateivalidierung Fehler auftreten oder die angegebenen IDs bereits vorhanden sind, werden keine Scripts registriert.

Ausgabe

• Promise<void>

  Gibt ein Promise zurück, das aufgelöst wird, sobald die Skripts vollständig registriert wurden, oder abgelehnt wird, wenn ein Fehler aufgetreten ist.

removeCSS()

Chrome 90 und höher browser.* seit Chrome 148

browser.scripting.removeCSS(
  injection: CSSInjection,
): Promise<void>

Entfernt ein CSS-Stylesheet, das zuvor von dieser Erweiterung eingefügt wurde, aus einem Zielkontext.

Parameter

• Injektion

  CSSInjection

  Die Details der zu entfernenden Stile. Die Properties css, files und origin müssen genau mit dem Stylesheet übereinstimmen, das über insertCSS eingefügt wurde. Der Versuch, ein nicht vorhandenes Stylesheet zu entfernen, ist ein No-Op.

Ausgabe

• Promise<void>

  Gibt ein Promise zurück, das nach Abschluss des Entfernens aufgelöst wird.

unregisterContentScripts()

Chrome 96+ browser.* seit Chrome 148

browser.scripting.unregisterContentScripts(
  filter?: ContentScriptFilter,
): Promise<void>

Meldet Inhaltsskripts für diese Erweiterung ab.

Parameter

• Filter

  ContentScriptFilter optional

  Wenn angegeben, werden nur dynamische Inhaltsskripts abgemeldet, die dem Filter entsprechen. Andernfalls wird die Registrierung aller dynamischen Inhaltsskripts der Erweiterung aufgehoben.

Ausgabe

• Promise<void>

  Gibt ein Promise zurück, das aufgelöst wird, sobald die Registrierung der Skripts aufgehoben wurde, oder abgelehnt wird, wenn ein Fehler aufgetreten ist.

updateContentScripts()

Chrome 96+ browser.* seit Chrome 148

browser.scripting.updateContentScripts(
  scripts: RegisteredContentScript[],
): Promise<void>

Aktualisiert ein oder mehrere Inhaltsskripts für diese Erweiterung.

Parameter

• Skripts

  RegisteredContentScript[]

  Enthält eine Liste der zu aktualisierenden Scripts. Eine Property wird für das vorhandene Script nur aktualisiert, wenn sie in diesem Objekt angegeben ist. Wenn beim Parsen des Scripts oder bei der Dateivalidierung Fehler auftreten oder die angegebenen IDs nicht zu einem vollständig registrierten Script gehören, werden keine Scripts aktualisiert.

Ausgabe

• Promise<void>

  Gibt ein Promise zurück, das aufgelöst wird, sobald die Skripts aktualisiert wurden, oder abgelehnt wird, wenn ein Fehler aufgetreten ist.