chrome.contentSettings

Opis

Użyj interfejsu API chrome.contentSettings, aby zmienić ustawienia, które kontrolują, czy witryny 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ć uprawnienie "contentSettings" w pliku manifestu rozszerzenia. Przykład:

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

Pojęcia i zastosowanie

Wzorce ustawień treści

Za pomocą wzorów możesz określić, na które witryny mają wpływ poszczególne ustawienia treści. Na przykład: https://*.youtube.com/* określa youtube.com i wszystkie jego subdomeny. Składnia wzorca 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 odróżnieniu od wzorców dopasowania wzorce ustawień treści mogą określać numer portu. Jeśli podany jest numer portu, wzorzec pasuje tylko do witryn z tym portem. Jeśli nie podasz numeru portu, wzór będzie pasował do wszystkich portów.

Wzór priorytetów

Jeśli do danej witryny ma zastosowanie więcej niż 1 reguła ustawień treści, pierwszeństwo ma reguła z bardziej szczegółowym wzorcem.

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

  1. https://www.example.com/*
  2. https://*.example.com/* (dopasowuje do example.com i wszystkich subdomen)
  3. <all_urls> (pasuje do każdego adresu URL)

Trzy rodzaje symboli wieloznacznych wpływają na to, jak szczegółowy jest wzór:

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

Jeśli wzór jest bardziej szczegółowy niż inny wzór w jednym fragmencie, ale mniej szczegółowy w innym, różne części są sprawdzane w tej kolejności: nazwa hosta, schemat, 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 to tak wysokie ryzyko, ponieważ chociaż podano nazwę hosta, nie podano schematu.
  3. https://*.example.com:123/* Niższa, ponieważ chociaż zawiera port i schemat, w nazwie hosta ma symbol wieloznaczny.

wzory podstawowe i dodatkowe,

Adres URL brany pod uwagę przy podejmowaniu decyzji o tym, które ustawienie treści zastosować, zależy od typu treści. Na przykład w przypadku contentSettings.notifications ustawienia są określane na podstawie adresu URL wyświetlanego w pasku wielofunkcyjnym. Ten adres URL nazywa się „głównym”.

Niektóre typy treści mogą uwzględniać dodatkowe adresy URL. Na przykład to, czy witryna może ustawić contentSettings.cookies, zależy od adresu URL żądania HTTP (który jest w tym przypadku adresem URL głównym) oraz adresu URL wyświetlanego w omniboksie (zwanym „adresem URL pomocniczym”).

Jeśli wiele reguł ma wzorce podstawowe i dodatkowe, pierwszeństwo ma reguła z bardziej szczegółowym wzorcem podstawowym. Jeśli kilka reguł ma ten sam wzór główny, pierwszeństwo ma reguła z bardziej szczegółowym wzorem dodatkowym. Na przykład ta lista par wzorów podstawowych i wtórnych jest uporządkowana 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>

W przypadku ustawienia zawartości obrazów nie są obsługiwane wzory dodatkowe.

Identyfikatory zasobów

Identyfikatory zasobów umożliwiają określenie ustawień treści dla konkretnych podtypów danego typu treści. Obecnie jedynym typem treści, który obsługuje identyfikatory zasobów, jest contentSettings.plugins, gdzie identyfikator zasobu identyfikuje konkretny wtyczkę. Podczas stosowania ustawień treści najpierw sprawdzane są ustawienia konkretnego wtyczka. Jeśli nie znaleziono ustawień konkretnej wtyczki, sprawdzane są ogólne ustawienia treści dotyczące wtyczek.

Jeśli na przykład reguła ustawień treści ma identyfikator zasobu adobe-flash-player i wzorzec <all_urls>, ma pierwszeństwo nad 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ę zmieniać w zależności od zestawu zainstalowanych wtyczek na komputerze użytkownika, ale Chrome stara się zachować stabilność identyfikatorów podczas aktualizacji wtyczek.

Przykłady

Aby wypróbować ten interfejs API, zainstaluj przykład contentSettings API z repozytorium chrome-extension-samples.

Typy

AutoVerifyContentSetting

Chrome 113 lub nowszy

Typ wyliczeniowy

"allow"

"block"

CameraContentSetting

Chrome 46 lub nowszy

Typ wyliczeniowy

"allow"

"block"

"ask"

ClipboardContentSetting

Chrome 121 lub nowszy

Typ wyliczeniowy

"allow"

"block"

"ask"

ContentSetting

