chrome.permissions

refresh date: 2026-09-25 robots: noindex

Описание

Используйте API chrome.permissions, чтобы запрашивать объявленные необязательные разрешения во время выполнения, а не установки. Так пользователи будут понимать, зачем нужны разрешения, и предоставлять только необходимые.

Обзор

Предупреждения о разрешениях описывают возможности, предоставляемые API, но некоторые из них могут быть неочевидными. Permissions API позволяет разработчикам объяснять предупреждения о разрешениях и постепенно вводить новые функции, чтобы пользователи могли безопасно ознакомиться с расширением. Это позволяет пользователям указывать, какой уровень доступа они готовы предоставить и какие функции хотят включить.

Например, основная функция расширения с необязательными разрешениями – переопределение страницы быстрого доступа. Одна из функций – отображение цели пользователя на день. Для работы этой функции требуется только разрешение storage, которое не сопровождается предупреждением. У расширения есть дополнительная функция, которую пользователи могут включить, нажав следующую кнопку:

Кнопка расширения, которая включает дополнительные функции

Для показа самых популярных сайтов пользователя требуется разрешение topSites, которое сопровождается следующим предупреждением:

Предупреждение о расширении для topSites API

Как реализовать необязательные разрешения

Шаг 1. Определите, какие разрешения обязательны, а какие нет

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

  • Используйте обязательные разрешения, когда они необходимы для работы основных функций расширения.
  • Используйте необязательные разрешения, когда они нужны для дополнительных функций расширения.

Преимущества обязательных разрешений:

  • Меньше запросов. Расширение может запросить у пользователя разрешение на все действия один раз.
  • Простая разработка. Необходимые разрешения гарантированно будут предоставлены.

Преимущества необязательных разрешений:

  • Повышенная безопасность. Расширения работают с меньшим количеством разрешений, поскольку пользователи включают только необходимые.
  • Более подробная информация для пользователей. Расширение может объяснить, почему ему требуется определенное разрешение, когда пользователь включает соответствующую функцию.
  • Простое обновление. Если при обновлении расширения вы добавляете необязательные разрешения, Chrome не будет отключать его для пользователей.

Шаг 2. Объявите необязательные разрешения в манифесте

Объявите необязательные разрешения в манифесте расширения с помощью ключа optional_permissions, используя тот же формат, что и для поля permissions:

{
  "name": "My extension",
  ...
  "optional_permissions": ["tabs"],
  "optional_host_permissions": ["https://www.google.com/"],
  ...
}

Если вы хотите запрашивать хосты, которые обнаруживаются только во время выполнения, включите "https://*/*" в поле optional_host_permissions расширения. Это позволяет указать любой источник в Permissions.origins, если у него есть соответствующая схема.

Разрешения, которые нельзя указать как необязательные

Большинство разрешений для расширений Chrome можно указать как необязательные, за исключением следующих:

Разрешение Описание
"debugger" API chrome.debugger служит альтернативным транспортом для протокола удаленной отладки Chrome.
"declarativeNetRequest" Предоставляет расширению доступ к API chrome.declarativeNetRequest.
"devtools" Позволяет расширению дополнять функциональность инструментов разработчика Chrome.
"experimental" Только в версиях Canary и для разработчиков. Предоставляет расширению доступ к API chrome.experimental.
"geolocation" Разрешает расширению использовать API геолокации HTML5.
"mdns" Предоставляет расширению доступ к API chrome.mdns.
"proxy" Предоставляет расширению доступ к API chrome.proxy для управления настройками прокси-сервера Chrome.
"tts" API chrome.tts воспроизводит синтезированную речь.
"ttsEngine" chrome.ttsEngine API реализует механизм преобразования текста в речь (TTS) с помощью расширения.
"wallpaper" Только для ChromeOS. Используйте API chrome.wallpaper, чтобы изменить обои ChromeOS.

Дополнительную информацию о доступных разрешениях и предупреждениях можно найти в статье Объявление разрешений и предупреждение пользователей.

Шаг 3. Запросите необязательные разрешения

Запросите разрешения в рамках жеста пользователя с помощью permissions.request():

document.querySelector('#my-button').addEventListener('click', (event) => {
  // Permissions must be requested from inside a user gesture, like a button's
  // click handler.
  chrome.permissions.request({
    permissions: ['tabs'],
    origins: ['https://www.google.com/']
  }, (granted) => {
    // The callback argument will be true if the user granted the permissions.
    if (granted) {
      doSomething();
    } else {
      doSomethingElse();
    }
  });
});

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

