chrome.contentSettings

Opis

Użyj interfejsu chrome.contentSettings API, aby zmienić ustawienia kontrolujące, czy witryny mogą korzystać z takich funkcji jak pliki cookie, JavaScript i wtyczki. Ustawienia treści umożliwiają dostosowywanie działania Chrome w przypadku poszczególnych witryn, 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ą wzorcó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 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ć w pełni 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 określono numer portu, wzorzec pasuje tylko do witryn z tym portem. Jeśli nie podasz 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 ustawień treści, pierwszeństwo ma reguła z bardziej szczegółowym wzorcem.

Na przykład te wzorce są uporządkowane według priorytetu:

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

Na to, jak szczegółowy jest wzorzec, 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 jeden wzorzec jest bardziej szczegółowy od drugiego w jednej części, ale mniej szczegółowy w innej, poszczególne części są sprawdzane w tej kolejności: nazwa hosta, schemat, port. Na przykład poniższe 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 wysoki, ponieważ chociaż określa nazwę hosta, nie określa schematu.
  3. https://*.example.com:123/* Niższy, ponieważ chociaż określa port i schemat, zawiera symbol wieloznaczny w nazwie hosta.

Wzorce 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 ustawień contentSettings.notifications są one oparte na adresie URL wyświetlanym w omniboksie. Ten adres URL nazywamy „podstawowym”.

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 w tym przypadku jest adresem URL głównym) oraz adresu URL wyświetlanego w omniboksie (zwanego adresem URL „dodatkowym”).

Jeśli kilka reguł ma wzorce podstawowe i dodatkowe, pierwszeństwo ma reguła z bardziej szczegółowym wzorcem podstawowym. Jeśli kilka reguł ma ten sam wzorzec główny, pierwszeństwo ma reguła z bardziej szczegółowym wzorcem dodatkowym. Na przykład ta lista par wzorców podstawowych i dodatkowych jest uporządkowana według ważności:

PierwszeństwoWzorzec podstawowyWzór 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 treści dotyczącego obrazów nie są obsługiwane wzorce 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. Identyfikator zasobu identyfikuje konkretną wtyczkę. Podczas stosowania ustawień treści najpierw sprawdzane są ustawienia konkretnej wtyczki. Jeśli nie znaleziono ustawień dla 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 ona 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ę zmieniać w zależności od zestawu wtyczek zainstalowanych 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 interfejsu contentSettings API z repozytorium chrome-extension-samples.

Typy

AutoVerifyContentSetting

Chrome 113 lub nowsza

Typ wyliczeniowy

„allow”

„block”

CameraContentSetting

Chrome 46 lub nowsza

Typ wyliczeniowy

„allow”

„block”

„ask”

ClipboardContentSetting

Chrome 121 lub nowsza

Typ wyliczeniowy

„allow”

„block”

„ask”

ContentSetting

