chrome.contentSettings

Opis

Interfejs API chrome.contentSettings umożliwia zmianę ustawień, które określają, czy strony mogą korzystać z takich funkcji jak pliki cookie, JavaScript i wtyczki. Ogólnie rzecz biorąc, ustawienia treści umożliwiają dostosowanie działania Chrome w poszczególnych witrynach, a nie globalnie.

Uprawnienia

contentSettings

Aby korzystać z interfejsu API, musisz zadeklarować uprawnienia "contentSettings" w pliku manifestu rozszerzenia. Przykład:

{
  "name": "My extension",
  ...
  "permissions": [
    "contentSettings"
  ],
  ...
}

Pojęcia i wykorzystanie

Wzorce ustawień treści

Przy użyciu wzorców możesz określać witryny, na które mają wpływ poszczególne ustawienia treści. Przykład: https://*.youtube.com/* określa domenę youtube.com i wszystkie jej subdomeny. Składnia treści wzorce ustawień są takie same 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 file adresów URL ścieżka musi być w pełni określony 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 port jeśli zostanie określony, wzorzec pasuje tylko do witryn z tym portem. Jeśli nie ma numeru portu wzorzec pasuje do wszystkich portów.

Pierwszeństwo wzorca

Jeśli do danej witryny ma zastosowanie więcej niż jedna reguła ustawienia treści, stosowana jest reguła z bardziej szczegółową ma pierwszeństwo.

Na przykład te wzorce są uporządkowane według pierwszeństwa:

  1. https://www.example.com/*
  2. https://*.example.com/* (zgodny z example.com i wszystkimi subdomenami)
  3. <all_urls> (dopasowanie do każdego adresu URL)

