chrome.contentSettings

Описание

Используйте API chrome.contentSettings , чтобы изменить настройки, которые контролируют, могут ли веб-сайты использовать такие функции, как файлы cookie, JavaScript и плагины. В более общем смысле, настройки контента позволяют настраивать поведение Chrome для каждого сайта, а не глобально.

Разрешения

contentSettings

Чтобы использовать API, вы должны объявить разрешение "contentSettings" в манифесте вашего расширения. Например:

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

Концепции и использование

Шаблоны настройки контента

Вы можете использовать шаблоны, чтобы указать веб-сайты, на которые влияет каждый параметр контента. Например, https://*.youtube.com/* указывает youtube.com и все его поддомены. Синтаксис шаблонов настройки контента такой же, как и для шаблонов соответствия , с некоторыми отличиями:

  • Для URL-адресов http , https и ftp путь должен быть подстановочным знаком ( /* ). Для URL-адресов file путь должен быть указан полностью и не должен содержать подстановочных знаков.
  • В отличие от шаблонов соответствия, шаблоны настройки контента могут указывать номер порта. Если указан номер порта, шаблон соответствует только веб-сайтам с этим портом. Если номер порта не указан, шаблон соответствует всем портам.

Приоритет шаблона

Если для данного сайта применяется более одного правила настройки контента, правило с более конкретным шаблоном имеет приоритет.

Например, следующие шаблоны упорядочены по приоритету:

  1. https://www.example.com/*
  2. https://*.example.com/* (соответствует example.com и всем поддоменам)
  3. <all_urls> (соответствует каждому URL)

Три типа подстановочных знаков влияют на конкретность шаблона:

  • Подстановочные знаки в порте (например https://www.example.com:*/* ).
  • Подстановочные знаки в схеме (например *://www.example.com:123/* )
  • Подстановочные знаки в имени хоста (например https://*.example.com:123/* ).

Если шаблон более конкретен, чем другой шаблон в одной части, но менее конкретен в другой части, разные части проверяются в следующем порядке: имя хоста, схема, порт. Например, следующие шаблоны упорядочены по приоритету:

  1. https://www.example.com:*/* Указывает имя хоста и схему.
  2. *:/www.example.com:123/* Не такой высокий, поскольку, хотя он и указывает имя хоста, он не определяет схему.
  3. https://*.example.com:123/* Ниже, потому что, хотя он указывает порт и схему, в имени хоста есть подстановочный знак.

Первичные и вторичные шаблоны

URL-адрес, учитываемый при принятии решения о том, какой параметр контента применить, зависит от типа контента. Например, настройки contentSettings.notifications основаны на URL-адресе, показанном в омнибоксе. Этот URL-адрес называется «основным» URL-адресом.

Некоторые типы контента могут учитывать дополнительные URL-адреса. Например, разрешено ли сайту устанавливать файл contentSettings.cookies , решается на основе URL-адреса HTTP-запроса (который в данном случае является основным URL-адресом), а также URL-адреса, отображаемого в омнибоксе (который называется «вторичным URL-адресом»). «URL-адрес).

Если несколько правил имеют первичный и вторичный шаблоны, правило с более конкретным основным шаблоном имеет приоритет. Если несколько правил имеют один и тот же основной шаблон, правило с более конкретным вторичным шаблоном имеет приоритет. Например, следующий список пар первичных и вторичных шаблонов упорядочен по приоритету:

Приоритет Основной шаблон Вторичный шаблон
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>

Идентификаторы ресурсов

Идентификаторы ресурсов позволяют указать настройки контента для определенных подтипов типа контента. В настоящее время единственным типом контента, который поддерживает идентификаторы ресурсов, является contentSettings.plugins , где идентификатор ресурса идентифицирует конкретный плагин. При применении настроек контента сначала проверяются настройки конкретного плагина. Если для конкретного плагина настройки не найдены, проверяются общие настройки контента для плагинов.

Например, если правило настройки контента имеет идентификатор ресурса adobe-flash-player и шаблон <all_urls> , оно имеет приоритет над правилом без идентификатора ресурса и шаблоном https://www.example.com/* , даже если этот шаблон более конкретен.

Вы можете получить список идентификаторов ресурсов для типа контента, вызвав метод contentSettings.ContentSetting.getResourceIdentifiers() . Возвращаемый список может меняться в зависимости от набора установленных плагинов на компьютере пользователя, но Chrome старается поддерживать стабильность идентификаторов при обновлении плагинов.

Примеры

Чтобы попробовать этот API, установите пример API contentSettings из репозитория chrome-extension-samples .

Типы

AutoVerifyContentSetting

Хром 113+

Перечисление

"позволять"

"блокировать"

CameraContentSetting

Хром 46+

Перечисление

"позволять"

"блокировать"

"просить"

ClipboardContentSetting

Хром 121+

Перечисление

"позволять"

"блокировать"

"просить"

ContentSetting

Характеристики

  • прозрачный

    пустота

    Обещать

    Очистите все правила настройки контента, установленные этим расширением.

    Функция clear выглядит так: 

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

    • подробности

      объект

      • объем

        Область действия необязательна

        Где очистить настройку (по умолчанию: обычная).

    • перезвонить

      функция необязательна

      Параметр callback выглядит так: 

      ()=>void

    • возвращает

      Обещание<void>

      Хром 96+

      Промисы поддерживаются в Манифесте V3 и более поздних версиях, но обратные вызовы предусмотрены для обратной совместимости. Вы не можете использовать оба при одном вызове функции. Промис разрешается с тем же типом, который передается в обратный вызов.

  • получать

    пустота

    Обещать

    Получает текущие настройки контента для заданной пары URL-адресов.

    Функция get выглядит так: 

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

    • подробности

      объект

      • инкогнито

        логическое значение необязательно

        Следует ли проверять настройки контента для сеанса инкогнито. (по умолчанию ложь)

      • первичный URL

        нить

        Основной URL-адрес, для которого следует получить настройки контента. Обратите внимание, что значение основного URL-адреса зависит от типа контента.

      • Идентификатор ресурса

        Идентификатор ресурса необязательно

        Более конкретный идентификатор типа контента, для которого следует получить настройки.

      • вторичный URL

        строка необязательна

        Вторичный URL-адрес, для которого следует получить настройки контента. По умолчанию используется основной URL-адрес. Обратите внимание, что значение вторичного URL-адреса зависит от типа контента, и не все типы контента используют вторичные URL-адреса.

    • перезвонить

      функция необязательна

      Параметр callback выглядит так: 

      (details: object)=>void

      • подробности

        объект

        • параметр

          Т

          Настройка контента. Возможные значения см. в описании отдельных объектов ContentSetting.

    • возвращает

      Обещание<объект>

      Хром 96+

      Промисы поддерживаются в Манифесте V3 и более поздних версиях, но обратные вызовы предусмотрены для обратной совместимости. Вы не можете использовать оба при одном вызове функции. Промис разрешается с тем же типом, который передается в обратный вызов.

  • getResourceIdentifiers

    пустота

    Обещать

    Функция getResourceIdentifiers выглядит так: 

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

    • перезвонить

      функция необязательна

      Параметр callback выглядит так: 

      (resourceIdentifiers?: ResourceIdentifier[])=>void

      • Идентификаторы ресурсов

        Идентификатор Ресурса [] необязательно

        Список идентификаторов ресурсов для этого типа контента или undefined , если этот тип контента не использует идентификаторы ресурсов.

    • возвращает

      Обещание < Идентификатор Ресурса []>

      Хром 96+

      Промисы поддерживаются в Манифесте V3 и более поздних версиях, но обратные вызовы предусмотрены для обратной совместимости. Вы не можете использовать оба при одном вызове функции. Промис разрешается с тем же типом, который передается в обратный вызов.

  • набор

    пустота

    Обещать

    Применяет новое правило настройки контента.

    Функция set выглядит так: 

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

    • подробности

      объект

      • PrimaryPattern

        нить

        Шаблон основного URL-адреса. Подробную информацию о формате шаблона см. в разделе Шаблоны настройки содержимого .

      • Идентификатор ресурса

        Идентификатор ресурса необязательно

        Идентификатор ресурса для типа контента.

      • объем

        Область действия необязательна

        Где установить настройку (по умолчанию: обычная).

      • вторичный шаблон

        строка необязательна

        Шаблон вторичного URL-адреса. По умолчанию соответствует всем URL-адресам. Подробную информацию о формате шаблона см. в разделе Шаблоны настройки содержимого .

      • параметр

        любой

        Параметр, применяемый этим правилом. Возможные значения см. в описании отдельных объектов ContentSetting.

    • перезвонить

      функция необязательна

      Параметр callback выглядит так: 

      ()=>void

    • возвращает

      Обещание<void>

      Хром 96+

      Промисы поддерживаются в Манифесте V3 и более поздних версиях, но обратные вызовы предусмотрены для обратной совместимости. Вы не можете использовать оба при одном вызове функции. Промис разрешается с тем же типом, который передается в обратный вызов.

CookiesContentSetting

Хром 44+

Перечисление

"позволять"

"блокировать"

"только_сессия"

FullscreenContentSetting

Хром 44+

Ценить

"позволять"

ImagesContentSetting

Хром 44+

Перечисление

"позволять"

"блокировать"

JavascriptContentSetting

Хром 44+

Перечисление

"позволять"

"блокировать"

LocationContentSetting

Хром 44+

Перечисление

"позволять"

"блокировать"

"просить"

MicrophoneContentSetting

Хром 46+

Перечисление

"позволять"

"блокировать"

"просить"

MouselockContentSetting

Хром 44+

Ценить

"позволять"

MultipleAutomaticDownloadsContentSetting

Хром 44+

Перечисление

"позволять"

"блокировать"

"просить"

NotificationsContentSetting

Хром 44+

Перечисление

"позволять"

"блокировать"

"просить"

PluginsContentSetting

Хром 44+

Ценить

"блокировать"

PopupsContentSetting

Хром 44+

Перечисление

"позволять"

"блокировать"

PpapiBrokerContentSetting

Хром 44+

Ценить

"блокировать"

ResourceIdentifier

Единственный тип контента, использующий идентификаторы ресурсов, — это contentSettings.plugins . Дополнительные сведения см. в разделе Идентификаторы ресурсов .

Характеристики

  • описание

    строка необязательна

    Удобочитаемое описание ресурса.

  • идентификатор

    нить

    Идентификатор ресурса для данного типа контента.

Scope

Хром 44+

Область действия ContentSetting. Один из regular : настройка для обычного профиля (которая наследуется профилем инкогнито, если она не переопределена где-либо еще), incognito\_session\_only : настройка для профиля инкогнито, которая может быть установлена ​​только во время сеанса инкогнито и удаляется при завершении сеанса инкогнито ( переопределяет обычные настройки).

Перечисление

"обычный"

"incognito_session_only"

Характеристики

automaticDownloads

Разрешить ли сайтам автоматически загружать несколько файлов. Один из allow : разрешить сайтам автоматически загружать несколько файлов, block : не разрешать сайтам автоматически загружать несколько файлов, ask : спрашивать, когда сайт хочет автоматически загружать файлы после первого файла. По умолчанию — ask . Первичный URL-адрес — это URL-адрес фрейма верхнего уровня. Вторичный URL-адрес не используется.

Тип

ContentSetting < MultipleAutomaticDownloadsContentSetting >

autoVerify

Хром 113+

Разрешить ли сайтам использовать API частных государственных токенов . Один из вариантов: allow : разрешить сайтам использовать API частных государственных токенов, block : запретить сайтам использовать API частных государственных токенов. По allow . Первичный URL-адрес — это URL-адрес фрейма верхнего уровня. Вторичный URL-адрес не используется. ПРИМЕЧАНИЕ. При вызове set() основным шаблоном должен быть .

Тип

ContentSetting <AutoVerifyContentSetting>

camera

Хром 46+

Разрешить ли сайтам доступ к камере. Один из allow : разрешить: разрешить сайтам доступ к камере, block : запретить сайтам доступ к камере, ask : спрашивать, когда сайт хочет получить доступ к камере. По умолчанию — ask . Основной URL-адрес — это URL-адрес документа, запрашивающего доступ к камере. Вторичный URL-адрес не используется. ПРИМЕЧАНИЕ. Настройка «разрешить» недействительна, если оба шаблона имеют значение «».

Тип

ContentSetting < CameraContentSetting >

clipboard

Хром 121+

Разрешить ли сайтам доступ к буферу обмена с помощью расширенных возможностей API Async Clipboard. «Расширенные» возможности включают в себя все, что угодно, кроме записи встроенных форматов после жеста пользователя, то есть возможность чтения, возможность записи пользовательских форматов и возможность записи без жеста пользователя. Один из allow : разрешить сайтам использовать расширенные возможности буфера обмена, block : не разрешать сайтам использовать расширенные возможности буфера обмена, ask : спрашивать, когда сайт хочет использовать расширенные возможности буфера обмена. По умолчанию — ask . Основной URL-адрес — это URL-адрес документа, запрашивающего доступ к буферу обмена. Вторичный URL-адрес не используется.

Тип

ContentSetting < ClipboardContentSetting >

cookies

Разрешить ли веб-сайтам установку файлов cookie и других локальных данных. Один из allow : принимать файлы cookie, block : блокировать файлы cookie, session\_only : принимать файлы cookie только для текущего сеанса. По allow . Основной URL-адрес — это URL-адрес, представляющий источник cookie. Вторичный URL-адрес — это URL-адрес фрейма верхнего уровня.

Тип

ContentSetting <CookiesContentSetting>

fullscreen

Устарело. Больше не имеет никакого эффекта. Разрешение на полноэкранный режим теперь автоматически предоставляется всем сайтам. Значение всегда allow .

Тип

ContentSetting < FullscreenContentSetting >

images

Показывать ли изображения. Одно из allow : показывать изображения, block : не показывать изображения. По allow . Первичный URL-адрес — это URL-адрес фрейма верхнего уровня. Вторичный URL-адрес — это URL-адрес изображения.

Тип

ContentSetting <ImageContentSetting>

javascript

Запускать ли JavaScript. Одно из allow : запускать JavaScript, block : не запускать JavaScript. По allow . Первичный URL-адрес — это URL-адрес фрейма верхнего уровня. Вторичный URL-адрес не используется.

Тип

ContentSetting <JavascriptContentSetting>

location

Разрешить ли геолокацию. Один из allow : разрешить сайтам отслеживать ваше физическое местоположение, block : запретить сайтам отслеживать ваше физическое местоположение, ask : спросите, прежде чем разрешить сайтам отслеживать ваше физическое местоположение. По умолчанию — ask . Основной URL-адрес — это URL-адрес документа, запрашивающего данные о местоположении. Вторичный URL-адрес — это URL-адрес фрейма верхнего уровня (который может отличаться или не отличаться от запрашивающего URL-адреса).

Тип

ContentSetting < LocationContentSetting >

microphone

Хром 46+

Разрешить ли сайтам доступ к микрофону. Один из allow : разрешить: разрешить сайтам доступ к микрофону, block : запретить сайтам доступ к микрофону, ask : спрашивать, когда сайт хочет получить доступ к микрофону. По умолчанию — ask . Основной URL-адрес — это URL-адрес документа, запрашивающего доступ к микрофону. Вторичный URL-адрес не используется. ПРИМЕЧАНИЕ. Настройка «разрешить» недействительна, если оба шаблона имеют значение «».

Тип

ContentSetting <MicrophoneContentSetting>

mouselock

Устарело. Больше не имеет никакого эффекта. Разрешение на блокировку мыши теперь автоматически предоставляется всем сайтам. Значение всегда allow .

Тип

ContentSetting <MouselockContentSetting>

notifications

Разрешить ли сайтам показывать уведомления на рабочем столе. Один из allow : разрешить: разрешить сайтам показывать уведомления на рабочем столе, block : запретить сайтам показывать уведомления на рабочем столе, ask : спрашивать, когда сайт хочет показывать уведомления на рабочем столе. По умолчанию — ask . Основной URL-адрес — это URL-адрес документа, который хочет отобразить уведомление. Вторичный URL-адрес не используется.

Тип

ContentSetting < NotificationsContentSetting >

plugins

Устарело. Поскольку в Chrome 88 удалена поддержка Flash, это разрешение больше не имеет никакого эффекта. Значение всегда block . Вызовы set() clear() будут игнорироваться.

Тип

ContentSetting < ПлагиныContentSetting >

popups

Разрешить ли сайтам показывать всплывающие окна. Один из вариантов: allow : разрешить сайтам показывать всплывающие окна, block : запретить сайтам показывать всплывающие окна. По умолчанию — block . Первичный URL-адрес — это URL-адрес фрейма верхнего уровня. Вторичный URL-адрес не используется.

Тип

ContentSetting <PopupsContentSetting>

unsandboxedPlugins

Устарело. Раньше контролировалось, разрешать ли сайтам запускать плагины без изолированной программной среды, однако после удаления процесса Flash Broker в Chrome 88 это разрешение больше не имеет никакого эффекта. Значение всегда block . Вызовы set() clear() будут игнорироваться.

Тип

ContentSetting <PpapiBrokerContentSetting>