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-адресом).

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

Приоритет Основной узор Вторичный узор
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, установите пример contentSettings API из репозитория chrome-extension-samples .

Типы

AutoVerifyContentSetting

Chrome 113+

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

"позволять"

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

CameraContentSetting

Chrome 46+

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

"позволять"

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

"просить"

ClipboardContentSetting

Chrome 121+

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

"позволять"

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

"просить"

ContentSetting

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

  • прозрачный

    пустота

    Обещать

    Удалите все правила настройки содержимого, установленные этим расширением.

    Функция clear выглядит следующим образом: 

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

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

      объект

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

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

      Параметр callback выглядит следующим образом: 

      () => void

    • возвраты

      Обещание<пустота>

      Chrome 96+

      Поддержка промисов доступна только для Manifest V3 и более поздних версий; для других платформ необходимо использовать колбэки.

  • получать

    пустота

    Обещать

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

    Функция get выглядит следующим образом: 

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

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

      объект

      • инкогнито

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

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

      • primaryUrl

        нить

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

      • resourceIdentifier

        ResourceIdentifier ( необязательно)

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

      • вторичный URL

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

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

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

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

      Параметр callback выглядит следующим образом: 

      (details: object) => void

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

        объект

        • параметр

          Т

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

    • возвраты

      Promise<object>

      Chrome 96+

      Поддержка промисов доступна только для Manifest V3 и более поздних версий; для других платформ необходимо использовать колбэки.

  • getResourceIdentifiers

    пустота

    Обещать

    Функция getResourceIdentifiers выглядит следующим образом: 

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

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

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

      Параметр callback выглядит следующим образом: 

      (resourceIdentifiers?: ResourceIdentifier[]) => void

      • resourceIdentifiers

        ResourceIdentifier [] необязательный

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

    • возвраты

      Promise< ResourceIdentifier []>

      Chrome 96+

      Поддержка промисов доступна только для Manifest V3 и более поздних версий; для других платформ необходимо использовать колбэки.

  • набор

    пустота

    Обещать

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

    Функция set выглядит следующим образом: 

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

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

      объект

      • primaryPattern

        нить

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

      • resourceIdentifier

        ResourceIdentifier ( необязательно)

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

      • объем

        Область применения необязательна

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

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

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

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

      • параметр

        любой

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

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

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

      Параметр callback выглядит следующим образом: 

      () => void

    • возвраты

      Обещание<пустота>

      Chrome 96+

      Поддержка промисов доступна только для Manifest V3 и более поздних версий; для других платформ необходимо использовать колбэки.

CookiesContentSetting

Chrome 44+

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

"позволять"

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

"session_only"

FullscreenContentSetting

Chrome 44+

Ценить

"позволять"

ImagesContentSetting

Chrome 44+

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

"позволять"

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

JavascriptContentSetting

Chrome 44+

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

"позволять"

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

LocationContentSetting

Chrome 44+

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

"позволять"

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

"просить"

MicrophoneContentSetting

Chrome 46+

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

"позволять"

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

"просить"

MouselockContentSetting

Chrome 44+

Ценить

"позволять"

MultipleAutomaticDownloadsContentSetting

Chrome 44+

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

"позволять"

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

"просить"

NotificationsContentSetting

Chrome 44+

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

"позволять"

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

"просить"

PluginsContentSetting

Chrome 44+

Ценить

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

PopupsContentSetting

Chrome 44+

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

"позволять"

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

PpapiBrokerContentSetting

Chrome 44+

Ценить

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

ResourceIdentifier

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

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

  • описание

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

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

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

    нить

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

Scope

Chrome 44+

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

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

"обычный"

"incognito_session_only"

SoundContentSetting

Chrome 141+

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

"позволять"

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

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

automaticDownloads

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

Тип

ContentSetting < MultipleAutomaticDownloadsContentSetting >

autoVerify

Chrome 113+

Разрешить ли сайтам использовать API частных токенов . Одно из allow : allow: разрешить сайтам использовать API частных токенов, block : заблокировать сайтам использование API частных токенов. По умолчанию — allow . При вызове set() основной шаблон URL должен быть <all_urls> . Дополнительный URL не используется.

Тип

ContentSetting < AutoVerifyContentSetting >

camera

Chrome 46+

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

Тип

ContentSetting < CameraContentSetting >

clipboard

Chrome 121+

Разрешать ли сайтам доступ к буферу обмена через расширенные возможности API асинхронного буфера обмена? К «расширенным» возможностям относятся все, кроме записи встроенных форматов после действия пользователя, то есть возможность чтения, возможность записи пользовательских форматов и возможность записи без действия пользователя. Один из вариантов: 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 .

Тип

Настройки содержимого < Настройки содержимого для полноэкранного режима >

images

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

Тип

ContentSetting < ImagesContentSetting >

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

Chrome 46+

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

Тип

ContentSetting < MicrophoneContentSetting >

mouselock

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

Тип

ContentSetting <MouselockContentSetting>

notifications

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

Тип

ContentSetting < NotificationsContentSetting >

plugins

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

Тип

ContentSetting < PluginsContentSetting >

popups

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

Тип

ContentSetting < PopupsContentSetting >

unsandboxedPlugins

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

Тип

ContentSetting < PpapiBrokerContentSetting >