Использование API разрешений

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

Разрешения в веб-среде — это необходимое зло, но для разработчиков они не являются приятной задачей.

Исторически различные API обрабатывали разрешения несогласованно — например, API уведомлений имели свои собственные методы проверки статуса разрешения и запроса разрешения, в то время как API геолокации этого не делал.

API разрешений предоставляет согласованный подход для разработчиков и позволяет им реализовать более удобный пользовательский интерфейс в отношении разрешений. В частности, разработчики могут использовать Permissions.query() для проверки, предоставлено ли разрешение на использование конкретного API в текущем контексте, отклонено ли оно или требуется ли специальное разрешение пользователя через запрос. Запрос разрешений в главном потоке широко поддерживается, а также в рабочих потоках (с заметным исключением).

Многие API теперь позволяют запрос разрешений, такие как API буфера обмена, API уведомлений, API push-уведомлений и Web MIDI API. Список многих API, поддерживающих разрешения, представлен в Обзоре API, а представление о поддержке браузерами вы можете получить в таблице совместимости здесь.

Permissions имеет другие методы для конкретного запроса разрешения на использование API и для отзыва разрешения, но они устарели (нестандартны и/или не широко поддерживаются).

Для этой статьи мы подготовили простую демонстрацию под названием «Поиск местоположения». Она использует геолокацию для запроса текущего местоположения пользователя и отображения его на карте Google:

Вы можете запустить пример онлайн или просмотреть исходный код на GitHub. Большая часть кода простая и не примечательная — ниже мы пройдемся только по коду, связанному с API разрешений, поэтому проверьте код самостоятельно, если хотите изучить какие-либо другие части.

Свойство Navigator.permissions было добавлено в браузер для доступа к глобальному объекту Permissions. В конечном итоге этот объект будет содержать методы для запроса, запроса и отзыва разрешений, хотя в настоящее время он содержит только Permissions.query(); см. ниже.

В нашем примере функциональность разрешений обрабатывается одной функцией — handlePermission(). Она начинается с запроса статуса разрешения с помощью Permissions.query(). В зависимости от значения свойства state объекта PermissionStatus, возвращаемого при разрешении обещания, она реагирует по-разному:

"granted"

Кнопка «Включить геолокацию» скрыта, так как она не нужна, если геолокация уже активна.

"prompt"

Кнопка «Включить геолокацию» скрыта, так как она не нужна, если пользователю будет предложено предоставить разрешение на геолокацию. Затем выполняется функция Geolocation.getCurrentPosition(), которая запрашивает разрешение у пользователя; она выполняет функцию revealPosition(), если разрешение предоставлено (что отображает карту), или функцию positionDenied(), если разрешение отклонено (что отображает кнопку «Включить геолокацию»).

"denied"

Кнопка «Включить геолокацию» отображается (этот код также необходим, если состояние разрешения уже установлено как отклоненное для этого источника при первой загрузке страницы).

function handlePermission() {
  navigator.permissions.query({ name: "geolocation" }).then((result) => {
    if (result.state === "granted") {
      report(result.state);
      geoBtn.style.display = "none";
    } else if (result.state === "prompt") {
      report(result.state);
      geoBtn.style.display = "none";
      navigator.geolocation.getCurrentPosition(
        revealPosition,
        positionDenied,
        geoSettings,
      );
    } else if (result.state === "denied") {
      report(result.state);
      geoBtn.style.display = "inline";
    }
    result.addEventListener("change", () => {
      report(result.state);
    });
  });
}

function report(state) {
  console.log(`Permission ${state}`);
}

handlePermission();

Метод Permissions.query() принимает PermissionDescriptor словарь в качестве параметра — он содержит имя API, которое вас интересует. Некоторые API имеют более сложные PermissionDescriptor с дополнительной информацией, которые наследуют от стандартного PermissionDescriptor. Например, PushPermissionDescriptor также должен содержать булево значение, указывающее, является ли userVisibleOnly true или false.

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