Пример запроса на подтверждение разрешения

Шаг 4. Проверьте текущие разрешения расширения

Чтобы проверить, есть ли у расширения определенное разрешение или набор разрешений, используйте permission.contains():

chrome.permissions.contains({
  permissions: ['tabs'],
  origins: ['https://www.google.com/']
}, (result) => {
  if (result) {
    // The extension has the permissions.
  } else {
    // The extension doesn't have the permissions.
  }
});

Шаг 5. Удалите разрешения

Если разрешения больше не нужны, их следует удалить. После удаления разрешения вызов permissions.request() обычно добавляет его обратно без запроса пользователю.

chrome.permissions.remove({
  permissions: ['tabs'],
  origins: ['https://www.google.com/']
}, (removed) => {
  if (removed) {
    // The permissions have been removed.
  } else {
    // The permissions have not been removed (e.g., you tried to remove
    // required permissions).
  }
});

Типы

Permissions

Свойства

  • источники

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

    Список разрешений хоста, включая указанные в ключах optional_permissions или permissions в манифесте, а также связанные со скриптами контента.

  • разрешения

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

    Список именованных разрешений (не включает хосты и источники).

Методы

contains()

Promise 
chrome.permissions.contains(
  permissions: Permissions,
  callback?: function,
): Promise<boolean>

Проверяет, есть ли у расширения указанные разрешения.

Параметры

  • разрешения

    Разрешения

  • обратный вызов

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

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

    (result: boolean) => void

    • Результат

      Логическое значение

      True, если у расширения есть указанные разрешения. Если источник указан и как необязательное разрешение, и как шаблон соответствия скрипта контента, будет возвращено значение false, пока не будут предоставлены оба разрешения.

Возвраты

  • Promise<boolean>

    Chrome 96 и более поздних версий;

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

getAll()

Promise 
chrome.permissions.getAll(
  callback?: function,
): Promise<Permissions>

Получает текущий набор разрешений расширения.

Параметры

  • обратный вызов

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

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

    (permissions: Permissions) => void

    • разрешения

      Разрешения

      Активные разрешения расширения. Обратите внимание, что свойство origins будет содержать источники, указанные в ключах permissions и optional_permissions в манифесте, а также источники, связанные со скриптами контента.

Возвраты

  • Promise<Permissions>

    Chrome 96 и более поздних версий;

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

remove()

Promise 
chrome.permissions.remove(
  permissions: Permissions,
  callback?: function,
): Promise<boolean>

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

Параметры

  • разрешения

    Разрешения

  • обратный вызов

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

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

    (removed: boolean) => void

    • удалено

      Логическое значение

      Возвращает значение "истина", если разрешения были удалены.

Возвраты

  • Promise<boolean>

    Chrome 96 и более поздних версий;

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

request()

Promise 
chrome.permissions.request(
  permissions: Permissions,
  callback?: function,
): Promise<boolean>

Запрашивает доступ к указанным разрешениям, при необходимости показывая пользователю запрос. Эти разрешения должны быть определены в поле optional_permissions манифеста или быть обязательными разрешениями, которые пользователь не предоставил. Пути в шаблонах источников игнорируются. Вы можете запрашивать подмножества необязательных разрешений для источников. Например, если вы укажете *://*\/* в разделе optional_permissions манифеста, то сможете запросить http://example.com/. Если при запросе разрешений возникнут проблемы, объект Promise будет отклонен.

Параметры

  • разрешения

    Разрешения

  • обратный вызов

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

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

    (granted: boolean) => void

    • granted

      Логическое значение

      True, если пользователь предоставил указанные разрешения.

Возвраты

  • Promise<boolean>

    Chrome 96 и более поздних версий;

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

События

onAdded

chrome.permissions.onAdded.addListener(
  callback: function,
)

Срабатывает, когда расширение получает новые разрешения.

Параметры

  • обратный вызов

    function

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

    (permissions: Permissions) => void

onRemoved

chrome.permissions.onRemoved.addListener(
  callback: function,
)

Срабатывает, когда у расширения отзываются разрешения.

Параметры

  • обратный вызов

    function

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

    (permissions: Permissions) => void