API блокировки экрана

API блокировки экрана предоставляет способ предотвращения затемнения или блокировки экрана устройства, когда приложение должно продолжать работать.

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

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

Существует множество случаев использования для поддержания экрана включенным, включая чтение электронных книг, навигацию по картам, следование рецептам, презентации аудитории, сканирование QR/штрих-кодов или приложения, использующие голосовое или жестом управление, а не сенсорный ввод (стандартный способ поддержания экрана активным).

Вы получаете объект WakeLockSentinel, вызывая метод, основанный на navigator.wakeLock.request() Promise, который разрешается, если платформа позволяет это. Запрос может быть отклонен по ряду причин, включая системные настройки (такие как режим экономии энергии или низкий уровень заряда батареи), или если документ не активен или не виден. Хорошей практикой является сохранение ссылки на объект-сентинель, чтобы приложение могло позже управлять его освобождением.

Сентинель прикреплен к базовой системной блокировке. Его может освободить система, опять же, если уровень заряда батареи слишком низкий или документ не активен или не виден. Его также можно вручную освободить с помощью метода WakeLockSentinel.release(). После освобождения WakeLockSentinel больше нельзя использовать. Если блокировка экрана снова необходима, приложение должно запросить новую.

API блокировки экрана следует использовать для поддержания экрана включенным, чтобы повысить удобство использования. Рекомендуется отображать информацию на интерфейсе, чтобы показать, если блокировка активна, и способ для пользователя отключить её, если это необходимо.

WakeLock

Предотвращает затемнение или блокировку экранов устройств, когда приложение должно продолжать работать.

WakeLockSentinel

Предоставляет маркер для базовой системной блокировки, и если ссылка сохранена, её можно вручную освободить и снова получить. Получите экземпляр объекта, вызвав WakeLock.request.

Navigator.wakeLock Только чтение

Возвращает экземпляр объекта WakeLock, из которого можно получить доступ ко всем остальным функциям.

Permissions-Policy: screen-wake-lock

Доступ к API регулируется директивой Permissions-Policy screen-wake-lock. См. Рекомендации по безопасности ниже.

Этот код проверяет поддержку блокировки экрана и соответственно обновляет пользовательский интерфейс.

if ("wakeLock" in navigator) {
  isSupported = true;
  statusElem.textContent = "Screen Wake Lock API supported!";
} else {
  wakeButton.disabled = true;
  statusElem.textContent = "Wake lock is not supported by this browser.";
}

Следующий пример демонстрирует, как запросить объект WakeLockSentinel. Метод WakeLock.request основан на Promise, поэтому мы можем создать асинхронную функцию, которая, в свою очередь, обновляет пользовательский интерфейс, чтобы отразить, что блокировка экрана активна.

// Create a reference for the Wake Lock.
let wakeLock = null;

// create an async function to request a wake lock
try {
  wakeLock = await navigator.wakeLock.request("screen");
  statusElem.textContent = "Wake Lock is active!";
} catch (err) {
  // The Wake Lock request has failed - usually system related, such as battery.
  statusElem.textContent = `${err.name}, ${err.message}`;
}

Следующий пример демонстрирует, как освободить ранее полученную блокировку экрана.

wakeLock.release().then(() => {
  wakeLock = null;
});

В этом примере пользовательский интерфейс обновляется, если блокировка экрана была освобождена по какой-либо причине (например, переход от активного окна/вкладки).

wakeLock.addEventListener("release", () => {
  // the wake lock has been released
  statusElem.textContent = "Wake Lock has been released";
});

Следующий код повторно получает блокировку экрана в случае, если видимость документа изменилась и блокировка экрана была освобождена.

document.addEventListener("visibilitychange", async () => {
  if (wakeLock !== null && document.visibilityState === "visible") {
    wakeLock = await navigator.wakeLock.request("screen");
  }
});

Вы можете найти полный код на GitHub здесь. Демонстрация здесь использует кнопку для получения и освобождения блокировки, которая, в свою очередь, обновляет пользовательский интерфейс. Пользовательский интерфейс также обновляется, если блокировка экрана освобождена автоматически по любой причине. Есть флажок, который при включении автоматически повторно получит блокировку экрана, если состояние видимости документа изменится и станет видимым снова.

• Освободите блокировку экрана, когда пользователь завершает активность, которая требует постоянно включенного экрана. Например, приложение для билетов, использующее QR-коды для передачи информации о билетах, может получить блокировку экрана, когда QR-код отображается (чтобы код был успешно отсканирован), но затем освободить её. Приложение для презентаций может удерживать блокировку только во время активной презентации, но не когда презентация редактируется.
• Если ваше приложение выполняет длительные загрузки, рассмотрите использование фоновой загрузки.
• Если ваше приложение синхронизирует данные с удалённым сервером, рассмотрите использование фоновой синхронизации.
• Только активные документы могут получить блокировку экрана, а ранее полученные блокировки автоматически освобождаются, когда документ становится неактивным. Поэтому убедитесь, что необходимо повторно получить блокировку экрана, когда документ становится активным (прослушивайте событие visibilitychange).

Доступ к API блокировки экрана контролируется директивой Политики разрешений screen-wake-lock.

При использовании Политики разрешений, список разрешённых значений по умолчанию для screen-wake-lock - self. Это позволяет использовать блокировку экрана в вложенных фреймах одного источника, но предотвращает использование блокировок сторонним контентом. Использование сторонним контентом может быть разрешено сервером, если сначала установить заголовок Permissions-Policy для предоставления разрешения конкретному стороннему источнику.

Permissions-Policy: screen-wake-lock=(self b.example.com)

Затем необходимо добавить атрибут allow="screen-wake-lock" к элементу контейнера фрейма для источников из этого источника:

<iframe src="https://b.example.com" allow="screen-wake-lock"/></iframe>

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

API разрешений screen-wake-lock разрешение может использоваться для проверки того, доступ к использованию блокировки экрана granted, denied или prompt (требует подтверждения пользователя).

• Оставайтесь активными с API блокировки экрана
• Демонстрация API блокировки экрана на glitch