refresh date: 2026-09-25 robots: noindex
Описание
Используйте API chrome.contentSettings, чтобы изменить настройки, определяющие, могут ли сайты использовать такие функции, как файлы cookie, JavaScript и плагины. В целом настройки контента позволяют задавать поведение Chrome для отдельных сайтов, а не для всех сразу.
Разрешения
contentSettingsМанифест
Чтобы использовать API, необходимо объявить разрешение contentSettings в манифесте расширения. Пример:
{
"name": "My extension",
...
"permissions": [
"contentSettings"
],
...
}
Шаблоны настроек контента
Вы можете использовать шаблоны, чтобы указать, на какие сайты влияет каждая настройка контента. Например, https://*.youtube.com/* указывает на youtube.com и все его субдомены. Синтаксис шаблонов настроек контента такой же, как и для шаблонов соответствия, за некоторыми исключениями:
- Для URL
http,httpsиftpпуть должен быть подстановочным знаком (/*). Для URLfileпуть должен быть указан полностью и не должен содержать подстановочных знаков. - В отличие от шаблонов соответствия, в шаблонах настроек контента можно указать номер порта. Если указан номер порта, шаблон будет соответствовать только сайтам с этим портом. Если номер порта не указан, шаблон соответствует всем портам.
Приоритет шаблонов
Если к сайту применяется несколько правил настройки контента, приоритет имеет правило с более точным шаблоном.
Например, следующие шаблоны упорядочены по приоритету:
https://www.example.com/*https://*.example.com/*(соответствует example.com и всем субдоменам)<all_urls>(соответствует любому URL)
Существует три типа подстановочных знаков, которые влияют на точность шаблона:
- Подстановочные знаки в порте (например,
https://www.example.com:*/*). - Подстановочные знаки в схеме (например,
*://www.example.com:123/*). - Подстановочные знаки в имени хоста (например,
https://*.example.com:123/*).
Если один шаблон более точен, чем другой, в одной части, но менее точен в другой, то разные части проверяются в следующем порядке: имя хоста, схема, порт. Например, следующие шаблоны упорядочены по приоритету:
https://www.example.com:*/*Указывает имя хоста и схему.*:/www.example.com:123/*Приоритет ниже, поскольку указано имя хоста, но не схема.https://*.example.com:123/*Ниже, потому что, хотя в нем указаны порт и схема, в имени хоста есть подстановочный знак.
Основные и дополнительные шаблоны
URL, который учитывается при выборе настройки контента, зависит от типа контента.
Например, для contentSettings.notifications настройки задаются на основе 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, установите пример contentSettings API из репозитория chrome-extension-samples.
Типы
AutoVerifyContentSetting
Перечисление
"allow"
"block"
CameraContentSetting
Перечисление
"allow"
"block"
"ask"
ClipboardContentSetting
Перечисление
"allow"
"block"
"ask"
ContentSetting
Свойства
-
очистить
void
PromiseУдалить все правила настройки контента, заданные этим расширением.
Функция
clearвыглядит следующим образом:(details: object, callback?: function) => {...}
-
подробные сведения
Объект
-
область действия
Scope необязательный
Где очистить настройку (по умолчанию: обычная).
-
-
обратный вызов
function необязательно
Параметр
callbackвыглядит следующим образом:() => void
-
Возвращает
Promise<void>
Chrome 96 и более поздних версий.Объекты Promise поддерживаются только в Manifest V3 и более поздних версиях. На других платформах нужно использовать обратные вызовы.
-
-
get
void
PromiseПолучает текущие настройки контента для заданной пары URL.
Функция
getвыглядит следующим образом:(details: object, callback?: function) => {...}
-
подробные сведения
Объект
-
инкогнито
Логическое значение (необязательно)
Проверять ли настройки контента для сеанса инкогнито. (по умолчанию false)
-
primaryUrl
string
Основной URL, для которого нужно получить настройки контента. Обратите внимание, что значение основного URL зависит от типа контента.
-
resourceIdentifier
ResourceIdentifier необязательный
Более точный идентификатор типа контента, для которого нужно получить настройки.
-
secondaryUrl
Строка (необязательно)
Дополнительный URL, для которого нужно получить настройки контента. По умолчанию используется основной URL. Обратите внимание, что значение дополнительного URL зависит от типа контента и что дополнительные URL используются не для всех типов контента.
-
-
обратный вызов
function необязательно
Параметр
callbackвыглядит следующим образом:(details: object) => void
-
подробные сведения
Объект
-
настройка
T
Настройки контента. Возможные значения приведены в описании отдельных объектов ContentSetting.
-
-
-
Возвращает
Promise<object>
Chrome 96 и более поздних версий.Объекты Promise поддерживаются только в Manifest V3 и более поздних версиях. На других платформах нужно использовать обратные вызовы.
-
-
getResourceIdentifiers
void
PromiseФункция
getResourceIdentifiersвыглядит следующим образом:(callback?: function) => {...}
-
обратный вызов
function необязательно
Параметр
callbackвыглядит следующим образом:(resourceIdentifiers?: ResourceIdentifier[]) => void
-
resourceIdentifiers
ResourceIdentifier[] необязательный
Список идентификаторов ресурсов для этого типа контента или
undefined, если этот тип контента не использует идентификаторы ресурсов.
-
-
Возвращает
Promise<ResourceIdentifier[]>
Chrome 96 и более поздних версий.Объекты Promise поддерживаются только в Manifest V3 и более поздних версиях. На других платформах нужно использовать обратные вызовы.
-
-
set
void
PromiseПрименяет новое правило настройки контента.
Функция
setвыглядит следующим образом:(details: object, callback?: function) => {...}
-
подробные сведения
Объект
-
primaryPattern
string
Шаблон основного URL. Подробные сведения о формате шаблона приведены в статье Шаблоны настроек контента.
-
resourceIdentifier
ResourceIdentifier необязательный
Идентификатор ресурса для типа контента.
-
область действия
Scope необязательный
Где задать настройку (по умолчанию: обычная).
-
secondaryPattern
Строка (необязательно)
Шаблон дополнительного URL. По умолчанию сопоставляются все URL. Подробные сведения о формате шаблона можно найти в статье Шаблоны настроек контента.
-
настройка
любой
Настройка, применяемая этим правилом. Возможные значения приведены в описании отдельных объектов ContentSetting.
-
-
обратный вызов
function необязательно
Параметр
callbackвыглядит следующим образом:() => void
-
Возвращает
Promise<void>
Chrome 96 и более поздних версий.Объекты Promise поддерживаются только в Manifest V3 и более поздних версиях. На других платформах нужно использовать обратные вызовы.
-
CookiesContentSetting
Перечисление
"allow"
"block"
"session_only"
FullscreenContentSetting
Значение
"allow"
ImagesContentSetting
Перечисление
"allow"
"block"
JavascriptContentSetting
Перечисление
"allow"
"block"
LocationContentSetting
Перечисление
"allow"
"block"
"ask"
MicrophoneContentSetting
Перечисление
"allow"
"block"
"ask"
MouselockContentSetting
Значение
"allow"
MultipleAutomaticDownloadsContentSetting
Перечисление
"allow"
"block"
"ask"
NotificationsContentSetting
Перечисление
"allow"
"block"
"ask"
PluginsContentSetting
Значение
"block"
PopupsContentSetting
Перечисление
"allow"
"block"
PpapiBrokerContentSetting
Значение
"block"
ResourceIdentifier
Идентификаторы ресурсов используются только в контенте типа contentSettings.plugins. Подробнее об идентификаторах ресурсов…
Свойства
-
описание
Строка (необязательно)
Понятное описание ресурса.
-
id
string
Идентификатор ресурса для указанного типа контента.
Scope
Область действия ContentSetting. Одно из следующих значений:
regular – настройка для обычного профиля (которая наследуется профилем инкогнито, если не переопределена в другом месте);
incognito\_session\_only – настройка для профиля инкогнито, которую можно задать только во время сеанса инкогнито и которая удаляется по его окончании (переопределяет обычные настройки).
Перечисление
"regular"
"incognito_session_only"
SoundContentSetting
Перечисление
"allow"
"block"
Свойства
automaticDownloads
Это правило определяет, могут ли сайты автоматически скачивать несколько файлов. Одно из следующих значений:
allow – разрешить сайтам автоматически скачивать несколько файлов;
block – запретить сайтам автоматически скачивать несколько файлов;
ask – спрашивать, когда сайт пытается автоматически скачать файлы после первого.
Значение по умолчанию – ask.
Основной URL – это URL фрейма верхнего уровня. Дополнительный URL не используется.
autoVerify
Разрешить ли сайтам использовать Private State Tokens API. Одно из следующих значений:
allow – разрешить сайтам использовать Private State Tokens API;
block – запретить сайтам использовать Private State Tokens API.
Значение по умолчанию – allow.
При вызове set() основным шаблоном URL должен быть <all_urls>. Дополнительный URL не используется.
camera
Разрешить сайтам доступ к камере. Одно из следующих значений:
allow – разрешить сайтам доступ к камере;
block – запретить сайтам доступ к камере;
ask – спрашивать, когда сайт запрашивает доступ к камере.
Значение по умолчанию – ask.
Основной URL – это URL документа, который запросил доступ к камере. Дополнительный URL не используется.
ПРИМЕЧАНИЕ. Значение allow недопустимо, если оба шаблона имеют вид <all_urls>.
clipboard
Это правило определяет, могут ли сайты получать доступ к буферу обмена через расширенные возможности Async Clipboard API. К расширенным возможностям относится все, кроме записи встроенных форматов после жеста пользователя, то есть возможность чтения, возможность записи пользовательских форматов и возможность записи без жеста пользователя. Одно из следующих значений:
allow – разрешить сайтам использовать расширенные возможности буфера обмена;
block – запретить сайтам использовать расширенные возможности буфера обмена;
ask – спрашивать, когда сайт хочет использовать расширенные возможности буфера обмена.
Значение по умолчанию – ask.
Основной URL – это URL документа, который запросил доступ к буферу обмена. Дополнительный URL не используется.
cookies
Это правило определяет, могут ли сайты сохранять файлы cookie и другие локальные данные. Одно из следующих значений:
allow – разрешить файлы cookie;
block – заблокировать файлы cookie;
session\_only – разрешить файлы cookie только для текущего сеанса.
Значение по умолчанию – allow.
Основной URL – это URL, представляющий источник файла cookie. Вторичный URL – это URL фрейма верхнего уровня.
fullscreen
Поддержка прекращена. Больше не действует. Теперь всем сайтам автоматически разрешено открывать контент в полноэкранном режиме. Значение всегда равно allow.
images
Показывать ли изображения. Одно из следующих значений:
allow – показывать изображения;
block – не показывать изображения.
Значение по умолчанию – allow.
Основной URL – это URL фрейма верхнего уровня. В качестве дополнительного URL регистрируется URL изображения.
javascript
Выполнять ли JavaScript. Одно из следующих значений:
allow – выполнять JavaScript;
block – не выполнять JavaScript.
Значение по умолчанию – allow.
Основной URL – это URL фрейма верхнего уровня. Дополнительный URL не используется.
location
Разрешить или запретить геолокацию. Одно из следующих значений:
allow – разрешить сайтам отслеживать ваше местоположение;
block – запретить сайтам отслеживать ваше местоположение;
ask – спрашивать, прежде чем разрешить сайтам отслеживать ваше местоположение.
Значение по умолчанию – ask.
Основной URL – это URL документа, который запрашивал данные о местоположении. Вторичный URL – это URL фрейма верхнего уровня (он может совпадать с URL запроса).
microphone
Разрешить сайтам доступ к микрофону. Одно из следующих значений:
allow – разрешить сайтам доступ к микрофону;
block – запретить сайтам доступ к микрофону;
ask – спрашивать, когда сайт запрашивает доступ к микрофону.
Значение по умолчанию – ask.
Основной URL – это URL документа, который запросил доступ к микрофону. Дополнительный URL не используется.
ПРИМЕЧАНИЕ. Значение allow недопустимо, если оба шаблона имеют вид <all_urls>.
mouselock
Поддержка прекращена. Больше не действует. Теперь всем сайтам автоматически разрешено блокировать указатель мыши. Значение всегда равно allow.
notifications
Разрешить сайтам показывать уведомления на рабочем столе. Одно из следующих значений:
allow – разрешить сайтам показывать уведомления на рабочем столе;
block – запретить сайтам показывать уведомления на рабочем столе;
ask – спрашивать, когда сайт хочет показать уведомления на рабочем столе.
Значение по умолчанию – ask.
Основной URL – это URL документа, который хочет показать уведомление. Дополнительный URL не используется.
plugins
Поддержка прекращена. Поскольку поддержка Flash была прекращена в Chrome 88, это разрешение больше не действует. Значение всегда равно block. Вызовы set() и clear() будут игнорироваться.
popups
Разрешить сайтам показывать всплывающие окна. Одно из следующих значений:
allow – разрешить сайтам показывать всплывающие окна;
block – запретить сайтам показывать всплывающие окна.
Значение по умолчанию – block.
Основной URL – это URL фрейма верхнего уровня. Дополнительный URL не используется.
unsandboxedPlugins
Поддержка прекращена. Ранее это правило определяло, разрешено ли сайтам запускать плагины вне изолированной среды. Однако после удаления процесса Flash Broker в Chrome 88 это разрешение больше не действует. Значение всегда равно block. Вызовы set() и clear() будут игнорироваться.