chrome.scripting

Beschreibung

Mit der chrome.scripting API kannst du ein Script in verschiedenen Kontexten ausführen.

Berechtigungen

scripting

Verfügbarkeit

Chrome (ab Version 88) MV3+

Manifest

Deklarieren Sie zur Verwendung der chrome.scripting API die Berechtigung "scripting" im Manifest sowie die Hostberechtigungen für die Seiten, in die Skripts eingeschleust werden sollen. Verwenden Sie den Schlüssel "host_permissions" oder die Berechtigung "activeTab", wodurch temporäre Hostberechtigungen gewährt werden. Im folgenden Beispiel wird die Berechtigung „activeTab“ verwendet.

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

Konzepte und Verwendung

Sie können die chrome.scripting API verwenden, um JavaScript und CSS in Websites. Ähnlich wie bei der Verwendung von Content Skripts verwenden. Wenn Sie jedoch den Namespace chrome.scripting verwenden, können Erweiterungen Entscheidungen zur Laufzeit treffen können.

Injection-Ziele

Sie können den Parameter target verwenden, um ein Ziel anzugeben, um JavaScript einzuschleusen, oder in CSS.

Das einzige Pflichtfeld ist tabId. Standardmäßig wird eine Injection im des angegebenen Tabs.

function getTabId() { ... }

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

Um in allen Frames des angegebenen Tabs ausgeführt zu werden, können Sie den booleschen Wert allFrames festlegen. an true.

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 bestimmte Frames eines Tabs einschleusen, indem Sie einzelne Frames angeben. IDs. Weitere Informationen zu Frame-IDs finden Sie unter chrome.webNavigation API zu erstellen.

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 einzuschleusenden Code entweder über eine externe Datei oder eine Laufzeitvariable.

Dateien

Dateien werden als Strings angegeben, die Pfade relativ zum Stamm der Erweiterung sind -Verzeichnis. Mit dem folgenden Code wird die Datei script.js in die des Tabs.

function getTabId() { ... }

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

Laufzeitfunktionen

Beim Einschleusen von JavaScript mit scripting.executeScript() können Sie ausgeführt werden soll. Diese Funktion sollte eine Funktion sein Variable verfügbar, 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

Wenn Sie CSS auf einer Seite einfügen, können Sie auch einen String zur Verwendung im css-Property. Diese Option ist nur für scripting.insertCSS() verfügbar. ich kann 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 JavaScript-Ausführung werden an die Erweiterung übergeben. Ein einzelnes Ergebnis pro Frame enthalten ist. Der Hauptframe ist garantiert der erste Index im resultierendes Array; alle anderen Frames 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 Wert der Skriptausführung ein Promise ist, wartet Chrome für das Versprechen zur Abrechnung und Rückgabe des resultierenden Werts.

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, mit der die Registrierung des gesamten dynamischen Inhalts aufgehoben wird Skripts, 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(scriptIds);
  } catch (error) {
    const message = [
      "An unexpected error occurred while",
      "unregistering dynamic content scripts.",
    ].join(" ");
    throw new Error(message, {cause : error});
  }
}

Um die chrome.scripting API auszuprobieren, Installieren Sie das Scripting-Beispiel aus den Chrome-Erweiterungsbeispielen. zu erstellen.

Typen

ContentScriptFilter

Chrome 96 und höher

Attribute

  • ids

    string[] optional

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

CSSInjection

Attribute

  • css

    String optional

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

  • Dateien

    string[] optional

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

  • origin

    StyleOrigin optional

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

  • Details zum Angeben des Ziels, in das das CSS eingefügt werden soll.

ExecutionWorld

Chrome 95 und höher

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

Enum

"ISOLATED"
Gibt die isolierte Welt an, also die Ausführungsumgebung dieser Erweiterung.

"MAIN"
Gibt die Hauptwelt des DOMs an, also die Ausführungsumgebung, die für den JavaScript-Code der Hostseite freigegeben ist.

InjectionResult

Attribute

  • documentId

    String

    Chrome 106 und höher

    Das mit der Injektion verknüpfte Dokument.

  • frameId

    Zahl

    Chrome 90 und höher

    Der Frame, der der Injektion zugeordnet ist.

  • Ergebnis

    Beliebige optionale

    Das Ergebnis der Skriptausführung.

InjectionTarget

Attribute

  • allFrames

    Boolescher Wert optional

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

  • documentIds

    string[] optional

    Chrome 106 und höher

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

  • frameIds

    number[] optional

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

  • tabId

    Zahl

    Die ID des Tabs, in den eingeschleust werden soll.

RegisteredContentScript

Chrome 96 und höher