Właściwości

  • wyczyść

    pusty

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

    Funkcja clear wygląda tak:

    (details: object) => {...}

    • szczegóły

      obiekt

      • zakres

        Scope opcjonalny

        Miejsce, w którym można wyczyścić ustawienie (domyślnie: regularne).

    • returns

      Promise<void>

      Chrome w wersji 96 lub nowszej
  • get

    pusty

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

    Funkcja get wygląda tak:

    (details: object) => {...}

    • szczegóły

      obiekt

      • incognito

        wartość logiczna opcjonalna

        Określa, czy należy sprawdzić ustawienia treści w sesji incognito. (domyślnie false)

      • primaryUrl

        ciąg znaków

        Główny 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

        ResourceIdentifier opcjonalny

        Bardziej szczegółowy identyfikator typu treści, dla których należy pobrać ustawienia.

      • secondaryUrl

        string 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. Nie wszystkie typy treści używają dodatkowych adresów URL.

    • returns

      Promise<object>

      Chrome w wersji 96 lub nowszej
  • getResourceIdentifiers

    pusty

    Funkcja getResourceIdentifiers wygląda tak:

    () => {...}

  • zestaw

    pusty

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

    Funkcja set wygląda tak:

    (details: object) => {...}

    • 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 dla typu treści.

      • zakres

        Scope opcjonalny

        Miejsce, w którym można ustawić to ustawienie (domyślnie: regular).

      • secondaryPattern

        string opcjonalny

        Wzorzec dodatkowego adresu URL. Domyślnie pasuje do wszystkich adresów URL. Szczegółowe informacje o formacie wzorca znajdziesz w artykule Wzorce ustawień treści.

      • ustawienie

        każdy

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

    • returns

      Promise<void>

      Chrome w wersji 96 lub nowszej

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 nowsza

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

    string 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 ContentSetting. Jedno z tych ustawień:regular: ustawienie profilu zwykłego (dziedziczone przez profil incognito, jeśli nie zostanie zastąpione w innym miejscu);incognito\_session\_only: ustawienie profilu incognito, które można skonfigurować tylko podczas sesji incognito i które jest usuwane po zakończeniu sesji incognito (zastępuje ustawienia zwykłe).

Typ wyliczeniowy

„regular”

"incognito_session_only"

Właściwości

automaticDownloads

Określa, czy zezwalać witrynom na automatyczne pobieranie wielu plików. Jeden z tych elementów:allow: Zezwalaj witrynom na automatyczne pobieranie wielu plikówblock: Nie zezwalaj witrynom na automatyczne pobieranie wielu plikówask: Pytaj, gdy witryna chce automatycznie pobrać pliki po pobraniu pierwszego pliku. Wartość domyślna to ask. Główny adres URL to adres ramki najwyższego poziomu. Dodatkowy adres URL nie jest używany.

Typ

ContentSetting<MultipleAutomaticDownloadsContentSetting>

autoVerify

Chrome 113 lub nowsza

Określa, czy zezwalać witrynom na korzystanie z interfejsu Private State Tokens API. Jedna z tych opcji:allow: Zezwalaj witrynom na korzystanie z interfejsu Private State Tokens API, block: Blokuj witrynom korzystanie z interfejsu Private State Tokens API. Wartość domyślna to allow. Podczas wywoływania funkcji set() główny wzorzec adresu URL musi mieć postać <all_urls>. Dodatkowy adres URL nie jest używany.

Typ

ContentSetting<AutoVerifyContentSetting>

camera

Chrome 46 lub nowsza

Określa, czy witryny mogą uzyskiwać dostęp do kamery. Jedna z tych opcji:allow: Zezwalaj witrynom na dostęp do kamery, block: Nie zezwalaj witrynom na dostęp do kamery, ask: Pytaj, gdy witryna chce uzyskać dostęp do kamery. Wartość domyślna to ask. Główny adres URL to adres dokumentu, który poprosił o dostęp do kamery. Dodatkowy adres URL nie jest używany. UWAGA: ustawienie „allow” jest nieprawidłowe, jeśli oba wzorce to „<all_urls>”.

Typ

ContentSetting<CameraContentSetting>

clipboard

Chrome 121 lub nowsza

Określa, czy zezwolić witrynom na dostęp do schowka za pomocą zaawansowanych funkcji interfejsu Async Clipboard API. Funkcje „zaawansowane” obejmują wszystko poza zapisywaniem wbudowanych formatów po wykonaniu gestu przez użytkownika, czyli możliwość odczytu, możliwość zapisywania formatów niestandardowych i możliwość zapisywania bez gestu użytkownika. Jeden z tych elementów:allow: Zezwalaj witrynom na korzystanie z zaawansowanych funkcji schowka, block: Nie zezwalaj witrynom na korzystanie z zaawansowanych funkcji schowka, ask: Pytaj, gdy witryna chce korzystać z zaawansowanych funkcji schowka. Wartość domyślna to ask. Główny adres URL to adres dokumentu, który poprosił o dostęp do schowka. Dodatkowy adres URL nie jest używany.