Właściwości

  • wyczyść

    nieważne

    Obietnice

    Wyczyść wszystkie ustawienia reguł dotyczące treści ustawione przez to rozszerzenie.

    Funkcja clear ma postać:

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

    • szczegóły

      Obiekt

      • zakres

        Zakres opcjonalnie

        Gdzie można usunąć ustawienie (domyślnie: regularnie).

    • wywołanie zwrotne

      function opcjonalny

      Parametr callback ma postać:

      () => void

    • returns

      Obietnica<void>

      Chrome 96+

      Obietnice są obsługiwane w pliku manifestu w wersji 3 i późniejszych, ale wywołania zwrotne są dostępne ze względu na zgodność wsteczną. Nie możesz używać obu w tym samym wywołaniu funkcji. Obiet na obietnice zwracany jest z tym samym typem, który jest przekazywany do funkcji zwracającej wywołanie zwrotne.

  • get

    nieważne

    Obietnice

    Pobiera bieżące ustawienie treści dla danej pary adresów URL.

    Funkcja get ma postać:

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

    • szczegóły

      Obiekt

      • incognito

        logiczna opcjonalna

        Określa, czy należy sprawdzić ustawienia treści dla sesji w trybie incognito. (wartość domyślna to false)

      • primaryUrl

        ciąg znaków

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

      • resourceIdentifier

        ResourceIdentifier opcjonalny

        Dokładniejszy identyfikator typu treści, dla których mają zostać pobrane ustawienia.

      • secondaryUrl

        ciąg znaków opcjonalny

        Adres URL podrzędny, z którego ma zostać pobrana konfiguracja treści. Domyślnie jest to adres URL główny. Pamiętaj, że znaczenie adresu URL dodatkowego zależy od typu treści. Nie wszystkie typy treści używają adresów URL dodatkowych.

    • wywołanie zwrotne

      function opcjonalny

      Parametr callback ma postać:

      (details: object) => void

      • szczegóły

        Obiekt

        • ustawienie

          T

          Ustawienie treści. Możliwe wartości znajdziesz w opisie poszczególnych obiektów ContentSetting.

    • returns

      Obietkw<object>

      Chrome 96+

      Obietnice są obsługiwane w pliku manifestu w wersji 3 i późniejszych, ale wywołania zwrotne są dostępne ze względu na zgodność wsteczną. Nie możesz używać obu w tym samym wywołaniu funkcji. Obiet na obietnice zwracany jest z tym samym typem, który jest przekazywany do funkcji zwracającej wywołanie zwrotne.

  • getResourceIdentifiers

    nieważne

    Obietnice

    Funkcja getResourceIdentifiers ma postać:

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

    • wywołanie zwrotne

      function opcjonalny

      Parametr callback ma postać:

      (resourceIdentifiers?: ResourceIdentifier[]) => void

      • resourceIdentifiers

        ResourceIdentifier[] opcjonalnie

        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

      Promise<ResourceIdentifier[]>

      Chrome 96+

      Obietnice są obsługiwane w pliku manifestu w wersji 3 i późniejszych, ale wywołania zwrotne są dostępne ze względu na zgodność wsteczną. Nie możesz używać obu w tym samym wywołaniu funkcji. Obiet na obietnice zwracany jest z tym samym typem, który jest przekazywany do funkcji zwracającej wywołanie zwrotne.

  • zestaw

    nieważne

    Obietnice

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

    Funkcja set ma postać:

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

    • szczegóły

      Obiekt

      • primaryPattern

        ciąg znaków

        Wzorzec głównego adresu URL. Szczegółowe informacje o formacie wzorca znajdziesz w artykule Wzorce ustawień treści.

      • resourceIdentifier

        ResourceIdentifier opcjonalny

        Identyfikator zasobu typu treści.

      • zakres

        Zakres opcjonalnie

        Gdzie ustawić ustawienie (domyślnie: regularne).

      • secondaryPattern

        ciąg znaków opcjonalny

        Wzorzec dodatkowego adresu URL. Domyślnie dopasowuje wszystkie adresy URL. Szczegółowe informacje o formacie wzorca znajdziesz w artykule Wzorce ustawień treści.

      • ustawienie

        każdy

        Ustawienie stosowane przez tę regułę. Możliwe wartości znajdziesz w opisie poszczególnych obiektów ContentSetting.

    • wywołanie zwrotne

      function opcjonalny

      Parametr callback ma postać:

      () => void

    • returns

      Obietnica<void>

      Chrome 96+

      Obietnice są obsługiwane w pliku manifestu w wersji 3 i późniejszych, ale wywołania zwrotne są dostępne ze względu na zgodność wsteczną. Nie możesz używać obu w tym samym wywołaniu funkcji. Obiet na obietnice zwracany jest z tym samym typem, który jest przekazywany do funkcji zwracającej wywołanie zwrotne.

CookiesContentSetting

Chrome 44 lub nowszy

Typ wyliczeniowy

"allow"

"block"

"session_only"

