chrome.scripting

Beschreibung

Mit der chrome.scripting API können Sie Skripts in verschiedenen Kontexten ausführen.

Berechtigungen

scripting

Verfügbarkeit

Chrome 88+ MV3+

Manifest

Wenn Sie die chrome.scripting API verwenden möchten, müssen Sie die Berechtigung "scripting" im Manifest sowie die Hostberechtigungen für die Seiten deklarieren, in die Skripts eingefügt werden sollen. Verwenden Sie den Schlüssel "host_permissions" oder die Berechtigung "activeTab", mit der temporäre Hostberechtigungen erteilt werden. Im folgenden Beispiel wird die Berechtigung „activeTab“ verwendet.

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

Konzepte und Verwendung

Mit der chrome.scripting API können Sie JavaScript und CSS in Websites einfügen. Das ist ähnlich wie bei Inhaltsskripts. Durch die Verwendung des Namespace chrome.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 Pflichtfeld ist tabId. Standardmäßig wird eine Injektion im Hauptframe des angegebenen Tabs ausgeführt.

function getTabId() { ... }

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

Wenn Sie den Code in allen Frames des angegebenen Tabs ausführen möchten, können Sie den booleschen Wert allFrames auf true festlegen.

function getTabId() { ... }

chrome.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 chrome.webNavigation API.

function getTabId() { ... }

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

Eingefügter 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() { ... }

chrome.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 anstelle einer Datei eine Funktion angeben, die ausgeführt werden soll. Diese Funktion sollte eine Funktionsvariable sein, die für den aktuellen Erweiterungskontext verfügbar ist.

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

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

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

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

chrome.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;
}

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

Laufzeit-Strings

Wenn Sie CSS auf einer Seite einfügen, können Sie auch einen String für die css-Eigenschaft angeben. Diese Option ist nur für scripting.insertCSS() verfügbar. Mit scripting.executeScript() können Sie keinen String ausführen.

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

chrome.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; }

chrome.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;
}

chrome.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

Alle dynamischen Content-Scripts abmelden

Das folgende Snippet enthält eine Funktion, mit der die Registrierung aller dynamischen Inhaltsskripts aufgehoben wird, die die Erweiterung zuvor registriert hat.

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

Wenn Sie die chrome.scripting API ausprobieren möchten, installieren Sie das Scripting-Beispiel aus dem Repository Chrome-Erweiterungsbeispiele.

Typen

ContentScriptFilter

Chrome 96 und höher

Attribute

  • ids

    string[] optional

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

CSSInjection

Attribute

  • css

    String optional

    Ein String mit dem einzufügenden CSS. 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 Einfügung. Die Standardeinstellung ist 'AUTHOR'.

  • Details zum Ziel, in das das CSS eingefügt werden soll.

ExecutionWorld

Chrome 95 und höher

Die JavaScript-Umgebung, in der ein Skript ausgeführt werden soll.

Enum

„ISOLATED“
Gibt die isolierte Welt an, die die für diese Erweiterung eindeutige Ausführungsumgebung ist.

„MAIN“
Gibt die Hauptwelt des DOM an. Das ist die Ausführungsumgebung, die mit dem JavaScript der Hostseite geteilt wird.

InjectionResult

Attribute

  • documentId

    String

    Chrome 106 und höher

    Das Dokument, das mit der Einfügung verknüpft ist.

  • frameId

    Zahl

    Chrome 90 und höher

    Der Frame, der mit der Einfügung verknüpft ist.

  • Ergebnis

    Beliebig optional

    Das Ergebnis der Skriptausführung.

InjectionTarget

Attribute

  • allFrames

    boolean optional

    Gibt an, ob das Skript in alle Frames auf dem Tab eingefügt werden soll. Die Standardeinstellung ist "false". Darf nicht zutreffen, wenn frameIds angegeben ist.

  • documentIds

    string[] optional

    Chrome 106 und höher

    Die IDs der spezifischen documentIds, in die eingefügt werden soll. Darf nicht festgelegt werden, wenn frameIds festgelegt ist.

  • frameIds

    number[] optional

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

  • tabId

    Zahl

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

RegisteredContentScript

Chrome 96 und höher

