chrome.scripting

Beschreibung

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

Berechtigungen

scripting

Verfügbarkeit

Chrome 88 oder höher MV3+

Manifest

Um die chrome.scripting API zu verwenden, deklarieren Sie die Berechtigung "scripting" im Manifest sowie die Hostberechtigungen für die Seiten, in die Skripts 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 Nutzung

Sie können die chrome.scripting API verwenden, um JavaScript und CSS in Websites einzufügen. Dies ähnelt der Verwendung von Inhaltsskripts. Wenn Sie jedoch den chrome.scripting-Namespace verwenden, können Erweiterungen Entscheidungen zur Laufzeit treffen.

Injektionsziele

Mit dem Parameter target können Sie ein Ziel angeben, in das JavaScript oder CSS eingeschleust werden sollen.

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 in allen Frames des angegebenen Tabs ausgeführt werden sollen, 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 die Informationen auch in bestimmte Frames eines Tabs einschleusen, indem Sie einzelne Frame-IDs angeben. Weitere Informationen zu Frame-IDs findest du unter 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"));

Eingeschleuster Code

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

Files

Dateien werden als Strings angegeben, die sich auf das Stammverzeichnis der Erweiterung beziehen. 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() einschleusen, können Sie angeben, dass anstelle einer Datei eine Funktion 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 das Problem umgehen, indem Sie das Attribut 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"));

Laufzeitstrings

Beim Einfügen von CSS in eine Seite kannst du auch einen String angeben, der in der css-Eigenschaft verwendet werden soll. Diese Option ist nur für scripting.insertCSS() verfügbar. Sie können keinen String mit scripting.executeScript() 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 Ausführung von JavaScript werden an die Erweiterung übergeben. Pro Frame wird ein einzelnes Ergebnis zurückgegeben. Der Hauptframe ist garantiert der erste Index im resultierenden Array. Alle anderen Frames befinden sich 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 darauf, dass das Versprechen 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

Registrierung aller Skripts für dynamische Inhalte aufheben

Das folgende Snippet enthält eine Funktion, die die Registrierung aller Skripts für dynamische Inhalte aufhebt, die von der Erweiterung zuvor registriert wurden.