Typ

ContentSetting<ClipboardContentSetting>

cookies

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

Typ

ContentSetting<CookiesContentSetting>

fullscreen

Wycofano. Nie ma już żadnego wpływu. Uprawnienie do wyświetlania na pełnym ekranie jest teraz automatycznie przyznawane wszystkim witrynom. Wartość to zawsze allow.

Typ

ContentSetting<FullscreenContentSetting>

images

Określa, czy mają być wyświetlane obrazy. Jeden z tych warunków:allow: wyświetlaj obrazy,allow: nie wyświetlaj obrazów.block Wartość domyślna to allow. Główny adres URL to adres ramki najwyższego poziomu. Dodatkowy adres URL to adres URL obrazu.

Typ

ContentSetting<ImagesContentSetting>

javascript

Określa, czy ma być wykonywany kod JavaScript. Jeden z tych warunków:allow: uruchom JavaScript,block: nie uruchamiaj JavaScriptu. Wartość domyślna to allow. Główny adres URL to adres ramki najwyższego poziomu. Dodatkowy adres URL nie jest używany.

Typ

ContentSetting<JavascriptContentSetting>

location

Określa, czy zezwolić na geolokalizację. Jeden z tych elementów:allow: Zezwalaj witrynom na śledzenie Twojej lokalizacji fizycznejblock: Nie zezwalaj witrynom na śledzenie Twojej lokalizacji fizycznejask: Pytaj, zanim zezwolisz witrynom na śledzenie Twojej lokalizacji fizycznej. Wartość domyślna to ask. Główny adres URL to adres dokumentu, który wysłał żądanie danych o lokalizacji. Dodatkowy adres URL to adres URL ramki najwyższego poziomu (który może się różnić od adresu URL żądania).

Typ

ContentSetting<LocationContentSetting>

microphone

Chrome 46 lub nowsza

Określa, czy witryny mogą mieć dostęp do mikrofonu. Jedna 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 dokumentu, który poprosił o dostęp do mikrofonu. Dodatkowy adres URL nie jest używany. UWAGA: ustawienie „allow” jest nieprawidłowe, jeśli oba wzorce to „<all_urls>”.

Typ

ContentSetting<MicrophoneContentSetting>

mouselock

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

Typ

ContentSetting<MouselockContentSetting>

notifications

Określa, czy zezwalać stronom na wyświetlanie powiadomień na pulpicie. Jedna z tych opcji: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 chce wyświetlić powiadomienie. Dodatkowy adres URL nie jest używany.

Typ

ContentSetting<NotificationsContentSetting>

plugins

Wycofano. Obsługa Flasha została usunięta w Chrome 88, więc to uprawnienie nie ma już żadnego wpływu. Wartość to zawsze block. Połączenia z numerów set() i clear() będą ignorowane.

Typ

ContentSetting<PluginsContentSetting>

popups

Określa, czy witryny mogą wyświetlać wyskakujące okienka. Jedna z tych opcji:allow: Zezwalaj witrynom na pokazywanie wyskakujących okienek,block: Nie zezwalaj witrynom na pokazywanie wyskakujących okienek. Wartość domyślna to block. Główny adres URL to adres ramki najwyższego poziomu. Dodatkowy adres URL nie jest używany.

Typ

ContentSetting<PopupsContentSetting>

unsandboxedPlugins

Wycofano. Wcześniej ta zasada określała, czy strony mogą uruchamiać wtyczki bez piaskownicy. Jednak po usunięciu procesu brokera Flasha w Chrome 88 to uprawnienie nie ma już żadnego wpływu. Wartość to zawsze block. Połączenia z numerów set() i clear() będą ignorowane.

Typ

ContentSetting<PpapiBrokerContentSetting>