Opis
Interfejs API chrome.contentSettings
umożliwia zmianę ustawień określających, czy strony mogą korzystać z takich funkcji jak pliki cookie, JavaScript czy wtyczki. Ogólnie rzecz biorąc, ustawienia treści umożliwiają dostosowanie działania Chrome w wybranych witrynach, a nie globalnie.
Uprawnienia
contentSettings
Aby używać interfejsu API, musisz zadeklarować uprawnienie "contentSettings"
w pliku manifestu rozszerzenia. Przykład:
{
"name": "My extension",
...
"permissions": [
"contentSettings"
],
...
}
Pojęcia i zastosowanie
Wzorce ustawień treści
Za pomocą wzorców możesz określać witryny, na które będą miały wpływ poszczególne ustawienia treści. Na przykład https://*.youtube.com/*
wskazuje domenę youtube.com i wszystkie jej subdomeny. Składnia wzorców ustawień treści jest taka sama jak w przypadku wzorców dopasowania z kilkoma różnicami:
- W przypadku adresów URL
http
,https
iftp
ścieżka musi być symbolem wieloznacznym (/*
). W przypadku adresów URLfile
ścieżka musi być całkowicie określona i nie może zawierać symboli wieloznacznych. - W przeciwieństwie do wzorców dopasowania wzorce ustawień treści mogą określać numer portu. Jeśli jest określony numer portu, wzorzec będzie pasował tylko do witryn z tym portem. Jeśli nie podasz żadnego numeru portu, wzorzec będzie pasować do wszystkich portów.
Pierwszeństwo wzorca
Jeśli do danej witryny ma zastosowanie więcej niż 1 reguła ustawienia treści, pierwszeństwo ma ta z bardziej szczegółowym wzorcem.
Na przykład te wzorce są uporządkowane od pierwszeństwa:
https://www.example.com/*
https://*.example.com/*
(dopasowanie example.com i wszystkich subdomen)<all_urls>
(pasujące do wszystkich adresów URL)
Występują 3 rodzaje symboli wieloznacznych, które wpływają na szczegółowość wzorca:
- Symbole wieloznaczne w porcie (np.
https://www.example.com:*/*
) - Symbole wieloznaczne w schemacie (np.
*://www.example.com:123/*
) - Symbole wieloznaczne w nazwie hosta (na przykład
https://*.example.com:123/*
)
Jeśli wzorzec jest bardziej szczegółowy od innego wzorca w jednej części, a mniej szczegółowy w innej, poszczególne części są sprawdzane w tej kolejności: nazwa hosta, schemat i port. Na przykład te wzorce są uporządkowane według pierwszeństwa:
https://www.example.com:*/*
Określa nazwę hosta i schemat.*:/www.example.com:123/*
Nie jest tak wysoka, ponieważ chociaż określa nazwę hosta, nie określa schematu.https://*.example.com:123/*
Niższa wartość, ponieważ chociaż określa port i schemat, w nazwie hosta występuje symbol wieloznaczny.
Wzorce podstawowe i dodatkowe
Adres URL, który jest brany pod uwagę przy wyborze ustawienia treści, zależy od typu treści.
Na przykład ustawienia contentSettings.notifications
zależą od adresu URL widocznego w omniboksie. Jest to tzw. „podstawowy” adres URL.
Niektóre rodzaje treści mogą uwzględniać dodatkowe adresy URL. Na przykład to, czy witryna może ustawić contentSettings.cookies
, jest określana na podstawie adresu URL żądania HTTP (w tym przypadku jest to podstawowy adres URL) oraz adresu URL wyświetlanego w omniboksie (tzw. „dodatkowego”).
Jeśli wiele reguł ma wzorce podstawowe i dodatkowe, pierwszeństwo ma reguła z bardziej szczegółowym wzorcem podstawowym. Jeśli wiele reguł ma ten sam wzorzec główny, pierwszeństwo ma reguła z bardziej szczegółowym wzorcem dodatkowym. Na przykład ta lista par podstawowych/dodatkowych wzorców jest uporządkowana według pierwszeństwa:
Pierwszeństwo | Wzór główny | Dodatkowy wzorzec |
---|---|---|
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> |
Identyfikatory zasobów
Identyfikatory zasobów umożliwiają określenie ustawień treści dla konkretnych podtypów typu treści.
Obecnie jedynym typem treści, który obsługuje identyfikatory zasobów, jest contentSettings.plugins
, gdzie identyfikator zasobu identyfikuje konkretną wtyczkę. Gdy stosujesz ustawienia treści, najpierw
sprawdzone są ustawienia konkretnej wtyczki. Jeśli nie można znaleźć ustawień dla konkretnej wtyczki, sprawdzane są ogólne ustawienia treści.
Jeśli na przykład reguła ustawienia treści ma identyfikator zasobu adobe-flash-player
i wzorzec <all_urls>
, ma ona pierwszeństwo przed regułą bez identyfikatora zasobu i wzorcem https://www.example.com/*
, nawet jeśli ten wzorzec jest bardziej szczegółowy.
Listę identyfikatorów zasobów danego typu treści możesz wyświetlić, wywołując metodę contentSettings.ContentSetting.getResourceIdentifiers()
. Zwrócona lista może się zmieniać w zależności od zestawu wtyczek zainstalowanych na komputerze użytkownika, ale Chrome stara się utrzymywać stabilne identyfikatory podczas aktualizacji wtyczek.
Przykłady
Aby go wypróbować, zainstaluj przykładowy interfejs ContentSettings API z repozytorium chrome-extension-samples.
Typy
AutoVerifyContentSetting
Enum
"block"
CameraContentSetting
Enum
"block"
"ask"
ClipboardContentSetting
Enum
"block"
"ask"
ContentSetting
Właściwości
-
wyczyść
void
ObietnicaWyczyść wszystkie reguły ustawień treści ustawione przez to rozszerzenie.
Funkcja
clear
wygląda tak:(details: object, callback?: function) => {...}
-
szczegóły
obiekt
-
zakres
Zakres opcjonalnie
Miejsce usunięcia ustawienia (domyślnie: zwykłe).
-
-
wywołanie zwrotne
funkcja opcjonalnie
Parametr
callback
wygląda tak:() => void
-
returns
Promise<void>
Chrome 96 i nowsze wersjeObietnice są obsługiwane w platformie Manifest V3 i nowszych, ale wywołania zwrotne są dostępne na potrzeby zgodności wstecznej. Nie można użyć obu w tym samym wywołaniu funkcji. Obietnica znika z tym samym typem, który jest przekazywany do wywołania zwrotnego.
-
-
get
void
ObietnicaPobiera bieżące ustawienie treści dla danej pary adresów URL.
Funkcja
get
wygląda tak:(details: object, callback?: function) => {...}
-
szczegóły
obiekt
-
incognito
wartość logiczna opcjonalna
Czy sprawdzać ustawienia treści w przypadku sesji incognito. (wartość domyślna to fałsz)
-
primaryUrl
string,
Podstawowy adres URL, dla którego należy pobrać ustawienie treści. Pamiętaj, że znaczenie podstawowego adresu URL zależy od typu treści.
-
resourceIdentifier
ResourceIdentifier opcjonalny
Bardziej szczegółowy identyfikator typu treści, dla których mają zostać pobrane ustawienia.
-
secondaryUrl
ciąg znaków opcjonalny
Dodatkowy adres URL, dla którego należy pobrać ustawienie treści. Domyślnie jest to główny adres URL. Pamiętaj, że znaczenie dodatkowego adresu URL zależy od typu treści i nie wszystkie rodzaje treści korzystają z dodatkowych adresów URL.
-
-
wywołanie zwrotne
funkcja opcjonalnie
Parametr
callback
wygląda tak:(details: object) => void
-
szczegóły
obiekt
-
Ustawianie
T
Ustawienie treści. Możliwe wartości znajdziesz w opisie poszczególnych obiektów ContentSetting.
-
-
-
returns
Promise<object>
Chrome 96 i nowsze wersjeObietnice są obsługiwane w platformie Manifest V3 i nowszych, ale wywołania zwrotne są dostępne na potrzeby zgodności wstecznej. Nie można użyć obu w tym samym wywołaniu funkcji. Obietnica znika z tym samym typem, który jest przekazywany do wywołania zwrotnego.
-
-
getResourceIdentifiers
void
ObietnicaFunkcja
getResourceIdentifiers
wygląda tak:(callback?: function) => {...}
-
wywołanie zwrotne
funkcja opcjonalnie
Parametr
callback
wygląda tak:(resourceIdentifiers?: ResourceIdentifier[]) => void
-
resourceIdentifiers
ResourceIdentifier[] opcjonalny
Lista identyfikatorów zasobów danego typu lub
undefined
, jeśli ten typ treści nie korzysta z identyfikatorów zasobów.
-
-
returns
Promise<ResourceIdentifier[]>
Chrome 96 i nowsze wersjeObietnice są obsługiwane w platformie Manifest V3 i nowszych, ale wywołania zwrotne są dostępne na potrzeby zgodności wstecznej. Nie można użyć obu w tym samym wywołaniu funkcji. Obietnica znika z tym samym typem, który jest przekazywany do wywołania zwrotnego.
-
-
Ustaw
void
ObietnicaStosuje nową regułę ustawienia treści.
Funkcja
set
wygląda tak:(details: object, callback?: function) => {...}
-
szczegóły
obiekt
-
primaryPattern
string,
Wzorzec podstawowego adresu URL. Szczegółowe informacje na temat formatu wzorców znajdziesz w sekcji Wzorce ustawień treści.
-
resourceIdentifier
ResourceIdentifier opcjonalny
Identyfikator zasobu dla typu treści.
-
zakres
Zakres opcjonalnie
Gdzie ustawić ustawienie (domyślnie: zwykłe).
-
secondaryPattern
ciąg znaków opcjonalny
Wzorzec dodatkowego adresu URL. Domyślnie dopasowuje się wszystkie adresy URL. Szczegółowe informacje na temat formatu wzorca znajdziesz w sekcji Wzorce ustawień treści.
-
Ustawianie
Dowolne
Ustawienie stosowane przez tę regułę. Możliwe wartości znajdziesz w opisie poszczególnych obiektów ContentSetting.
-
-
wywołanie zwrotne
funkcja opcjonalnie
Parametr
callback
wygląda tak:() => void
-
returns
Promise<void>
Chrome 96 i nowsze wersjeObietnice są obsługiwane w platformie Manifest V3 i nowszych, ale wywołania zwrotne są dostępne na potrzeby zgodności wstecznej. Nie można użyć obu w tym samym wywołaniu funkcji. Obietnica znika z tym samym typem, który jest przekazywany do wywołania zwrotnego.
-
CookiesContentSetting
Enum
"block"
"session_only"
FullscreenContentSetting
Wartość
ImagesContentSetting
Enum
"block"
JavascriptContentSetting
Enum
"block"
LocationContentSetting
Enum
"block"
"ask"
MicrophoneContentSetting
Enum
"block"
"ask"
MouselockContentSetting
Wartość
MultipleAutomaticDownloadsContentSetting
Enum
"block"
"ask"
NotificationsContentSetting
Enum
"block"
"ask"
PluginsContentSetting
Wartość
"block"
PopupsContentSetting
Enum
"block"
PpapiBrokerContentSetting
Wartość
"block"
ResourceIdentifier
Jedynym typem treści, który korzysta z identyfikatorów zasobów, jest contentSettings.plugins
. Więcej informacji znajdziesz w sekcji Identyfikatory zasobów (w języku angielskim).
Właściwości
-
opis
ciąg znaków opcjonalny
Zrozumiały dla człowieka opis zasobu.
-
id
string,
Identyfikator zasobu danego typu treści.
Scope
Zakres ContentSetting. Jedno z tych ustawień:
regular
: ustawienie profilu zwykłego (które jest dziedziczone przez profil incognito, jeśli nie zostanie zastąpione w innym miejscu),
incognito\_session\_only
: ustawienie profilu incognito, które można ustawić tylko podczas sesji incognito i jest usuwane po zakończeniu sesji incognito (zastępuje ustawienia standardowe).
Enum
"incognito_session_only"
Właściwości
automaticDownloads
Określa, czy zezwolić witrynom na automatyczne pobieranie wielu plików. Jedna z tych wartości: allow
: zezwalaj witrynom na automatyczne pobieranie kilku plików,
block
: nie zezwalaj witrynom na automatyczne pobieranie kilku plików,
ask
: pytaj, gdy witryna chce automatycznie pobierać pliki po pierwszym pliku.
Wartość domyślna to ask
.
Podstawowy adres URL to adres URL ramki najwyższego poziomu. Dodatkowy adres URL nie jest używany.
autoVerify
Określa, czy zezwalać witrynom na korzystanie z interfejsu Private State Tokens API. Jedna z tych wartości: allow
: zezwalaj witrynom na używanie interfejsu Private State Tokens API, block
: nie zezwalaj witrynom na korzystanie z interfejsu Private State Tokens API.
Wartość domyślna to allow
.
Podstawowy adres URL to adres URL ramki najwyższego poziomu. Dodatkowy adres URL nie jest używany. UWAGA: podczas wywoływania metody set()
wzór główny musi mieć postać .
camera
Określa, czy strony mają mieć dostęp do kamery. Jedna z tych wartości: allow
: zezwalaj stronom na dostęp do kamery,block
: nie zezwalaj stronom na dostęp do kamery,ask
: pytaj, gdy strona chce uzyskać dostęp do kamery.
Wartość domyślna to ask
.
Podstawowy adres URL to adres URL dokumentu, który zażądał dostępu do aparatu. Dodatkowy adres URL nie jest używany.
UWAGA: ustawienie zezwolenia nie jest prawidłowe, jeśli oba wzorce mają wartość „”.
clipboard
Określa, czy zezwolić witrynom na dostęp do schowka za pomocą zaawansowanych funkcji interfejsu Async Clipboard API. „Zaawansowane” funkcje obejmują wszystko poza pisaniem wbudowanych formatów po gestu użytkownika, czyli m.in. odczytywanie, zapisywanie w formatach niestandardowych i pisanie bez gestu użytkownika. Jedna z tych wartości: allow
: zezwalaj stronom na korzystanie z zaawansowanych funkcji schowka,
block
: nie zezwalaj stronom na korzystanie z zaawansowanych funkcji schowka,
ask
: pytaj, gdy strona chce używać zaawansowanych funkcji schowka.
Wartość domyślna to ask
.
Podstawowy adres URL to adres URL dokumentu, który poprosił o dostęp do schowka. Dodatkowy adres URL nie jest używany.
cookies
Określa, czy witryny mają zezwalać na zapisywanie plików cookie i innych danych lokalnych. Jedna z tych wartości: allow
: Akceptuj pliki cookie, block
: Blokuj pliki cookie,
session\_only
: akceptuj pliki cookie tylko z bieżącej sesji.
Wartość domyślna to allow
.
Podstawowy adres URL to adres, który reprezentuje pochodzenie pliku cookie. Dodatkowy adres URL to adres URL ramki najwyższego poziomu.
fullscreen
Wycofano. Nie ma już żadnego efektu. Dostęp do pełnego ekranu jest teraz automatycznie przyznawany wszystkim witrynom. Wartość to zawsze allow
.
images
Określa, czy wyświetlać obrazy. Jedna z tych wartości: allow
: Pokaż obrazy, block
: Nie pokazuj obrazów.
Wartość domyślna to allow
.
Podstawowy adres URL to adres URL ramki najwyższego poziomu. Dodatkowy adres URL to adres URL obrazu.
javascript
Określa, czy uruchamiać JavaScript. Jedna z tych wartości: allow
: uruchom JavaScript, block
: nie uruchamiaj JavaScriptu.
Wartość domyślna to allow
.
Podstawowy adres URL to adres URL ramki najwyższego poziomu. Dodatkowy adres URL nie jest używany.
location
Czy zezwolić na geolokalizację. Jedna z tych wartości: allow
: zezwalaj witrynom na śledzenie fizycznej lokalizacji,
block
: nie zezwalaj witrynom na śledzenie Twojej fizycznej lokalizacji,
ask
: pytaj, zanim zezwolisz stronom na śledzenie Twojej fizycznej lokalizacji.
Wartość domyślna to ask
.
Podstawowy adres URL to adres URL dokumentu, który zażądał danych o lokalizacji. Dodatkowy adres URL to adres URL ramki najwyższego poziomu (który może, ale nie musi się różnić od adresu URL, z którego pochodzi żądanie).
microphone
Określa, czy strony mają mieć dostęp do mikrofonu. Jedna z tych wartości: allow
: zezwalaj witrynom na dostęp do mikrofonu, block
: nie zezwalaj witrynom na dostęp do mikrofonu, ask
: pytaj, gdy strona chce uzyskać dostęp do mikrofonu.
Wartość domyślna to ask
.
Podstawowy adres URL to adres URL dokumentu, który poprosił o dostęp do mikrofonu. Dodatkowy adres URL nie jest używany.
UWAGA: ustawienie zezwolenia nie jest prawidłowe, jeśli oba wzorce mają wartość „”.
mouselock
Wycofano. Nie ma już żadnego efektu. Uprawnienia do blokowania myszy są teraz automatycznie przyznawane wszystkim witrynom. Wartość to zawsze allow
.
notifications
Czy zezwolić witrynom na wyświetlanie powiadomień na pulpicie. Jedna z tych wartości: allow
: zezwalaj witrynom na wyświetlanie powiadomień na pulpicie,
block
: nie zezwalaj witrynom na pokazywanie powiadomień na pulpicie,
ask
: pytaj, gdy witryna chce pokazywać powiadomienia na pulpicie.
Wartość domyślna to ask
.
Główny adres URL to adres URL dokumentu, w którym chce się wyświetlać powiadomienie. Dodatkowy adres URL nie jest używany.
plugins
Wycofano. To uprawnienie przestało działać, ponieważ obsługa Flasha została usunięta w Chrome 88. Wartość to zawsze block
. Połączenia z numerami set()
i clear()
będą ignorowane.
popups
Czy zezwolić witrynom na pokazywanie wyskakujących okienek. Jedna z tych wartości: allow
: zezwalaj na wyświetlanie wyskakujących okienek w witrynach, block
: nie zezwalaj na wyskakujące okienka w witrynach.
Wartość domyślna to block
.
Podstawowy adres URL to adres URL ramki najwyższego poziomu. Dodatkowy adres URL nie jest używany.
unsandboxedPlugins
Wycofano. Dotychczas można było określić, czy zezwolić witrynom na uruchamianie wtyczek poza piaskownicą. Jednak po usunięciu procesu brokera Flash w Chrome 88 to uprawnienie przestało działać. Wartość to zawsze block
. Połączenia z numerami set()
i clear()
będą ignorowane.