FullscreenContentSetting

Chrome 44 lub nowszy

Wartość

"allow"

ImagesContentSetting

Chrome 44 lub nowszy

Typ wyliczeniowy

"allow"

"block"

JavascriptContentSetting

Chrome 44 lub nowszy

Typ wyliczeniowy

"allow"

"block"

LocationContentSetting

Chrome 44 lub nowszy

Typ wyliczeniowy

"allow"

"block"

"ask"

MicrophoneContentSetting

Chrome 46 lub nowszy

Typ wyliczeniowy

"allow"

"block"

"ask"

MouselockContentSetting

Chrome 44 lub nowszy

Wartość

"allow"

MultipleAutomaticDownloadsContentSetting

Chrome 44 lub nowszy

Typ wyliczeniowy

"allow"

"block"

"ask"

NotificationsContentSetting

Chrome 44 lub nowszy

Typ wyliczeniowy

"allow"

"block"

"ask"

PluginsContentSetting

Chrome 44 lub nowszy

Wartość

"block"

PopupsContentSetting

Chrome 44 lub nowszy

Typ wyliczeniowy

"allow"

"block"

PpapiBrokerContentSetting

Chrome 44 lub nowszy

Wartość

"block"

ResourceIdentifier

Jedynym typem treści, który używa identyfikatorów zasobów, jest contentSettings.plugins. Więcej informacji znajdziesz w artykule 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 dla danego typu treści.

Scope

Chrome 44 lub nowszy

Zakres ustawienia treści. regular: ustawienie dla zwykłego profilu (które jest dziedziczone przez profil incognito, jeśli nie zostało zastąpione gdzie indziej), incognito\_session\_only: ustawienie dla profilu incognito, które można ustawić tylko podczas sesji incognito i które jest usuwane po zakończeniu tej sesji (zastępuje zwykłe ustawienia).

Typ wyliczeniowy

„regular”

"incognito_session_only"

Właściwości

automaticDownloads

Określa, czy witryny mogą automatycznie pobierać wiele plików. allow: zezwalaj witrynom na automatyczne pobieranie wielu plików, block: nie zezwalaj witrynom na automatyczne pobieranie wielu plików, ask: pytaj, czy witryna chce automatycznie pobrać pliki po pierwszym pliku. Wartość domyślna to ask. Główny adres URL to adres URL elementu najwyższego poziomu. Adres URL podany jako drugi nie jest używany.

Typ

ContentSetting<MultipleAutomaticDownloadsContentSetting>

autoVerify

Chrome 113 lub nowszy

Określa, czy witryny mogą korzystać z interfejsu Private State Tokens API. allow: Zezwalaj witrynom na korzystanie z interfejsu Private State Tokens API, block: Zablokuj witrynom korzystanie z interfejsu Private State Tokens API. Wartość domyślna to allow. Główny adres URL to adres URL elementu najwyższego poziomu. Adres URL dodatkowy nie jest używany. UWAGA: podczas wywoływania funkcji set() główny wzór musi być .

Typ

ContentSetting<AutoVerifyContentSetting>

camera

Chrome 46 lub nowszy

Czy zezwolić stronom na dostęp do aparatu. Możesz wybrać jedną z tych opcji: allow: zezwalaj witrynom na dostęp do aparatu; block: nie zezwalaj witrynom na dostęp do aparatu; ask: pytaj, gdy witryna chce uzyskać dostęp do aparatu. Wartość domyślna to ask. Główny adres URL to adres URL dokumentu, który poprosił o dostęp do kamery. Adres URL podany jako drugi nie jest używany. UWAGA: ustawienie „Zezwól” jest nieprawidłowe, jeśli oba wzorce są „'”.

Typ

ContentSetting<CameraContentSetting>

clipboard

Chrome 121 lub nowszy

Określa, czy zezwolić witrynom na dostęp do schowka za pomocą zaawansowanych funkcji interfejsu Async Clipboard API. „Zaawansowane” funkcje obejmują wszystko oprócz zapisywania wbudowanych formatów po wykonaniu przez użytkownika odpowiedniego działania, czyli możliwość odczytu, możliwość zapisywania w formatach niestandardowych i możliwość zapisywania bez wykonywania przez użytkownika odpowiedniego działania. Wybierz jedną z opcji: allow: zezwalaj witrynom na korzystanie z zaawansowanych funkcji schowka; block: nie zezwalaj witrynom na korzystanie z zaawansowanych funkcji schowka; ask: pytaj, gdy witryna chce użyć zaawansowanych funkcji schowka. Wartość domyślna to ask. Główny adres URL to adres URL dokumentu, który poprosił o dostęp do schowka. Adres URL dodatkowy nie jest używany.

Typ

