chrome.scripting (original) (raw)

Zum Hauptinhalt springen

chrome.scripting

Beschreibung

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

Berechtigungen

scripting

Verfügbarkeit

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

Attribute

CSSInjection

Attribute

ExecutionWorld

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

InjectionTarget

Attribute

RegisteredContentScript

Attribute

ScriptInjection

Attribute

StyleOrigin

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

Enum

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.scripting.getRegisteredContentScripts(
  filter?: ContentScriptFilter,
): Promise<RegisteredContentScript[]>

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

Parameter

Ausgabe

insertCSS()

chrome.scripting.insertCSS(
  injection: CSSInjection,
): Promise

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

Parameter

Ausgabe

registerContentScripts()

chrome.scripting.registerContentScripts(
  scripts: RegisteredContentScript[],
): Promise

Registriert ein oder mehrere Inhaltskripte für diese Erweiterung.

Parameter

Ausgabe

removeCSS()

chrome.scripting.removeCSS(
  injection: CSSInjection,
): Promise

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

Parameter

Ausgabe

unregisterContentScripts()

chrome.scripting.unregisterContentScripts(
  filter?: ContentScriptFilter,
): Promise

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

Parameter

Ausgabe

updateContentScripts()

chrome.scripting.updateContentScripts(
  scripts: RegisteredContentScript[],
): Promise

Aktualisiert ein oder mehrere Inhaltsskripts für diese Erweiterung.

Parameter

Ausgabe

Sofern nicht anders angegeben, sind die Inhalte dieser Seite unter der Creative Commons Attribution 4.0 License und Codebeispiele unter der Apache 2.0 License lizenziert. Weitere Informationen finden Sie in den Websiterichtlinien von Google Developers. Java ist eine eingetragene Marke von Oracle und/oder seinen Partnern.

Zuletzt aktualisiert: 2025-08-11 (UTC).