Attribute

  • allFrames

    Boolescher Wert optional

    Wenn Sie „true“ angeben, wird der Frame in alle Frames eingefügt, auch wenn der Frame nicht der oberste Frame auf dem Tab ist. Jeder Frame wird unabhängig auf die URL-Anforderungen überprüft. wird er 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 zugeordnet.

  • 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, in die dieses Inhaltsskript andernfalls eingeschleust würde. Weitere Informationen zur Syntax dieser Strings finden Sie unter Übereinstimmungsmuster.

  • id

    String

    Die im API-Aufruf angegebene ID des Inhaltsskripts. Darf nicht mit einem "_" beginnen da es als Präfix für generierte Skript-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 vorkommen.

  • matchOriginAsFallback

    Boolescher Wert optional

    Chrome 119 oder höher

    Gibt an, ob das Skript in Frames eingeschleust werden kann, deren URL ein nicht unterstütztes Schema enthält; und zwar „about:“, „data:“, „blob:“ oder „filesystem:“. In diesen Fällen wird der Ursprung der URL geprüft, um zu bestimmen, ob das Skript eingeschleust 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 nicht der übergeordnete Frame ist.

  • stimmt überein mit

    string[] optional

    Gibt an, in 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 in zukünftigen Sitzungen beibehalten wird. Die Standardeinstellung ist "true".

  • runAt

    RunAt optional

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

  • Welt

    ExecutionWorld optional

    Chrome 102 und höher

    Die JavaScript-Welt in dem das Skript ausgeführt werden soll. 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ügenden 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 Einschleusung so schnell wie möglich im Ziel ausgelöst werden soll. Dies ist keine Garantie dafür, dass eine Einfügung vor dem Laden der Seite erfolgt, da die Seite möglicherweise bereits geladen ist, als das Skript das Ziel erreicht hat.

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

  • Welt

    ExecutionWorld optional

    Chrome 95 und höher

    Die JavaScript-Welt in dem das Skript ausgeführt werden soll. Die Standardeinstellung ist ISOLATED.

  • func

    void optional

    Chrome 92 und höher

    Eine einzufügende JavaScript-Funktion. Diese Funktion wird serialisiert und dann für die Injektion deserialisiert. Dies 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 für eine Stiländerung. Weitere Informationen finden Sie unter Stilursprünge.

Enum

"AUTHOR"

"NUTZER"

Methoden

executeScript()

<ph type="x-smartling-placeholder"></ph> Versprechen 
chrome.scripting.executeScript(
  injection: ScriptInjection,
  callback?: function,
)

Skript in einen Zielkontext einfügen Standardmäßig wird das Skript unter document_idle oder sofort ausgeführt, wenn die Seite bereits geladen wurde. Wenn das Attribut injectImmediately festgelegt ist, wird das Skript ohne Wartezeit eingefügt, auch wenn die Seite noch nicht fertig geladen ist. Wenn das Skript ein Promise auswertet, wartet der Browser darauf, dass das Promise ausgeglichen wurde, und gibt den resultierenden Wert zurück.

Parameter

Returns

  • Promise&lt;InjectionResult[]&gt;

    Chrome 90 und höher

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks sind jedoch für Abwärtskompatibilität. Sie können nicht beide in demselben Funktionsaufruf verwenden. Die Promise wird mit demselben Typ aufgelöst, der an das Callback übergeben wird.

getRegisteredContentScripts()

<ph type="x-smartling-placeholder"></ph> Versprechen Chrome 96 und 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.

Parameter

Returns

  • Promise&lt;RegisteredContentScript[]&gt;

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks sind jedoch für Abwärtskompatibilität. Sie können nicht beide in demselben Funktionsaufruf verwenden. Die Promise wird mit demselben Typ aufgelöst, der an das Callback übergeben wird.

insertCSS()

<ph type="x-smartling-placeholder"></ph> Versprechen 
chrome.scripting.insertCSS(
  injection: CSSInjection,
  callback?: function,
)

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

Parameter

  • Injektion

    CSSInjection

    Die Details der einzufügenden Stile.

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    () => void

Returns

  • Versprechen<void>

    Chrome 90 und höher

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks sind jedoch für Abwärtskompatibilität. Sie können nicht beide in demselben Funktionsaufruf verwenden. Die Promise wird mit demselben Typ aufgelöst, der an das Callback übergeben wird.

registerContentScripts()

<ph type="x-smartling-placeholder"></ph> Versprechen Chrome 96 und höher 
chrome.scripting.registerContentScripts(
  scripts: RegisteredContentScript[],
  callback?: function,
)

Registriert ein oder mehrere Inhaltsskripte für diese Erweiterung.

Parameter

  • Enthält eine Liste der zu registrierenden Skripts. Wenn beim Parsen des Skripts 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

Returns

  • Versprechen<void>

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks sind jedoch für Abwärtskompatibilität. Sie können nicht beide in demselben Funktionsaufruf verwenden. Die Promise wird mit demselben Typ aufgelöst, der an das Callback übergeben wird.

removeCSS()

<ph type="x-smartling-placeholder"></ph> Versprechen Chrome 90 oder höher 
chrome.scripting.removeCSS(
  injection: CSSInjection,
  callback?: function,
)

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

Parameter

  • Injektion

    CSSInjection

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

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    () => void

Returns

  • Versprechen<void>

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks sind jedoch für Abwärtskompatibilität. Sie können nicht beide in demselben Funktionsaufruf verwenden. Die Promise wird mit demselben Typ aufgelöst, der an das Callback übergeben wird.

unregisterContentScripts()

<ph type="x-smartling-placeholder"></ph> Versprechen Chrome 96 und höher 
chrome.scripting.unregisterContentScripts(
  filter?: ContentScriptFilter,
  callback?: function,
)

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

Parameter

  • Filter

    ContentScriptFilter optional

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

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    () => void

Returns

  • Versprechen<void>

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks sind jedoch für Abwärtskompatibilität. Sie können nicht beide in demselben Funktionsaufruf verwenden. Die Promise wird mit demselben Typ aufgelöst, der an das Callback übergeben wird.

updateContentScripts()

<ph type="x-smartling-placeholder"></ph> Versprechen Chrome 96 und höher 
chrome.scripting.updateContentScripts(
  scripts: RegisteredContentScript[],
  callback?: function,
)

Aktualisiert ein oder mehrere Inhaltsskripte für diese Erweiterung.

Parameter

  • 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 oder der Dateivalidierung 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

Returns

  • Versprechen<void>

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks sind jedoch für Abwärtskompatibilität. Sie können nicht beide in demselben Funktionsaufruf verwenden. Die Promise wird mit demselben Typ aufgelöst, der an das Callback übergeben wird.