Эта страница переведена с помощью Cloud Translation API.

chrome.permissions

Описание

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

Понятия и применение

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

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

Дополнительная кнопка, активирующая дополнительные функции.

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

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

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

Шаг 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 .
`"geolocation"`	Позволяет расширению использовать API геолокации HTML5.
`"mdns"`	Предоставляет расширению доступ к API chrome.mdns .
`"proxy"`	Предоставляет расширению доступ к API chrome.proxy для управления настройками прокси Chrome.
`"tts"`	API chrome.tts воспроизводит синтезированную речь (TTS).
`"ttsEngine"`	API chrome.ttsEngine реализует механизм преобразования текста в речь (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

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

происхождение
строка[] необязательный
Список разрешений хоста, включая те, которые указаны в ключах optional_permissions или permissions в манифесте, а также те, которые связаны с Content Scripts .
разрешения
строка[] необязательный
Список именованных разрешений (не включает хосты или источники).

Методы

addHostAccessRequest()

Chrome 133+ MV3+

chrome.permissions.addHostAccessRequest(
  request: object,
): Promise<void>

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

Параметры

запрос
объект
- documentId
  строка необязательный
  Идентификатор документа, в котором могут отображаться запросы доступа к хосту. Должен быть документом верхнего уровня во вкладке. Если указан, запрос отображается на вкладке указанного документа и удаляется при переходе документа на новый источник. Добавление нового запроса переопределит любой существующий запрос для tabId . Необходимо указать либо этот параметр, либо tabId .
- шаблон
  строка необязательный
  Шаблон URL-адреса, по которому могут отображаться запросы на доступ к хосту. Если указан, запросы на доступ к хосту будут отображаться только для URL-адресов, соответствующих этому шаблону.
- tabId
  число необязательно
  Идентификатор вкладки, где могут отображаться запросы доступа к хосту. Если указан, запрос отображается на указанной вкладке и удаляется при переходе на новый источник. Добавление нового запроса переопределит существующий запрос для documentId . Необходимо указать либо этот идентификатор, либо documentId .

Возвраты

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

contains()

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

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

Параметры

разрешения
Разрешения

Возвраты

Promise<boolean>
Chrome 96+

getAll()

chrome.permissions.getAll(): Promise<Permissions>

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

Возвраты

Promise< Permissions >
Chrome 96+

remove()

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

Удаляет доступ к указанным разрешениям. В случае возникновения проблем с удалением разрешений, промис будет отклонен.

Параметры

разрешения
Разрешения

Возвраты

Promise<boolean>
Chrome 96+

removeHostAccessRequest()

Chrome 133+ MV3+

chrome.permissions.removeHostAccessRequest(
  request: object,
): Promise<void>

Удаляет запрос на доступ к хосту, если таковой существует.

Параметры

запрос
объект
- documentId
  строка необязательный
  Идентификатор документа, запрос на доступ к которому будет удален. Должен быть документом верхнего уровня в вкладке. Необходимо указать либо этот идентификатор, либо tabId .
- шаблон
  строка необязательный
  Шаблон URL-адреса, с которого будет удален запрос на доступ к хосту. Если указан, он должен точно соответствовать шаблону существующего запроса на доступ к хосту.
- tabId
  число необязательно
  Идентификатор вкладки, с которой будет удален запрос на доступ к хосту. Необходимо указать либо этот идентификатор, либо documentId .

Возвраты

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

request()

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

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

Параметры

разрешения
Разрешения

Возвраты

Promise<boolean>
Chrome 96+

События

onAdded

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

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

Параметры

перезвонить
функция
Параметр callback выглядит следующим образом:
```
(permissions: Permissions) => void
```
- разрешения
  Разрешения

onRemoved

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

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

Параметры

перезвонить
функция
Параметр callback выглядит следующим образом:
```
(permissions: Permissions) => void
```
- разрешения
  Разрешения

chrome.permissions Оптимизируйте свои подборки Сохраняйте и классифицируйте контент в соответствии со своими настройками.

Описание

Понятия и применение

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

Шаг 1: Определите, какие разрешения являются обязательными, а какие — необязательными.

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

Шаг 3: Запрос дополнительных разрешений

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

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

Типы

Permissions

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

Методы

addHostAccessRequest()

Параметры

Возвраты

contains()

Параметры

Возвраты

getAll()

Возвраты

remove()

Параметры

Возвраты

removeHostAccessRequest()

Параметры

Возвраты

request()

Параметры

Возвраты

События

onAdded

Параметры

onRemoved

Параметры

chrome.permissions