Beschreibung
Mit der chrome.contentSettings
API können Sie Einstellungen ändern, mit denen festgelegt wird, ob Websites Funktionen wie Cookies, JavaScript und Plug-ins verwenden dürfen. Allgemein gesagt, können Sie mit Inhaltseinstellungen das Verhalten von Chrome für einzelne Websites und nicht global anpassen.
Berechtigungen
contentSettings
Du musst die Berechtigung „"contentSettings"
“ im Manifest deiner Erweiterung deklarieren, um die API nutzen zu können. Beispiel:
{
"name": "My extension",
...
"permissions": [
"contentSettings"
],
...
}
Konzepte und Nutzung
Muster für die Inhaltseinstellung
Mithilfe von Mustern können Sie die Websites angeben, auf die sich die jeweilige Inhaltseinstellung auswirkt. Beispiel: Durch https://*.youtube.com/*
werden youtube.com und alle zugehörigen Subdomains angegeben. Die Syntax für Inhaltseinstellungsmuster ist bis auf einige Unterschiede die gleiche wie für Übereinstimmungsmuster:
- Bei
http
-,https
- undftp
-URLs muss der Pfad ein Platzhalter (/*
) sein. Beifile
-URLs muss der Pfad vollständig angegeben werden und dürfen keine Platzhalter enthalten. - Im Gegensatz zu Abgleichsmustern kann in Inhaltseinstellungsmustern eine Portnummer angegeben werden. Wenn eine Portnummer angegeben ist, stimmt das Muster nur mit Websites mit diesem Port überein. Wenn keine Portnummer angegeben ist, gilt das Muster für alle Ports.
Rangfolge von Mustern
Wenn für eine bestimmte Website mehrere Regeln für die Inhaltseinstellung gelten, hat die Regel mit dem spezifischeren Muster Vorrang.
Die folgenden Muster sind beispielsweise nach Priorität sortiert:
https://www.example.com/*
https://*.example.com/*
(Übereinstimmung mit beispiel.de und allen Subdomains)<all_urls>
(Übereinstimmung mit jeder URL)
Drei Arten von Platzhaltern beeinflussen, wie spezifisch ein Muster ist:
- Platzhalter im Port (z. B.
https://www.example.com:*/*
) - Platzhalter im Schema (z. B.
*://www.example.com:123/*
) - Platzhalter im Hostnamen (z. B.
https://*.example.com:123/*
)
Wenn ein Muster in einem Teil spezifischer als ein anderes Muster, in einem anderen Teil jedoch weniger spezifisch ist, werden die verschiedenen Teile in der folgenden Reihenfolge geprüft: Hostname, Schema, Port. Die folgenden Muster sind beispielsweise nach Priorität sortiert:
https://www.example.com:*/*
Gibt den Hostnamen und das Schema an.*:/www.example.com:123/*
Nicht so hoch, weil damit zwar der Hostname, aber nicht das Schema angegeben wird.https://*.example.com:123/*
Niedriger, da damit zwar Port und Schema angegeben werden, der Hostname aber einen Platzhalter hat.
Primäre und sekundäre Muster
Welche URL bei der Entscheidung, welche Inhaltseinstellung angewendet wird, berücksichtigt wird, hängt vom Inhaltstyp ab.
Die Einstellungen für contentSettings.notifications
basieren beispielsweise auf der URL, die in der Omnibox angezeigt wird. Diese URL wird als „primäre“ URL bezeichnet.
Bei einigen Inhaltstypen können zusätzliche URLs berücksichtigt werden. Ob eine Website beispielsweise eine contentSettings.cookies
festlegen darf, wird anhand der URL der HTTP-Anfrage (in diesem Fall die primäre URL) sowie der in der Omnibox angezeigten URL (die „sekundäre“ URL) bestimmt.
Wenn mehrere Regeln primäre und sekundäre Muster haben, hat die Regel mit dem spezifischeren primären Muster Vorrang. Wenn es mehrere Regeln mit demselben primären Muster gibt, hat die Regel mit dem spezifischeren sekundären Muster Vorrang. Die folgende Liste mit primären/sekundären Musterpaaren ist beispielsweise nach Priorität sortiert:
Vorrang | Primäres Muster | Sekundäres Muster |
---|---|---|
1 | https://www.moose.com/* , | https://www.wombat.com/* |
2 | https://www.moose.com/* , | <all_urls> |
3 | <all_urls> , | https://www.wombat.com/* |
4 | <all_urls> , | <all_urls> |
Ressourcen-IDs
Mit Ressourcenkennungen können Sie Inhaltseinstellungen für bestimmte Untertypen eines Inhaltstyps angeben.
Derzeit ist contentSettings.plugins
der einzige Inhaltstyp, der Ressourcen-IDs unterstützt. Dabei identifiziert eine Ressourcen-ID ein bestimmtes Plug-in. Wenn Sie Inhaltseinstellungen anwenden, werden zuerst die Einstellungen für das jeweilige Plug-in überprüft. Wenn für ein bestimmtes Plug-in keine Einstellungen gefunden werden, werden die allgemeinen Inhaltseinstellungen für Plug-ins überprüft.
Wenn eine Regel zur Inhaltseinstellung beispielsweise die Ressourcenkennung adobe-flash-player
und das Muster <all_urls>
hat, hat sie Vorrang vor einer Regel ohne Ressourcenkennung und dem Muster https://www.example.com/*
, auch wenn dieses Muster spezifischer ist.
Durch Aufrufen der Methode contentSettings.ContentSetting.getResourceIdentifiers()
können Sie eine Liste der Ressourcenkennungen für einen Inhaltstyp abrufen. Die zurückgegebene Liste kann sich mit den auf dem Computer des Nutzers installierten Plug-ins ändern. Chrome versucht jedoch, die IDs über Plug-in-Updates hinweg stabil zu halten.
Beispiele
Wenn Sie diese API testen möchten, installieren Sie das contentSettings API-Beispiel aus dem Repository chrome-extension-sample.
Typen
AutoVerifyContentSetting
Enum
CameraContentSetting
Enum
ClipboardContentSetting
Enum
ContentSetting
Attribute
-
löschen
void
VersprechenAlle von dieser Erweiterung festgelegten Regeln für Inhaltseinstellungen löschen.
Die Funktion
clear
sieht so aus:(details: object, callback?: function) => {...}
-
Details
Objekt
-
Bereich
Umfang optional
Gibt an, wo die Einstellung gelöscht werden soll (Standardeinstellung: regulär).
-
-
callback
Funktion optional
Der Parameter
callback
sieht so aus:() => void
-
Gibt zurück
Promise<void>
Chrome 96 oder höherPromise-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.
-
-
get
void
VersprechenRuft die aktuelle Inhaltseinstellung für ein bestimmtes URL-Paar ab.
Die Funktion
get
sieht so aus:(details: object, callback?: function) => {...}
-
Details
Objekt
-
inkognito
Boolescher Wert optional
Gibt an, ob die Inhaltseinstellungen für eine Inkognitositzung geprüft werden sollen. (Standardeinstellung „false“)
-
primaryUrl
String
Die primäre URL, für die die Inhaltseinstellung abgerufen werden soll. Hinweis: Die Bedeutung einer primären URL hängt vom Inhaltstyp ab.
-
resourceIdentifier
ResourceIdentifier optional
Eine genauere Kennung für den Inhaltstyp, für den die Einstellungen abgerufen werden sollen.
-
secondaryUrl
String optional
Die sekundäre URL, für die die Inhaltseinstellung abgerufen werden soll. Die Standardeinstellung ist die primäre URL. Beachten Sie, dass die Bedeutung einer sekundären URL vom Inhaltstyp abhängt. Nicht für alle Inhaltstypen werden sekundäre URLs verwendet.
-
-
callback
Funktion optional
Der Parameter
callback
sieht so aus:(details: object) => void
-
Details
Objekt
-
Einstellung
T
Die Inhaltseinstellung. Die möglichen Werte finden Sie in der Beschreibung der einzelnen ContentSetting-Objekte.
-
-
-
Gibt zurück
Promise<object>
Chrome 96 oder höherPromise-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.
-
-
getResourceIdentifiers
void
VersprechenDie Funktion
getResourceIdentifiers
sieht so aus:(callback?: function) => {...}
-
callback
Funktion optional
Der Parameter
callback
sieht so aus:(resourceIdentifiers?: ResourceIdentifier[]) => void
-
resourceIdentifiers
ResourceIdentifier[] optional
Eine Liste von Ressourcenkennungen für diesen Inhaltstyp oder
undefined
, wenn dieser Inhaltstyp keine Ressourcenkennungen verwendet.
-
-
Gibt zurück
Promise<ResourceIdentifier[]>
Chrome 96 oder höherPromise-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.
-
-
set
void
VersprechenWendet eine neue Regel für die Inhaltseinstellung an.
Die Funktion
set
sieht so aus:(details: object, callback?: function) => {...}
-
Details
Objekt
-
primaryPattern
String
Das Muster für die primäre URL. Weitere Informationen zum Format eines Musters finden Sie unter Inhaltseinstellungsmuster.
-
resourceIdentifier
ResourceIdentifier optional
Die Ressourcen-ID für den Inhaltstyp.
-
Bereich
Umfang optional
Hier wird die Einstellung festgelegt (Standard: regulär).
-
secondaryPattern
String optional
Das Muster für die sekundäre URL. Entspricht standardmäßig allen URLs. Weitere Informationen zum Format eines Musters finden Sie unter Muster für die Inhaltseinstellung.
-
Einstellung
Beliebig
Die von dieser Regel angewendete Einstellung. Die möglichen Werte finden Sie in der Beschreibung der einzelnen ContentSetting-Objekte.
-
-
callback
Funktion optional
Der Parameter
callback
sieht so aus:() => void
-
Gibt zurück
Promise<void>
Chrome 96 oder höherPromise-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.
-
CookiesContentSetting
Enum
"session_only"
FullscreenContentSetting
Wert
ImagesContentSetting
Enum
JavascriptContentSetting
Enum
LocationContentSetting
Enum
MicrophoneContentSetting
Enum
MouselockContentSetting
Wert
MultipleAutomaticDownloadsContentSetting
Enum
NotificationsContentSetting
Enum
PluginsContentSetting
Wert
PopupsContentSetting
Enum
PpapiBrokerContentSetting
Wert
ResourceIdentifier
Der einzige Inhaltstyp, der Ressourcenkennungen verwendet, ist contentSettings.plugins
. Weitere Informationen finden Sie unter Ressourcenkennzeichnungen.
Attribute
-
Beschreibung
String optional
Eine menschenlesbare Beschreibung der Ressource.
-
id
String
Die Ressourcen-ID für den angegebenen Inhaltstyp.
Scope
Der Umfang von ContentSetting. Eine der regular
: Einstellung für ein reguläres Profil, die vom Inkognitoprofil übernommen wird, wenn sie nicht an anderer Stelle überschrieben wird.
incognito\_session\_only
: Einstellung für das Inkognitoprofil, die nur während einer Inkognitositzung festgelegt werden kann und gelöscht wird, wenn die Inkognitositzung endet (überschreibt die normalen Einstellungen).
Enum
"regular"
Attribute
automaticDownloads
Gibt an, ob Websites mehrere Dateien automatisch herunterladen dürfen. Eine der folgenden Optionen:
allow
: Websites dürfen automatisch mehrere Dateien herunterladen,
block
: Websites dürfen nicht automatisch mehrere Dateien herunterladen,
ask
: Websites fragen, wenn eine Website Dateien nach der ersten Datei automatisch herunterladen möchte.
Der Standardwert ist ask
.
Die primäre URL ist die URL des Frames auf oberster Ebene. Die sekundäre URL wird nicht verwendet.
autoVerify
Gibt an, ob Websites die Private State Tokens API verwenden dürfen. Eine der allow
: Websites die Verwendung der Private State Tokens API erlauben,
block
: Websites daran hindern, die Private State Tokens API zu verwenden.
Der Standardwert ist allow
.
Die primäre URL ist die URL des Frames auf oberster Ebene. Die sekundäre URL wird nicht verwendet. HINWEIS: Beim Aufrufen von set()
muss das primäre Muster .
camera
Gibt an, ob Websites auf die Kamera zugreifen dürfen. Eine der folgenden Optionen:
allow
: Websites erlauben, auf die Kamera zuzugreifen,
block
: Websites nicht erlauben, auf die Kamera zuzugreifen,
ask
: Websites fragen, wenn eine Website auf die Kamera zugreifen möchte.
Der Standardwert ist ask
.
Die primäre URL ist die URL des Dokuments, für das der Kamerazugriff angefordert wurde. Die sekundäre URL wird nicht verwendet.
HINWEIS: Die Einstellung „allow“ ist ungültig, wenn beide Muster auf „'“ festgelegt sind.
clipboard
Gibt an, ob Websites über erweiterte Funktionen der Async Clipboard API auf die Zwischenablage zugreifen dürfen. „Erweiterte“ Funktionen umfassen alles, was über das Schreiben von integrierten Formaten nach einer Nutzergeste hinaus möglich ist, d.h. die Fähigkeit, zu lesen, benutzerdefinierte Formate zu schreiben und ohne Nutzergeste zu schreiben. Eine der folgenden Optionen:
allow
: Websites dürfen erweiterte Funktionen der Zwischenablage verwenden,
block
: Websites dürfen keine erweiterten Funktionen der Zwischenablage verwenden,
ask
: Websites fragen, wenn sie erweiterte Funktionen für die Zwischenablage verwenden möchten.
Der Standardwert ist ask
.
Die primäre URL ist die URL des Dokuments, das den Zugriff auf die Zwischenablage angefordert hat. Die sekundäre URL wird nicht verwendet.
cookies
Gibt an, ob Cookies und andere lokale Daten von Websites gesetzt werden dürfen. Eine der folgenden Optionen:
allow
: Cookies akzeptieren,
block
: Cookies blockieren,
session\_only
: Cookies nur für die aktuelle Sitzung akzeptieren.
Der Standardwert ist allow
.
Die primäre URL ist die URL, die den Cookie-Ursprung darstellt. Die sekundäre URL ist die URL des Frames auf oberster Ebene.
fullscreen
Veraltet. Hat keine Auswirkungen mehr. Die Berechtigung für den Vollbildmodus wird jetzt automatisch für alle Websites gewährt. Der Wert ist immer allow
.
images
Gibt an, ob Bilder angezeigt werden sollen. Eines der folgenden Elemente:
allow
: Bilder anzeigen,
block
: keine Bilder anzeigen.
Der Standardwert ist allow
.
Die primäre URL ist die URL des Frames auf oberster Ebene. Die sekundäre URL ist die URL des Bildes.
javascript
Gibt an, ob JavaScript ausgeführt werden soll. Eine der folgenden Optionen: allow
: JavaScript ausführen, block
: JavaScript nicht ausführen.
Der Standardwert ist allow
.
Die primäre URL ist die URL des Frames auf oberster Ebene. Die sekundäre URL wird nicht verwendet.
location
Gibt an, ob die Standortbestimmung zugelassen wird. Eine der folgenden Optionen:
allow
: Websites dürfen meinen physischen Standort abrufen,
block
: Websites nicht erlauben, meinen physischen Standort zu erfassen,
ask
: Websites fragen, bevor sie meinen physischen Standort abrufen dürfen.
Der Standardwert ist ask
.
Die primäre URL ist die URL des Dokuments, über das Standortdaten angefordert wurden. Die sekundäre URL ist die URL des Frames auf oberster Ebene. Sie kann sich von der anfragenden URL unterscheiden.
microphone
Gibt an, ob Websites auf das Mikrofon zugreifen dürfen. Eine der folgenden Optionen:
allow
: Websites den Zugriff auf das Mikrofon erlauben,
block
: Websites dürfen nicht auf das Mikrofon zugreifen,
ask
: Websites fragen, wenn eine Website auf das Mikrofon zugreifen möchte.
Der Standardwert ist ask
.
Die primäre URL ist die URL des Dokuments, das den Mikrofonzugriff angefordert hat. Die sekundäre URL wird nicht verwendet.
HINWEIS: Die Einstellung „allow“ ist ungültig, wenn beide Muster auf „'“ festgelegt sind.
mouselock
Veraltet. Hat keine Auswirkungen mehr. Die Berechtigung für die Maussperre wird jetzt automatisch für alle Websites gewährt. Der Wert ist immer allow
.
notifications
Gibt an, ob Websites Desktop-Benachrichtigungen anzeigen dürfen. Eine der folgenden Optionen:
allow
: Anzeige von Desktop-Benachrichtigungen auf Websites zulassen,
block
: Anzeigen von Desktop-Benachrichtigungen nicht zulassen,
ask
: Nachfragen, wenn eine Website Desktop-Benachrichtigungen anzeigen möchte.
Der Standardwert ist ask
.
Die primäre URL ist die URL des Dokuments, in dem die Benachrichtigung angezeigt werden soll. Die sekundäre URL wird nicht verwendet.
plugins
Veraltet. Nachdem in Chrome 88 die Flash-Unterstützung entfernt wurde, hat diese Berechtigung keine Auswirkungen mehr. Der Wert ist immer block
. Aufrufe an set()
und clear()
werden ignoriert.
popups
Gibt an, ob Websites Pop-ups anzeigen dürfen. Eine der folgenden Optionen:
allow
: Websites dürfen Pop-ups anzeigen,
block
: Websites dürfen keine Pop-ups anzeigen.
Der Standardwert ist block
.
Die primäre URL ist die URL des Frames auf oberster Ebene. Die sekundäre URL wird nicht verwendet.
unsandboxedPlugins
Veraltet. Bisher wurde gesteuert, ob Websites Plug-ins ohne Sandbox ausführen dürfen. Da der Flash Broker-Prozess in Chrome 88 jedoch entfernt wurde, hat diese Berechtigung keine Auswirkungen mehr. Der Wert ist immer block
. Aufrufe an set()
und clear()
werden ignoriert.