async function unregisterAllDynamicContentScripts() {
  try {
    const scripts = await chrome.scripting.getRegisteredContentScripts();
    const scriptIds = scripts.map(script => script.id);
    return chrome.scripting.unregisterContentScripts(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 testen möchten, installieren Sie das Scripting-Beispiel aus dem Repository für Chrome-Erweiterungsbeispiele.

Typen

ContentScriptFilter

Chrome 96 oder höher

Attribute

  • ids

    string[] optional

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

CSSInjection

Attribute

  • css

    String optional

    Ein String mit dem zu injizierenden CSS-Code. Es muss genau eines der Attribute files oder css angegeben werden.

  • Dateien

    string[] optional

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

  • Ursprung

    StyleOrigin optional

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

  • Details zum Festlegen des Ziels, in das die CSS eingefügt werden soll

ExecutionWorld

Chrome 95 oder höher

Die JavaScript-Welt, in der ein Skript ausgeführt werden kann.

Enum

"ISOLATED"
Gibt die isolierte Welt an, also die Ausführungsumgebung, die nur für diese Erweiterung verfügbar ist.

"MAIN"
Gibt die Hauptwelt des DOM an, also die Ausführungsumgebung, die gemeinsam mit dem JavaScript der Hostseite verwendet wird.

InjectionResult

Attribute

  • documentId

    String

    Chrome 106 oder höher

    Das mit der Injektion verknüpfte Dokument.

  • frameId

    Zahl

    Chrome 90 oder höher

    Der mit der Injektion verknüpfte Frame.

  • Ergebnis

    Beliebig optional

    Das Ergebnis der Skriptausführung.

InjectionTarget

Attribute

  • allFrames

    Boolescher Wert optional

    Gibt an, ob das Skript in alle Frames auf dem Tab eingeschleust werden soll. Die Standardeinstellung ist "false". Dieser Wert darf nicht „true“ sein, wenn frameIds angegeben ist.

  • documentIds

    string[] optional

    Chrome 106 oder höher

    Die IDs bestimmter documentIds, in die eingeschleust werden soll. Dieser Parameter darf nicht festgelegt werden, wenn frameIds festgelegt ist.

  • frameIds

    nummer[] optional

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

  • tabId

    Zahl

    Die ID des Tabs, in den eingeschleust werden soll.

RegisteredContentScript

Chrome 96 oder höher

Attribute

  • allFrames

    Boolescher Wert optional

    Wenn „true“ angegeben wird, wird der Frame in alle Frames eingeschleust, auch wenn der Frame nicht der oberste Frame auf dem Tab ist. Jeder Frame wird unabhängig auf URL-Anforderungen geprüft. Er wird nicht in untergeordnete Frames eingefügt, wenn die URL-Anforderungen nicht erfüllt sind. Die Standardeinstellung ist „false“, d. h., nur der oberste Frame wird abgeglichen.

  • css

    string[] optional

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

  • excludeMatches

    string[] optional

    Schließt Seiten aus, auf denen dieses Inhaltsskript andernfalls eingeschleust werden würde. Weitere Informationen zur Syntax dieser Strings finden Sie unter Übereinstimmungsmuster.

  • id

    String

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

  • js

    string[] optional

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

  • matchOriginAsFallback

    Boolescher Wert optional

    Chrome 119 und höher

    Gibt an, ob das Skript in Frames eingeschleust 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 überprüft, um festzustellen, ob das Skript eingeschleust werden sollte. 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.

  • Übereinstimmungen

    string[] optional

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

  • persistAcrossSessions

    Boolescher Wert optional

    Gibt an, ob dieses Inhaltsskript auch in zukünftigen Sitzungen erhalten bleiben soll. Die Standardeinstellung ist "true".

  • runAt

    RunAt optional

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

  • welt

    ExecutionWorld optional

    Chrome 102 und höher

    Die JavaScript-„World“, in der das Script ausgeführt wird. Die Standardeinstellung ist ISOLATED.

ScriptInjection

Attribute

  • args

    Beliebig[] 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ührenden JS- oder CSS-Dateien, relativ zum Stammverzeichnis der Erweiterung. Es muss genau entweder files oder func angegeben werden.

  • injectImmediately

    Boolescher Wert optional

    Chrome 102 und höher

    Gibt an, ob die Injektion im Ziel so schnell wie möglich ausgelöst werden soll. Dies ist keine Garantie dafür, dass die Seite vor dem Laden der Seite eingefügt wird, da die Seite möglicherweise bereits geladen wurde, als das Skript das Ziel erreicht hat.

  • Details zum Festlegen des Ziels, in das das Skript eingeschleust werden soll

  • welt

    ExecutionWorld optional

    Chrome 95 oder höher

    Die JavaScript-„World“, in der das Script ausgeführt wird. Die Standardeinstellung ist ISOLATED.

  • func

    void optional

    Chrome 92 und höher

    Eine zu injizierende JavaScript-Funktion. Diese Funktion wird seriell und dann für die Injektion deserialisiert. Das bedeutet, dass alle gebundenen Parameter und der Ausführungskontext verloren gehen. Es muss genau entweder files oder func angegeben werden.

    Die Funktion func sieht so aus: 

    ()=> {...}

StyleOrigin

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

Enum

"AUTHOR"

Methoden

executeScript()

Versprechen 
chrome.scripting.executeScript(
  injection: ScriptInjection,
  callback?: function,
)

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

Parameters

Rückgaben

  • Promise<InjectionResult[]>

    Chrome 90 oder höher

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks werden jedoch aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide in einem Funktionsaufruf verwenden. Das Promise wird mit demselben Typ aufgelöst, der an den Callback übergeben wird.

getRegisteredContentScripts()

Versprechen Chrome 96 oder höher 
chrome.scripting.getRegisteredContentScripts(
  filter?: ContentScriptFilter,
  callback?: function,
)

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

Parameters

Rückgaben

  • Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks werden jedoch aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide in einem Funktionsaufruf verwenden. Das Promise wird mit demselben Typ aufgelöst, der an den Callback übergeben wird.

insertCSS()

Versprechen 
chrome.scripting.insertCSS(
  injection: CSSInjection,
  callback?: function,
)

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

Parameters

  • Injektion

    CSSInjection

    Die Details der einzufügenden Stile.

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    ()=>void

Rückgaben

  • Promise<void>

    Chrome 90 oder höher

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks werden jedoch aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide in einem Funktionsaufruf verwenden. Das Promise wird mit demselben Typ aufgelöst, der an den Callback übergeben wird.

registerContentScripts()

Versprechen Chrome 96 oder höher 
chrome.scripting.registerContentScripts(
  scripts: RegisteredContentScript[],
  callback?: function,
)

Registriert ein oder mehrere Inhaltsskripte für diese Erweiterung.

Parameters

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

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    ()=>void

Rückgaben

  • Promise<void>

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks werden jedoch aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide in einem Funktionsaufruf verwenden. Das Promise wird mit demselben Typ aufgelöst, der an den Callback übergeben wird.

removeCSS()

Versprechen Chrome 90 oder höher 
chrome.scripting.removeCSS(
  injection: CSSInjection,
  callback?: function,
)

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

Parameters

  • Injektion

    CSSInjection

    Die Details der zu entfernenden Stile. Die Eigenschaften css, files und origin müssen genau mit dem durch insertCSS eingefügten Stylesheet übereinstimmen. Der Versuch, ein nicht vorhandenes Stylesheet zu entfernen, ist vertretbar.

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    ()=>void

Rückgaben

  • Promise<void>

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks werden jedoch aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide in einem Funktionsaufruf verwenden. Das Promise wird mit demselben Typ aufgelöst, der an den Callback übergeben wird.

unregisterContentScripts()

Versprechen Chrome 96 oder höher 
chrome.scripting.unregisterContentScripts(
  filter?: ContentScriptFilter,
  callback?: function,
)

Hebt die Registrierung von Inhaltsskripts für diese Erweiterung auf.

Parameters

  • Filter

    ContentScriptFilter optional

    Wenn angegeben, wird nur die Registrierung von Skripts mit dynamischen Inhalten aufgehoben, die dem Filter entsprechen. Andernfalls sind alle Skripts für dynamische Inhalte der Erweiterung nicht registriert.

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    ()=>void

Rückgaben

  • Promise<void>

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks werden jedoch aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide in einem Funktionsaufruf verwenden. Das Promise wird mit demselben Typ aufgelöst, der an den Callback übergeben wird.

updateContentScripts()

Versprechen Chrome 96 oder höher 
chrome.scripting.updateContentScripts(
  scripts: RegisteredContentScript[],
  callback?: function,
)

Aktualisiert ein oder mehrere Inhaltsskripte für diese Erweiterung.

Parameters

  • Enthält eine Liste der zu aktualisierenden Skripts. Eine Eigenschaft wird nur für das vorhandene Skript aktualisiert, wenn sie in diesem Objekt angegeben ist. Falls beim Parsen/der Dateiüberprüfung des Skripts Fehler auftreten oder die angegebenen IDs keinem vollständig registrierten Skript entsprechen, werden keine Skripts aktualisiert.

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    ()=>void

Rückgaben

  • Promise<void>

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks werden jedoch aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide in einem Funktionsaufruf verwenden. Das Promise wird mit demselben Typ aufgelöst, der an den Callback übergeben wird.