chrome.contentSettings

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 i ftp ścieżka musi być symbolem wieloznacznym (/*). W przypadku adresów URL file ś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:

  1. https://www.example.com/*
  2. https://*.example.com/* (dopasowanie example.com i wszystkich subdomen)
  3. <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:

  1. https://www.example.com:*/*Określa nazwę hosta i schemat.
  2. *:/www.example.com:123/* Nie jest tak wysoka, ponieważ chociaż określa nazwę hosta, nie określa schematu.
  3. 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ństwoWzór głównyDodatkowy wzorzec
1https://www.moose.com/*,https://www.wombat.com/*
2https://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

Chrome 113 i nowsze wersje

Enum

"block"

CameraContentSetting

Chrome 46 i nowsze wersje

Enum

"block"

"ask"

ClipboardContentSetting

Chrome 121 i nowsze wersje

Enum

"block"

"ask"

ContentSetting

Właściwości

  • wyczyść

    void

    Obietnica

    Wyczyść 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 wersje

      Obietnice 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

    Obietnica

    Pobiera 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 wersje

      Obietnice 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

    Obietnica

    Funkcja 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 wersje

      Obietnice 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

    Obietnica

    Stosuje 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 wersje

      Obietnice 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

Chrome 44 i nowsze wersje

Enum

"block"

"session_only"

FullscreenContentSetting

Chrome 44 i nowsze wersje

Wartość

ImagesContentSetting

Chrome 44 i nowsze wersje

Enum

"block"

JavascriptContentSetting

Chrome 44 i nowsze wersje

Enum

"block"

LocationContentSetting

Chrome 44 i nowsze wersje

Enum

"block"

"ask"

MicrophoneContentSetting

Chrome 46 i nowsze wersje

Enum

"block"

"ask"

MouselockContentSetting

Chrome 44 i nowsze wersje

Wartość

MultipleAutomaticDownloadsContentSetting

Chrome 44 i nowsze wersje

Enum

"block"

"ask"

NotificationsContentSetting

Chrome 44 i nowsze wersje

Enum

"block"

"ask"

PluginsContentSetting

Chrome 44 i nowsze wersje

Wartość

"block"

PopupsContentSetting

Chrome 44 i nowsze wersje

Enum

"block"

PpapiBrokerContentSetting

Chrome 44 i nowsze wersje

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

Chrome 44 i nowsze wersje

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.

Typ

ContentSetting<MultipleAutomaticDownloadsContentSetting>

autoVerify

Chrome 113 i nowsze wersje

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ć .

Typ

ContentSetting<AutoVerifyContentSetting>

camera

Chrome 46 i nowsze wersje

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ść „”.

Typ

ContentSetting<CameraContentSetting>

clipboard

Chrome 121 i nowsze wersje

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.

Typ

ContentSetting<ClipboardContentSetting>

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.

Typ

ContentSetting<CookiesContentSetting>

fullscreen

Wycofano. Nie ma już żadnego efektu. Dostęp do pełnego ekranu jest teraz automatycznie przyznawany wszystkim witrynom. Wartość to zawsze allow.

Typ

ContentSetting<FullscreenContentSetting>

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.

Typ

ContentSetting<ImagesContentSetting>

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.

Typ

ContentSetting<JavascriptContentSetting>

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).

Typ

ContentSetting<LocationContentSetting>

microphone

Chrome 46 i nowsze wersje

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ść „”.

Typ

ContentSetting<MicrophoneContentSetting>

mouselock

Wycofano. Nie ma już żadnego efektu. Uprawnienia do blokowania myszy są teraz automatycznie przyznawane wszystkim witrynom. Wartość to zawsze allow.

Typ

ContentSetting<MouselockContentSetting>

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.

Typ

ContentSetting<NotificationsContentSetting>

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.

Typ

ContentSetting<PluginsContentSetting>

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.

Typ

ContentSetting<PopupsContentSetting>

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.

Typ

ContentSetting<PpapiBrokerContentSetting>