Attribute

  • allFrames

    boolean optional

    Wenn „true“ angegeben ist, wird der Code in alle Frames eingefügt, auch wenn der Frame nicht der oberste Frame auf dem Tab ist. Jeder Frame wird unabhängig auf URL-Anforderungen geprüft. Wenn die URL-Anforderungen nicht erfüllt sind, wird der Code nicht in untergeordnete Frames eingefügt. Die Standardeinstellung ist „false“. Das bedeutet, 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 aufgeführt sind, bevor ein DOM für die Seite erstellt oder angezeigt wird.

  • excludeMatches

    string[] optional

    Schließt Seiten aus, in die dieses Inhaltsscript ansonsten eingefügt 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 „_“ beginnen, da dieses Zeichen als Präfix für generierte Skript-IDs reserviert ist.

  • js

    string[] optional

    Die Liste der JavaScript-Dateien, die in übereinstimmende Seiten eingefügt werden sollen. Sie werden in der Reihenfolge eingefügt, in der sie in diesem Array aufgeführt sind.

  • matchOriginAsFallback

    boolean optional

    Chrome 119 und höher

    Gibt an, ob das Skript 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 Skript 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. Das muss nicht der übergeordnete Frame sein.

  • stimmt überein mit

    string[] optional

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

  • persistAcrossSessions

    boolean optional

    Gibt an, ob dieses Inhaltsscript 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

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

ScriptInjection

Attribute

  • args

    any[] optional

    Chrome 92 und höher

    Die Argumente, die an die angegebene 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 entweder files oder func angegeben werden.

  • injectImmediately

    boolean optional

    Chrome 102 und höher

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

  • Details zum Ziel, in das das Skript eingefügt werden soll.

  • Welt

    ExecutionWorld optional

    Chrome 95 und höher

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

  • func

    void optional

    Chrome 92 und höher

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

    Die func-Funktion sieht so aus: 

    () => {...}

StyleOrigin

Die Quelle für eine Stiländerung. Weitere Informationen finden Sie unter Stilursprünge.

Enum

"AUTHOR"

"USER"

Methoden

executeScript()

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

Fügt ein Skript in einen Zielkontext ein. Standardmäßig wird das Script bei document_idle ausgeführt oder sofort, wenn die Seite bereits geladen wurde. Wenn die Property injectImmediately festgelegt ist, wird das Script sofort eingefügt, auch wenn die Seite noch nicht vollständig geladen wurde. 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

Ausgabe

getRegisteredContentScripts()

Chrome 96 und höher 
chrome.scripting.getRegisteredContentScripts(
  filter?: ContentScriptFilter,
): Promise<RegisteredContentScript[]>

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

Parameter

  • filtern

    ContentScriptFilter optional

    Ein Objekt zum Filtern der dynamisch registrierten Skripts der Erweiterung.

Ausgabe

insertCSS()

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

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

Parameter

  • Injektion

    CSSInjection

    Die Details der einzufügenden Stile.

Ausgabe

  • Promise<void>

    Chrome 90 und höher

registerContentScripts()

Chrome 96 und höher 
chrome.scripting.registerContentScripts(
  scripts: RegisteredContentScript[],
): Promise<void>

Registriert ein oder mehrere Inhaltskripte für diese Erweiterung.

Parameter

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

Ausgabe

  • Promise<void>

removeCSS()

Chrome 90 und höher 
chrome.scripting.removeCSS(
  injection: CSSInjection,
): Promise<void>

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

Parameter

  • Injektion

    CSSInjection

    Die Details der zu entfernenden Stile. Die Eigenschaften 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, hat keine Auswirkungen.

Ausgabe

  • Promise<void>

unregisterContentScripts()

Chrome 96 und höher 
chrome.scripting.unregisterContentScripts(
  filter?: ContentScriptFilter,
): Promise<void>

Hebt die Registrierung von Content-Scripts für diese Erweiterung auf.

Parameter

  • filtern

    ContentScriptFilter optional

    Wenn angegeben, werden nur dynamische Inhaltsskripts abgemeldet, die dem Filter entsprechen. Andernfalls werden alle Skripts für dynamische Inhalte der Erweiterung abgemeldet.

Ausgabe

  • Promise<void>

updateContentScripts()

Chrome 96 und höher 
chrome.scripting.updateContentScripts(
  scripts: RegisteredContentScript[],
): Promise<void>

Aktualisiert ein oder mehrere Inhaltsskripts für diese Erweiterung.

Parameter

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

Ausgabe

  • Promise<void>