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-адреса. Например, решение о том, разрешено ли сайту устанавливать файлы cookie 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, установите пример API contentSettings из репозитория chrome-extension-samples .

Типы

AutoVerifyContentSetting

Хром 113+

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

"позволять"

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

CameraContentSetting

Хром 46+

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

"позволять"

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

"просить"

ClipboardContentSetting

Хром 121+

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

"позволять"

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

"просить"

ContentSetting

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

  • прозрачный

    пустота

    Обещать

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

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

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

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

      объект

      • объем

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

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

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

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

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

      () => void

    • возвращается

      Обещание<void>

      Хром 96+

      Обещания поддерживаются только для Manifest V3 и более поздних версий, на других платформах необходимо использовать обратные вызовы.

  • получать

    пустота

    Обещать

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

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

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

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

      объект

      • инкогнито

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

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

      • основнойUrl

        нить

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

      • resourceIdentifier

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

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

      • вторичный URL

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

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

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

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

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

      (details: object) => void

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

        объект

        • параметр

          Т

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

    • возвращается

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

      Хром 96+

      Обещания поддерживаются только для Manifest V3 и более поздних версий, на других платформах необходимо использовать обратные вызовы.

  • получитьResourceIdentifiers

    пустота

    Обещать

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

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

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

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

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

      (resourceIdentifiers?: ResourceIdentifier[]) => void

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

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

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

    • возвращается

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

      Хром 96+

      Обещания поддерживаются только для Manifest V3 и более поздних версий, на других платформах необходимо использовать обратные вызовы.

  • набор

    пустота

    Обещать

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

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

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

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

      объект

      • основной шаблон

        нить

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

      • resourceIdentifier

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

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

      • объем

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

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

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

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

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

      • параметр

        любой

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

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

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

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

      () => void

    • возвращается

      Обещание<void>

      Хром 96+

      Обещания поддерживаются только для Manifest V3 и более поздних версий, на других платформах необходимо использовать обратные вызовы.

CookiesContentSetting

Хром 44+

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

"позволять"

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

"session_only"

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"

SoundContentSetting

Хром 141+

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

"позволять"

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

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

automaticDownloads

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

Тип

ContentSetting < MultipleAutomaticDownloadsContentSetting >

autoVerify

Хром 113+

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

Тип

ContentSetting < AutoVerifyContentSetting >

camera

Хром 46+

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

Тип

ContentSetting < CameraContentSetting >

clipboard

Хром 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 .

Тип

ContentSetting < FullscreenContentSetting >

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

Хром 46+

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

Тип

ContentSetting < PopupsContentSetting >

unsandboxedPlugins

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

Тип

ContentSetting < PpapiBrokerContentSetting >