ContentSetting<ClipboardContentSetting>

cookies

Określa, czy witryny mogą tworzyć pliki cookie i inne dane lokalne. allow: akceptuj pliki cookie,block: blokuj pliki cookie,session\_only: akceptuj pliki cookie tylko w ramach bieżącej sesji. Wartość domyślna to allow. Główny adres URL to adres URL reprezentujący źródło pliku cookie. Drugi adres URL to adres URL ramki najwyższego poziomu.

Typ

ContentSetting<CookiesContentSetting>

fullscreen

Wycofany. Nie ma już żadnego wpływu. Uprawnienia do wyświetlania na pełnym ekranie są teraz przyznawane automatycznie w przypadku wszystkich witryn. Wartość zawsze wynosi allow.

Typ

ContentSetting<FullscreenContentSetting>

images

Określa, czy mają być wyświetlane obrazy. Jeden z tych elementów: allow: Pokaż obrazy block: Nie pokazuj obrazów. Wartość domyślna to allow. Główny adres URL to adres URL elementu najwyższego poziomu. Drugi adres URL to adres URL obrazu.

Typ

ContentSetting<ImagesContentSetting>

javascript

Określa, czy ma być wykonywany kod JavaScript. allow: uruchamianie JavaScriptu, block: nie uruchamianie JavaScriptu. Wartość domyślna to allow. Główny adres URL to adres URL elementu najwyższego poziomu. Adres URL dodatkowy nie jest używany.

Typ

ContentSetting<JavascriptContentSetting>

location

Czy zezwolić na geolokalizację. Wybierz jedną z tych opcji: allow: Zezwalaj witrynom na śledzenie Twojej lokalizacji fizycznej; block: Nie zezwalaj witrynom na śledzenie Twojej lokalizacji fizycznej; ask: Pytaj, zanim zezwolisz witrynom na śledzenie Twojej lokalizacji fizycznej. Wartość domyślna to ask. Główny adres URL to adres URL dokumentu, który poprosił o dane o lokalizacji. Drugi adres URL to adres URL ramki najwyższego poziomu (może się on różnić od adresu URL przesyłanego żądania).

Typ

ContentSetting<LocationContentSetting>

microphone

Chrome 46 lub nowszy

Określa, czy witryny mają mieć dostęp do mikrofonu. Możesz wybrać jedną z tych opcji: allow: zezwalaj witrynom na dostęp do mikrofonu, block: nie zezwalaj witrynom na dostęp do mikrofonu, ask: pytaj, gdy witryna 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. Adres URL dodatkowy nie jest używany. UWAGA: ustawienie „Zezwól” jest nieprawidłowe, jeśli oba wzorce są „'”.

Typ

ContentSetting<MicrophoneContentSetting>

mouselock

Wycofany. Nie ma już żadnego wpływu. Uprawnienia do blokowania myszy są teraz automatycznie przyznawane w przypadku wszystkich witryn. Wartość zawsze wynosi allow.

Typ

ContentSetting<MouselockContentSetting>

notifications

Określa, czy strony mogą wyświetlać powiadomienia na pulpicie. allow: Zezwalaj witrynom na wyświetlanie powiadomień na pulpicie, block: Nie zezwalaj witrynom na wyświetlanie powiadomień na pulpicie, ask: Pytaj, gdy witryna chce wyświetlać powiadomienia na pulpicie. Wartość domyślna to ask. Główny adres URL to adres URL dokumentu, który ma wyświetlać powiadomienie. Adres URL dodatkowy nie jest używany.

Typ

ContentSetting<NotificationsContentSetting>

plugins

Wycofany. W Chrome 88 usunięto obsługę Flasha, więc to uprawnienie nie ma już żadnego wpływu. Wartość zawsze wynosi block. Połączenia do numerów set() i clear() będą ignorowane.

Typ

ContentSetting<PluginsContentSetting>

popups

Określa, czy witryny mogą wyświetlać wyskakujące okienka. Wybierz jedną z opcji: allow: Zezwalaj na pokazywanie wyskakujących okienek, block: Nie zezwalaj na pokazywanie wyskakujących okienek. Wartość domyślna to block. Główny adres URL to adres URL elementu najwyższego poziomu. Adres URL podany jako drugi nie jest używany.

Typ

ContentSetting<PopupsContentSetting>

unsandboxedPlugins

Wycofany. Wcześniej określało, czy zezwolić witrynom na uruchamianie wtyczek bez piaskownicy. Jednak w Chrome 88 usunięto proces pośredniczący Flasha, więc to uprawnienie nie ma już żadnego wpływu. Wartość zawsze wynosi block. Połączenia do numerów set() i clear() będą ignorowane.

Typ

ContentSetting<PpapiBrokerContentSetting>