chrome.declarativeContent

Aktualisierungsdatum: 2026-09-25 robots: noindex

Beschreibung

Mit der chrome.declarativeContent API können Sie Aktionen basierend auf dem Inhalt einer Seite ausführen, ohne dass eine Berechtigung zum Lesen des Seiteninhalts erforderlich ist.

Berechtigungen

declarativeContent

.

Nutzung

Mit der Declarative Content API können Sie die Aktion Ihrer Erweiterung abhängig von der URL einer Webseite oder davon aktivieren, ob ein CSS-Selektor mit einem Element auf der Seite übereinstimmt. Dazu müssen Sie keine Hostberechtigungen hinzufügen oder ein Inhaltsskript einfügen.

Verwenden Sie die Berechtigung activeTab, um mit einer Seite zu interagieren, nachdem der Nutzer auf die Aktion der Erweiterung geklickt hat.

Regeln

Regeln bestehen aus Bedingungen und Aktionen. Wenn eine der Bedingungen erfüllt ist, werden alle Aktionen ausgeführt. Die Aktionen sind setIcon und showAction.

Das PageStateMatcher entspricht Webseiten nur, wenn alle aufgeführten Kriterien erfüllt sind. Sie kann mit einer Seiten-URL, einem zusammengesetzten CSS-Selektor oder dem Status einer Seite als Lesezeichen übereinstimmen. Mit der folgenden Regel wird die Aktion der Erweiterung auf Google-Seiten aktiviert, wenn ein Passwortfeld vorhanden ist:

let rule1 = {
  conditions: [
    new chrome.declarativeContent.PageStateMatcher({
      pageUrl: { hostSuffix: '.google.com', schemes: ['https'] },
      css: ["input[type='password']"]
    })
  ],
  actions: [ new chrome.declarativeContent.ShowAction() ]
};

Wenn Sie die Aktion der Erweiterung auch für Google-Websites mit einem Video aktivieren möchten, können Sie eine zweite Bedingung hinzufügen, da jede Bedingung ausreicht, um alle angegebenen Aktionen auszulösen:

let rule2 = {
  conditions: [
    new chrome.declarativeContent.PageStateMatcher({
      pageUrl: { hostSuffix: '.google.com', schemes: ['https'] },
      css: ["input[type='password']"]
    }),
    new chrome.declarativeContent.PageStateMatcher({
      css: ["video"]
    })
  ],
  actions: [ new chrome.declarativeContent.ShowAction() ]
};

Mit dem Ereignis onPageChanged wird geprüft, ob für eine Regel mindestens eine Bedingung erfüllt ist. Wenn das der Fall ist, werden die Aktionen ausgeführt. Regeln bleiben über Browsersitzungen hinweg bestehen. Daher sollten Sie bei der Installation der Erweiterung zuerst removeRules verwenden, um zuvor installierte Regeln zu löschen, und dann addRules, um neue zu registrieren.

chrome.runtime.onInstalled.addListener(function(details) {
  chrome.declarativeContent.onPageChanged.removeRules(undefined, function() {
    chrome.declarativeContent.onPageChanged.addRules([rule2]);
  });
});

Mit der Berechtigung activeTab werden in Ihrer Erweiterung keine Berechtigungswarnungen angezeigt. Wenn der Nutzer auf die Erweiterungsaktion klickt, wird sie nur auf relevanten Seiten ausgeführt.

Abgleich von Seiten-URLs

Der PageStateMatcher.pageurl wird abgeglichen, wenn die URL-Kriterien erfüllt sind. Die gängigsten Kriterien sind eine Verkettung von Host, Pfad oder URL, gefolgt von „Enthält“, „Gleich“, „Präfix“ oder „Suffix“. Die folgende Tabelle enthält einige Beispiele:

Kriterien Übereinstimmungen
{ hostSuffix: 'google.com' } Alle Google-URLs
{ pathPrefix: '/docs/extensions' } URLs der Erweiterungsdokumentation
{ urlContains: 'developer.chrome.com' } Alle Chrome-Entwicklerdokumentations-URLs

Bei allen Kriterien wird zwischen Groß- und Kleinschreibung unterschieden. Eine vollständige Liste der Kriterien finden Sie unter UrlFilter.

Abgleich von Preisvergleichsportalen

PageStateMatcher.css-Bedingungen müssen zusammengesetzte Selektoren sein. Das bedeutet, dass Sie keine Kombinatoren wie Leerzeichen oder „>“ in Ihre Selektoren einfügen können. So kann Chrome die Selektoren effizienter abgleichen.

Zusammengesetzte Selektoren (OK) Komplexe Selektoren (nicht OK)
a div p
iframe.special[src^='http'] p>span.highlight
ns|* p + ol
#abcd:checked p::first-line

CSS-Bedingungen stimmen nur mit angezeigten Elementen überein. Wenn ein Element, das mit Ihrem Selektor übereinstimmt, display:none ist oder eines seiner übergeordneten Elemente display:none ist, wird die Bedingung nicht erfüllt. Elemente, die mit visibility:hidden formatiert, außerhalb des Bildschirms positioniert oder durch andere Elemente verborgen sind, können trotzdem dazu führen, dass die Bedingung erfüllt wird.

Abgleich des Lesezeichenstatus

Mit der Bedingung PageStateMatcher.isBookmarked kann der Lesezeichenstatus der aktuellen URL im Profil des Nutzers abgeglichen werden. Damit diese Bedingung verwendet werden kann, muss die Berechtigung „Lesezeichen“ im Manifest der Erweiterung deklariert werden.

Typen

ImageDataType

Weitere Informationen finden Sie unter https://developer.mozilla.org/en-US/docs/Web/API/ImageData.

Typ

ImageData

PageStateMatcher

Entspricht dem Status einer Webseite basierend auf verschiedenen Kriterien.

Attribute

  • Konstruktor

    void

    Die Funktion constructor sieht so aus: 

    (arg: PageStateMatcher) => {...}

  • css

    string[] optional

    Die Bedingung wird erfüllt, wenn alle CSS-Selektoren im Array mit angezeigten Elementen in einem Frame mit demselben Ursprung wie der Hauptframe der Seite übereinstimmen. Alle Selektoren in diesem Array müssen zusammengesetzte Selektoren sein, um den Abgleich zu beschleunigen. Hinweis: Wenn Sie Hunderte von CSS-Selektoren auflisten oder CSS-Selektoren, die Hunderte von Malen pro Seite übereinstimmen, kann dies die Geschwindigkeit von Websites verlangsamen.

  • isBookmarked

    Boolesch optional

    Chrome 45 und höher

    Trifft zu, wenn der Lesezeichenstatus der Seite dem angegebenen Wert entspricht. Erfordert die Berechtigung für Lesezeichen.

  • pageUrl

    UrlFilter optional

    Wird abgeglichen, wenn die Bedingungen von UrlFilter für die URL der obersten Ebene der Seite erfüllt sind.

RequestContentScript

Deklarative Ereignisaktion, mit der ein Content-Script eingefügt wird.

ACHTUNG:Diese Aktion ist noch experimentell und wird in stabilen Versionen von Chrome nicht unterstützt.

Attribute

  • Konstruktor

    void

    Die Funktion constructor sieht so aus: 

    (arg: RequestContentScript) => {...}

  • allFrames

    Boolesch optional

    Gibt an, ob das Content-Script in allen Frames der übereinstimmenden Seite oder nur im obersten Frame ausgeführt wird. Standardwert ist false.

  • css

    string[] optional

    Namen der CSS-Dateien, die als Teil des Inhaltsskripts eingefügt werden sollen.

  • js

    string[] optional

    Namen der JavaScript-Dateien, die als Teil des Content-Scripts eingefügt werden sollen.

  • matchAboutBlank

    Boolesch optional

    Gibt an, ob das Inhaltsscript auf about:blank und about:srcdoc eingefügt werden soll. Der Standardwert ist false.

