Beschreibung
Mit der chrome.declarativeContent
API können Sie Aktionen abhängig vom Inhalt einer Seite ausführen, ohne dass Sie eine Berechtigung zum Lesen des Seiteninhalts benötigen.
Berechtigungen
declarativeContent
Nutzung
Mit der Declarative Content API können Sie die Aktion Ihrer Erweiterung abhängig von der URL einer Webseite aktivieren oder wenn ein CSS-Selektor mit einem Element auf der Seite übereinstimmt, ohne Hostberechtigungen hinzufügen oder ein Inhaltsskript einfügen zu müssen.
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
-Objekt stimmt nur dann mit Webseiten überein, wenn alle aufgeführten Kriterien erfüllt sind. Sie kann einer Seiten-URL, einem zusammengesetzten CSS-Selektor oder dem Lesezeichenstatus einer Seite entsprechen. Die folgende Regel aktiviert die Aktion der Erweiterung auf Google-Seiten, 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() ]
};
Das Ereignis onPageChanged
prüft, ob eine Regel mindestens eine erfüllte Bedingung hat, und führt die Aktionen aus. Die Regeln bleiben über mehrere Browsersitzungen hinweg bestehen. Daher sollten Sie während der Installation von Erweiterungen zuerst removeRules
verwenden, um zuvor installierte Regeln zu löschen, und dann addRules
verwenden, um neue Regeln zu registrieren.
chrome.runtime.onInstalled.addListener(function(details) {
chrome.declarativeContent.onPageChanged.removeRules(undefined, function() {
chrome.declarativeContent.onPageChanged.addRules([rule2]);
});
});
Mit der Berechtigung activeTab zeigt Ihre Erweiterung keine Berechtigungswarnungen an. Wenn der Nutzer auf die Erweiterungsaktion klickt, wird sie nur auf relevanten Seiten ausgeführt.
Seiten-URL-Abgleich
Wenn die URL-Kriterien erfüllt sind, wird als Ergebnis PageStateMatcher.pageurl
zurückgegeben. Die häufigsten Kriterien sind eine Verkettung von Host, Pfad oder URL gefolgt von „Enthält“, „Ist gleich“, „Präfix“ oder „Suffix“. Die folgende Tabelle enthält einige Beispiele:
Kriterien | Übereinstimmungen |
---|---|
{ hostSuffix: 'google.com' } |
Alle Google-URLs |
{ pathPrefix: '/docs/extensions' } |
Erweiterungsdokumentations-URLs |
{ urlContains: 'developer.chrome.com' } |
Alle URLs der Chrome-Entwicklerdokumentation |
Bei allen Kriterien wird zwischen Groß- und Kleinschreibung unterschieden. Eine vollständige Liste der Kriterien finden Sie unter UrlFilter.
CSS-Abgleich
PageStateMatcher.css
-Bedingungen müssen zusammengesetzte Selektoren sein, d. h., Sie können keine Kombinatoren wie Leerzeichen oder „>
“ in Ihre Selektoren aufnehmen. So kann Chrome die Auswahl noch effizienter finden.
Zusammengesetzte Selektoren (OK) | Komplexe Selektoren (nicht zulässig) |
---|---|
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
oder eines der übergeordneten Elemente display:none
ist, führt dies nicht dazu, dass die Bedingung übereinstimmt. Durch Elemente mit visibility:hidden
-Formatierung, außerhalb des sichtbaren oder von anderen Elementen ausgeblendeten Elementen kann die Bedingung trotzdem erfüllt werden.
Abgleichsstatus als Lesezeichen
Die Bedingung PageStateMatcher.isBookmarked
ermöglicht den Abgleich des Lesezeichenstatus der aktuellen URL im Profil des Nutzers. Damit diese Bedingung genutzt 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
Gleicht den Status einer Webseite anhand verschiedener Kriterien ab.
Attribute
-
Konstruktor
void
Die Funktion
constructor
sieht so aus:(arg: PageStateMatcher) => {...}
-
Argument
-
Gibt zurück
-
-
css
string[] optional
Stimmt überein, wenn alle CSS-Selektoren im Array mit den angezeigten Elementen in einem Frame übereinstimmen, der denselben Ursprung wie der Hauptframe der Seite hat. Alle Selektoren in diesem Array müssen zusammengesetzte Selektoren sein, um den Abgleich zu beschleunigen Hinweis: Das Auflisten von Hunderten von CSS-Selektoren oder das Auflisten von CSS-Selektoren, die hunderte Male pro Seite übereinstimmen, kann Websites verlangsamen.
-
isBookmarked
Boolescher Wert optional
Chrome 45 und höherStimmt überein, wenn der Status der Seite als Lesezeichen dem angegebenen Wert entspricht. Hierfür ist die Berechtigung für Lesezeichen erforderlich.
-
pageUrl
UrlFilter optional
Stimmt überein, wenn die Bedingungen von
UrlFilter
für die Top-Level-URL der Seite erfüllt sind.
RequestContentScript
Deklarative Ereignisaktion, durch die ein Inhaltsskript eingeschleust wird.
WARNUNG: Diese Aktion befindet sich noch in der Testphase und wird in stabilen Chrome-Builds nicht unterstützt.
Attribute
-
Konstruktor
void
Die Funktion
constructor
sieht so aus:(arg: RequestContentScript) => {...}
-
Argument
-
Gibt zurück
-
-
allFrames
Boolescher Wert optional
Gibt an, ob das Inhaltsskript in allen Frames der übereinstimmenden Seite oder nur im obersten Frame ausgeführt wird. Standardwert ist
false
. -
css
string[] optional
Namen von CSS-Dateien, die als Teil des Inhaltsskripts eingeschleust werden sollen.
-
js
string[] optional
Namen von JavaScript-Dateien, die als Teil des Inhaltsskripts eingeschleust werden sollen.
-
matchAboutBlank
Boolescher Wert optional
Gibt an, ob das Inhaltsskript auf
about:blank
undabout:srcdoc
eingefügt werden soll. Der Standardwert istfalse
.
SetIcon
Deklarative Ereignisaktion, mit der das quadratische Symbol „n-dip“ für die Seitenaktion oder Browseraktion der Erweiterung festgelegt wird, während die entsprechenden Bedingungen erfüllt sind. Diese Aktion kann ohne Hostberechtigungen verwendet werden, aber die Erweiterung muss eine Seiten- oder Browseraktion haben.
Es muss genau entweder imageData
oder path
angegeben werden. Beide sind Wörterbücher, die einer Bilddarstellung eine bestimmte Anzahl von Pixeln 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 im Verhältnis zum Manifest der Erweiterung ist. Wenn scale
-Bildschirmpixel in ein geräteunabhängiges Pixel passen, wird das Symbol scale * n
verwendet. Fehlt diese Skala, wird ein anderes Bild auf die erforderliche Größe angepasst.
Attribute
-
Konstruktor
void
Die Funktion
constructor
sieht so aus:(arg: SetIcon) => {...}
-
Argument
-
Gibt zurück
-
-
imageData
ImageData | Objekt optional
Entweder ein
ImageData
-Objekt oder ein Wörterbuch {size -> ImageData}, das ein festzulegendes Symbol darstellt. Wenn das Symbol als Wörterbuch angegeben ist, wird das verwendete Bild abhängig von der Pixeldichte des Bildschirms ausgewählt. Wenn die Anzahl der Bildpixel, die in eine Bildschirmbereichseinheit passen,scale
ist, wird ein Bild mit der Größescale * n
ausgewählt, wobei n die Größe des Symbols auf der Benutzeroberfläche ist. Es muss mindestens ein Bild angegeben werden.details.imageData = foo
entsprichtdetails.imageData = {'16': foo}
.
ShowAction
Eine deklarative Ereignisaktion, die die action der Symbolleiste der Erweiterung auf den Status „Aktiviert“ setzt, während 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 angezeigt. Wenn Sie darauf klicken, wird das Kontextmenü geöffnet, anstatt die Aktion auszulösen.
Attribute
-
Konstruktor
void
Die Funktion
constructor
sieht so aus:(arg: ShowAction) => {...}
-
Argument
-
Gibt zurück
-
ShowPageAction
Verwenden Sie declarativeContent.ShowAction
.
Eine deklarative Ereignisaktion, durch die die Seitenaktion der Erweiterung auf den Status „Aktiviert“ gesetzt wird, während die entsprechenden Bedingungen erfüllt sind. Diese Aktion kann ohne Hostberechtigungen verwendet werden, aber die Erweiterung muss 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 angezeigt. Wenn Sie darauf klicken, wird das Kontextmenü geöffnet, anstatt die Aktion auszulösen.
Attribute
-
Konstruktor
void
Die Funktion
constructor
sieht so aus:(arg: ShowPageAction) => {...}
-
Argument
-
Gibt zurück
-
Veranstaltungen
onPageChanged
Stellt die deklarative Event API bereit, die aus addRules
, removeRules
und getRules
besteht.