Na trafność wzorca wpływają 3 rodzaje symboli wieloznacznych:

  • Symbole wieloznaczne w porcie (np. https://www.example.com:*/*)
  • Symbole wieloznaczne w schemacie (np. *://www.example.com:123/*)
  • Symbole wieloznaczne w nazwie hosta (np. https://*.example.com:123/*).

Jeśli wzorzec jest w jednej części bardziej szczegółowy od innego, ale mniej dokładny w innej, poszczególne części są sprawdzane w tej kolejności: nazwa hosta, schemat, port. Na przykład parametr 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 tak wysoka, bo chociaż zawiera nazwę hosta, nie określa schematu.
  3. https://*.example.com:123/* Niższa, ponieważ chociaż określa port i schemat, ma w nazwie hosta symbol wieloznaczny.

Wzorce podstawowe i dodatkowe

Adres URL brany pod uwagę przy wyborze ustawienia treści zależy od typu treści. Na przykład ustawienia contentSettings.notifications są oparte na adresie URL wyświetlanym w tagu w omniboksie. Jest to tzw. „podstawowy” adres URL. Adres URL.

Niektóre typy treści mogą uwzględniać dodatkowe adresy URL. Na przykład czy witryna może parametr contentSettings.cookies jest określany na podstawie adresu URL żądania HTTP (który jest główny URL w tym przypadku) oraz adres URL wyświetlany w omniboksie (nazywany „dodatkowym” adres URL).

Jeśli wiele reguł ma wzorce główne i dodatkowe, reguła z bardziej szczegółową regułą główną ma pierwszeństwo. Jeśli wiele reguł ma ten sam wzorzec główny, reguła z atrybutem bardziej szczegółowy wzorzec dodatkowy ma pierwszeństwo. Na przykład ta lista Pary wzorców podstawowych i dodatkowych są uporządkowane według pierwszeństwa:

PierwszeństwoWzorzec głównyWzorzec dodatkowy
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 określonych 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ę. Przy stosowaniu ustawień treści najpierw ustawień wtyczki. Jeśli nie można znaleźć ustawień dotyczących określonego urządzenia wtyczki, sprawdzane są ogólne ustawienia treści dla wtyczek.

Jeśli na przykład reguła ustawień treści ma identyfikator zasobu adobe-flash-player oraz <all_urls>, ma pierwszeństwo przed regułą bez identyfikatora zasobu i wzorca https://www.example.com/*, nawet jeśli ten wzorzec jest bardziej szczegółowy.

Aby uzyskać listę identyfikatorów zasobów dla danego typu treści, wywołaj metodę contentSettings.ContentSetting.getResourceIdentifiers(). Zwrócona lista może się zmienić w: zestaw wtyczek zainstalowanych na komputerze użytkownika, ale Chrome stara się utrzymywać stabilność identyfikatorów przy aktualizacjach wtyczek.

Przykłady

Aby wypróbować ten interfejs API, zainstaluj przykładowy interfejs ContentSettings API ze strony chrome-extension-samples z repozytorium.

Typy

AutoVerifyContentSetting

Chrome w wersji 113 lub nowszej .

Typ wyliczeniowy

"allow"

"block"

CameraContentSetting

Chrome w wersji 46 lub nowszej, .

Typ wyliczeniowy

"allow"

"block"

"ask"

ClipboardContentSetting

Chrome w wersji 121 lub nowszej .

Typ wyliczeniowy

"allow"

"block"

"ask"

ContentSetting

Właściwości

  • wyczyść

    nieważne

    Obietnica .

    Wyczyść wszystkie reguły ustawień treści skonfigurowane przez to rozszerzenie.

    Funkcja clear wygląda tak: 

    (details: object, callback?: function) => {...}

    • szczegóły

      Obiekt

      • zakres

        Zakres opcjonalny

        Gdzie można wyczyścić ustawienie (domyślnie: zwykłe).

    • wywołanie zwrotne

      funkcja optional

      Parametr callback wygląda tak: 

      () => void

    • returns

      Obietnica<void>

      Chrome w wersji 96 lub nowszej, .

      Obietnice są obsługiwane w Manifest V3 i nowszych, ale wywołania zwrotne są podane w przypadku zgodność wsteczną. Nie można użyć obu w tym samym wywołaniu funkcji. Polecenie promowana jest realizowane z tym samym typem, który jest przekazywany do wywołania zwrotnego.

  • get

    nieważne

    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

        Określa, czy sprawdzić ustawienia treści dla sesji incognito. (domyślnie fałsz)

      • primaryUrl

        ciąg znaków

        Podstawowy adres URL, dla którego należy pobrać ustawienie treści. Pamiętaj, że znaczenie głównego adresu URL zależy od typu treści.

      • resourceIdentifier

        Opcjonalny ResourceIdentifier

        Bardziej szczegółowy identyfikator typu treści, dla którego należy pobrać 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 we wszystkich typach treści używa się dodatkowych adresów URL.

    • wywołanie zwrotne

      funkcja optional

      Parametr callback wygląda tak: 

      (details: object) => void

      • szczegóły

        Obiekt

        • ustawienie

          T

          Ustawienie treści. Możliwe wartości możesz znaleźć w opisie poszczególnych obiektów ContentSettings.

    • returns

      Promise&lt;object&gt;

      Chrome w wersji 96 lub nowszej, .

      Obietnice są obsługiwane w Manifest V3 i nowszych, ale wywołania zwrotne są podane w przypadku zgodność wsteczną. Nie można użyć obu w tym samym wywołaniu funkcji. Polecenie promowana jest realizowane z tym samym typem, który jest przekazywany do wywołania zwrotnego.

  • getResourceIdentifiers

    nieważne

    Obietnica .

    Funkcja getResourceIdentifiers wygląda tak: 

    (callback?: function) => {...}

    • wywołanie zwrotne

      funkcja optional

      Parametr callback wygląda tak: 

      (resourceIdentifiers?: ResourceIdentifier[]) => void

      • resourceIdentifiers

        ResourceIdentifier[] opcjonalny

        Lista identyfikatorów zasobów dla tego typu treści lub undefined, jeśli ten typ treści nie używa identyfikatorów zasobów.

    • returns

      Obietnica<ResourceIdentifier[]>

      Chrome w wersji 96 lub nowszej, .

      Obietnice są obsługiwane w Manifest V3 i nowszych, ale wywołania zwrotne są podane w przypadku zgodność wsteczną. Nie można użyć obu w tym samym wywołaniu funkcji. Polecenie promowana jest realizowane z tym samym typem, który jest przekazywany do wywołania zwrotnego.

  • zestaw

    nieważne

    Obietnica .

    Stosuje nową regułę ustawień treści.

    Funkcja set wygląda tak: 

    (details: object, callback?: function) => {...}

    • szczegóły

      Obiekt

      • primaryPattern

        ciąg znaków

        Wzorzec podstawowego adresu URL. Szczegółowe informacje na temat formatu wzorca znajdziesz w artykule Wzorce ustawień treści.

      • resourceIdentifier

        Opcjonalny ResourceIdentifier

        Identyfikator zasobu dla typu treści.

      • zakres

        Zakres opcjonalny

        Gdzie skonfigurować ustawienie (domyślnie: zwykłe).

      • secondaryPattern

        ciąg znaków opcjonalny

        Wzorzec dodatkowego adresu URL. Domyślnie dopasowywane są wszystkie adresy URL. Szczegółowe informacje na temat formatu wzorca znajdziesz w artykule Wzorce ustawień treści.

      • ustawienie

        każdy

        Ustawienie stosowane przez tę regułę. Możliwe wartości możesz znaleźć w opisie poszczególnych obiektów ContentSettings.

    • wywołanie zwrotne

      funkcja optional

      Parametr callback wygląda tak: 

      () => void

    • returns

      Obietnica<void>

      Chrome w wersji 96 lub nowszej, .

      Obietnice są obsługiwane w Manifest V3 i nowszych, ale wywołania zwrotne są podane w przypadku zgodność wsteczną. Nie można użyć obu w tym samym wywołaniu funkcji. Polecenie promowana jest realizowane z tym samym typem, który jest przekazywany do wywołania zwrotnego.

CookiesContentSetting

Chrome w wersji 44 lub nowszej .

Typ wyliczeniowy

"allow"

"block"

&quot;session_only&quot;

FullscreenContentSetting

Chrome w wersji 44 lub nowszej .

Wartość

"allow"

ImagesContentSetting

Chrome w wersji 44 lub nowszej .

Typ wyliczeniowy

"allow"

"block"

JavascriptContentSetting

Chrome w wersji 44 lub nowszej .

Typ wyliczeniowy

"allow"

"block"

LocationContentSetting

Chrome w wersji 44 lub nowszej .

Typ wyliczeniowy

"allow"

"block"

"ask"

MicrophoneContentSetting

Chrome w wersji 46 lub nowszej, .

Typ wyliczeniowy

"allow"

"block"

"ask"

MouselockContentSetting

Chrome w wersji 44 lub nowszej .

Wartość

"allow"

MultipleAutomaticDownloadsContentSetting

Chrome w wersji 44 lub nowszej .

Typ wyliczeniowy

"allow"

"block"

"ask"

NotificationsContentSetting

Chrome w wersji 44 lub nowszej .

Typ wyliczeniowy

"allow"

"block"

"ask"

PluginsContentSetting

Chrome w wersji 44 lub nowszej .

Wartość

"block"

PopupsContentSetting

Chrome w wersji 44 lub nowszej .

Typ wyliczeniowy

"allow"

"block"

PpapiBrokerContentSetting

Chrome w wersji 44 lub nowszej .

Wartość

"block"

ResourceIdentifier

Jedynym typem treści, który korzysta z identyfikatorów zasobów, jest contentSettings.plugins. Aby dowiedzieć się więcej, przeczytaj artykuł Identyfikatory zasobów.

Właściwości

  • opis

    ciąg znaków opcjonalny

    Zrozumiały dla człowieka opis zasobu.

  • id

    ciąg znaków

    Identyfikator zasobu danego typu treści.

Scope

Chrome w wersji 44 lub nowszej .

Zakres ustawienia ContentSetting. Jedna z tych wartości: regular: ustawienie zwykłego profilu (odziedziczone 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 standardowe ustawienia).

Typ wyliczeniowy

"standardowy"

"incognito_session_only"

Właściwości

automaticDownloads

Określa, czy witryny mogą automatycznie pobierać wiele plików. Jedna z tych wartości: allow: zezwalaj witrynom na automatyczne pobieranie wielu plików, block: nie zezwalaj witrynom na automatyczne pobieranie wielu plików, ask: zapytaj, gdy strona chce automatycznie pobierać pliki po pierwszym pliku. Wartość domyślna to ask. Podstawowy adres URL to adres ramki najwyższego poziomu. Dodatkowy adres URL nie jest używany.

Typ

ContentSetting&lt;MultipleAutomaticDownloadsContentSetting&gt;

autoVerify

Chrome w wersji 113 lub nowszej .

Określa, czy zezwolić witrynom na używanie 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 używanie interfejsu Private State Tokens API. Wartość domyślna to allow. Podstawowy adres URL to adres ramki najwyższego poziomu. Dodatkowy adres URL nie jest używany. UWAGA: w przypadku wywoływania funkcji set() podstawowym wzorcem musi być .

Typ

ContentSetting&lt;AutoVerifyContentSetting&gt;

camera

Chrome w wersji 46 lub nowszej, .

Określa, czy zezwolić witrynom na dostęp do kamery. Jedna z tych wartości: allow: zezwalaj stronom na dostęp do kamery, block: nie zezwalaj witrynom na dostęp do kamery, ask: pytaj, gdy strona chce korzystać z kamery. Wartość domyślna to ask. Podstawowy URL to adres dokumentu, którego dotyczy prośba o dostęp do aparatu. Dodatkowy adres URL nie jest używany. UWAGA: 'zezwalaj' Ustawienie nie jest prawidłowe, jeśli oba wzorce mają wartość „”.

Typ

ContentSetting&lt;CameraContentSetting&gt;

clipboard

Chrome w wersji 121 lub nowszej .

Określa, czy zezwolić witrynom na dostęp do schowka przy użyciu zaawansowanych funkcji interfejsu Async Clipboard API. „Zaawansowane” funkcje te obejmują wszystko oprócz pisania wbudowanych formatów po gestie użytkownika, w tym możliwość czytania, zapisu niestandardowego formatu i pisania bez użycia gestu użytkownika. Jedna z tych wartości: allow: zezwalaj witrynom na korzystanie z zaawansowanych funkcji schowka, block: nie zezwalaj witrynom na używanie zaawansowanych funkcji schowka, ask: zapytaj, gdy strona chce korzystać z zaawansowanych funkcji schowka. Wartość domyślna to ask. Podstawowy URL to adres URL dokumentu, który zażądał dostępu do schowka. Dodatkowy adres URL nie jest używany.

Typ

ContentSetting&lt;ClipboardContentSetting&gt;

cookies

Określa, czy zezwolić witrynom na tworzenie 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 w bieżącej sesji. Wartość domyślna to allow. Podstawowy adres URL to adres URL reprezentujący źródło pliku cookie. Dodatkowy adres URL to adres URL ramki najwyższego poziomu.

Typ

ContentSetting&lt;CookiesContentSetting&gt;

fullscreen

Wycofano. Nie ma już żadnych efektów. Uprawnienie pełnego ekranu jest teraz przyznawane automatycznie wszystkim witrynom. Wartość to zawsze allow.

Typ

ContentSetting&lt;FullscreenContentSetting&gt;

images

Określa, czy wyświetlać obrazy. Jedna z tych wartości: allow: pokazuj obrazy, block: nie wyświetlaj obrazów. Wartość domyślna to allow. Podstawowy adres URL to adres ramki najwyższego poziomu. Dodatkowy URL to adres URL obrazu.

Typ

ContentSetting&lt;ImagesContentSetting&gt;

javascript

Określa, czy wykonywać JavaScript. Jedna z tych wartości: allow: uruchom JavaScript, block: nie uruchamiaj JavaScriptu. Wartość domyślna to allow. Podstawowy adres URL to adres ramki najwyższego poziomu. Dodatkowy adres URL nie jest używany.

Typ

ContentSetting&lt;JavascriptContentSetting&gt;

location

Określa, czy zezwolić na geolokalizację. Jedna z tych wartości: allow: zezwalaj stronom na śledzenie mojej fizycznej lokalizacji block: nie zezwalaj witrynom na śledzenie fizycznej lokalizacji, ask: zapytaj, zanim zezwolisz stronom na śledzenie Twojej fizycznej lokalizacji. Wartość domyślna to ask. Podstawowy URL to URL dokumentu, z którego wysłano żądanie danych o lokalizacji. Dodatkowy adres URL to adres URL ramki najwyższego poziomu (która może, ale nie musi się różnić od adresu URL, z którego pochodzi żądanie).

Typ

ContentSetting&lt;LocationContentSetting&gt;

microphone

Chrome w wersji 46 lub nowszej, .

Określa, czy zezwolić witrynom na dostęp do mikrofonu. Jedna z tych wartości: allow: zezwalaj stronom 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 URL to URL dokumentu, który zażądał dostępu do mikrofonu. Dodatkowy adres URL nie jest używany. UWAGA: 'zezwalaj' Ustawienie nie jest prawidłowe, jeśli oba wzorce mają wartość „”.

Typ

ContentSetting&lt;MicrophoneContentSetting&gt;

mouselock

Wycofano. Nie ma już żadnych efektów. Uprawnienia do blokowania myszy są teraz automatycznie przyznawane wszystkim witrynom. Wartość to zawsze allow.

Typ

ContentSetting&lt;MouselockContentSetting&gt;

notifications

Określa, czy witryny mają wyświetlać powiadomienia na pulpicie. Jedna z tych wartości: allow: zezwalaj witrynom na wyświetlanie powiadomień na pulpicie block: nie zezwalaj witrynom na wyświetlanie powiadomień na pulpicie, ask: zapytaj, gdy witryna chce pokazywać powiadomienia na pulpicie. Wartość domyślna to ask. Podstawowy URL to adres dokumentu, w którym ma być wyświetlane powiadomienie. Dodatkowy adres URL nie jest używany.

Typ

ContentSetting&lt;NotificationsContentSetting&gt;

plugins

Wycofano. Po usunięciu obsługi Flasha w Chrome 88 to uprawnienie nie działa już. Wartość to zawsze block. Połączenia z numerami set() i clear() będą ignorowane.

Typ

ContentSetting&lt;PluginsContentSetting&gt;

popups

Określa, czy witryny mają wyświetlać wyskakujące okienka. Jedna z tych wartości: allow: zezwalaj witrynom na wyświetlanie wyskakujących okienek, block: nie zezwalaj witrynom na wyświetlanie wyskakujących okienek. Wartość domyślna to block. Podstawowy adres URL to adres ramki najwyższego poziomu. Dodatkowy adres URL nie jest używany.

Typ

ContentSetting&lt;PopupsContentSetting&gt;

unsandboxedPlugins

Wycofano. Wcześniej określało to, czy zezwalać witrynom na uruchamianie wtyczek poza piaskownicą. Jednak po usunięciu procesu brokera Flash w Chrome 88 to uprawnienie nie ma już żadnego efektu. Wartość to zawsze block. Połączenia z numerami set() i clear() będą ignorowane.

Typ

ContentSetting&lt;PpapiBrokerContentSetting&gt;