SetIcon

Deklarative Ereignisaktion, mit der das quadratische Symbol mit n Dips für die Seitenaktion oder Browseraktion der Erweiterung festgelegt wird, wenn die entsprechenden Bedingungen erfüllt sind. Diese Aktion kann ohne Hostberechtigungen verwendet werden, die Erweiterung muss jedoch eine Seiten- oder Browseraktion haben.

Es muss genau eines von imageData und path angegeben werden. Beide sind Dictionaries, die einer Reihe von Pixeln eine Bilddarstellung zuordnen. Die Bilddarstellung in imageData ist ein ImageData-Objekt, z. B. aus einem canvas-Element, während die Bilddarstellung in path der Pfad zu einer Bilddatei relativ zum Manifest der Erweiterung ist. Wenn scale Displaypixel in ein geräteunabhängiges Pixel passen, wird das Symbol scale * n verwendet. Wenn diese Skala fehlt, wird ein anderes Bild auf die erforderliche Größe skaliert.

Attribute

  • Konstruktor

    void

    Die Funktion constructor sieht so aus: 

    (arg: SetIcon) => {...}

  • imageData

    ImageData | object optional

    Entweder ein ImageData-Objekt oder ein Dictionary {size -> ImageData}, das ein festzulegendes Symbol darstellt. Wenn das Symbol als Dictionary angegeben wird, wird das verwendete Bild in Abhängigkeit von der Pixeldichte des Bildschirms ausgewählt. Wenn die Anzahl der Bildpixel, die in eine Einheit des Bildschirmbereichs passen, gleich scale ist, wird ein Bild mit der Größe scale * n ausgewählt, wobei n die Größe des Symbols in der Benutzeroberfläche ist. Es muss mindestens ein Bild angegeben werden. details.imageData = foo entspricht details.imageData = {'16': foo}.

ShowAction

Chrome 97 und höher

Eine deklarative Ereignisaktion, die die Aktion der Symbolleiste der Erweiterung auf „Aktiviert“ setzt, wenn die entsprechenden Bedingungen erfüllt sind. Diese Aktion kann ohne Hostberechtigungen verwendet werden. Wenn die Erweiterung die Berechtigung activeTab hat, wird durch Klicken auf die Seitenaktion Zugriff auf den aktiven Tab gewährt.

Auf Seiten, auf denen die Bedingungen nicht erfüllt sind, wird die Symbolleistenaktion der Erweiterung in Graustufen dargestellt. Wenn Sie darauf klicken, wird das Kontextmenü geöffnet, anstatt die Aktion auszulösen.

Attribute

ShowPageAction

Seit Chrome 97 eingestellt

Verwenden Sie declarativeContent.ShowAction.

Eine deklarative Ereignisaktion, die die Seitenaktion der Erweiterung auf „Aktiviert“ setzt, wenn die entsprechenden Bedingungen erfüllt sind. Diese Aktion kann ohne Hostberechtigungen verwendet werden, die Erweiterung muss jedoch eine Seitenaktion haben. Wenn die Erweiterung die Berechtigung activeTab hat, wird durch Klicken auf die Seitenaktion Zugriff auf den aktiven Tab gewährt.

Auf Seiten, auf denen die Bedingungen nicht erfüllt sind, wird die Symbolleistenaktion der Erweiterung in Graustufen dargestellt. Wenn Sie darauf klicken, wird das Kontextmenü geöffnet, anstatt die Aktion auszulösen.

Attribute

Ereignisse

onPageChanged

Bietet die Declarative Event API mit addRules, removeRules und getRules.

Bedingungen

PageStateMatcher

Aktionen

RequestContentScript

SetIcon

ShowPageAction

ShowAction