Сайт ничего не знает о батарее устройства, пока сам не спросит. Battery Status API (интерфейс состояния батареи) отвечает на этот вопрос: какой сейчас заряд, подключена ли зарядка и сколько осталось до полной зарядки или до отключения. Для запроса не нужны библиотеки и диалог с разрешением — достаточно одного вызова navigator.getBattery().

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

Зачем сайту знать про батарею

Показывать процент заряда ради процента бессмысленно — его и так видно в углу экрана. Ценность в том, чтобы подстроить поведение страницы под ситуацию пользователя:

  • облегчённый режим — при низком заряде выключить фоновые анимации, параллакс, автозапуск видео, частые опросы сервера;
  • предупреждение перед долгой операцией — экспорт видео, сборка большого отчёта или загрузка файла могут не успеть закончиться, если ноутбук вот-вот уснёт;
  • страховка для черновиков — в редакторе или длинной форме при заряде ниже 10 % стоит чаще сохранять введённое и подсказать пользователю, что пора подключить зарядку;
  • веб-игры и тяжёлые визуализации — снизить частоту кадров или качество графики, пока устройство работает от батареи.

Все эти сценарии — прогрессивное улучшение: если данных нет, страница просто работает в обычном режиме. Это важно, потому что данных не будет довольно часто (подробности ниже).

Сначала — проверка поддержки

Метод getBattery есть не во всех браузерах, поэтому перед вызовом проверяем, существует ли он. Удобнее всего через оператор in:

if ('getBattery' in navigator) {
  // API есть, можно запрашивать данные
} else {
  // данных о батарее не будет, работаем как обычно
}

Картина поддержки сложилась необычная. Chromium-браузеры (Chrome, Edge, Opera) реализовали API давно и не убирали. А вот Firefox умел работать с батареей, но с 52-й версии закрыл доступ из соображений приватности. Safari не реализовывал API никогда, в том числе на iOS. Значит, на всех айфонах и у всех пользователей Firefox ветка else — это норма, а не редкий случай.

Есть ещё три условия, при которых API не сработает даже в Chrome:

  • только безопасный контекст — страница должна открываться по HTTPS (защищённому протоколу) или с localhost. На обычном HTTP метода getBattery в navigator просто нет, и проверка выше вернёт false;
  • только основной поток — в Web Worker (фоновом скрипте) интерфейса нет, данные о батарее читаем на самой странице и при необходимости передаём воркеру через postMessage;
  • Permissions Policy (политика разрешений) — в актуальной редакции спецификации доступ к батарее управляется ключом battery. По умолчанию он разрешён только своему источнику: скрипту внутри чужого <iframe> нужен атрибут allow="battery", а заголовок Permissions-Policy: battery=() запрещает API на всей странице. Если доступ закрыт, промис отклоняется с ошибкой NotAllowedError.

Отсюда вывод: даже если метод есть, вызов нужно оборачивать в try...catch.

Что возвращает getBattery()

Метод не отдаёт данные сразу, а возвращает промис. Когда браузер получит сведения от системы, промис выполнится с объектом BatteryManager. С async/await это выглядит так:

async function readBattery() {
  if (!('getBattery' in navigator)) return null;

  try {
    const battery = await navigator.getBattery();
    const percent = Math.round(battery.level * 100);

    console.log(`Заряд: ${percent}%`);
    console.log(battery.charging ? 'Заряжается' : 'Работает от батареи');

    return battery;
  } catch (error) {
    // например, NotAllowedError внутри iframe без allow="battery"
    console.warn('Нет доступа к батарее:', error.name);
    return null;
  }
}

readBattery();

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

У BatteryManager четыре свойства, все только для чтения:

Свойство Что содержит Пример значения
level уровень заряда, дробь от 0 до 1 (не проценты) 0.47 — это 47 %
charging подключена ли зарядка, булевое значение true
chargingTime секунды до полной зарядки 3240 — 54 минуты
dischargingTime секунды до полной разрядки Infinity, если идёт зарядка

Ловушка: Infinity, 0 и «вечно полная» батарея

С временем работы нужно быть внимательным. Если устройство разряжается, chargingTime равен Infinity, а если заряжается — Infinity окажется в dischargingTime. Та же бесконечность приходит, когда система просто не может оценить время. Выводить такое значение напрямую нельзя — пользователь увидит «Infinity мин».

Вторая особенность менее очевидна. Если браузер не может получить данные о батарее (например, на настольном компьютере, где батареи нет вовсе), он не выдаёт ошибку, а изображает полностью заряженную батарею на зарядке: level равен 1, charging — true, chargingTime — 0. Отличить «ноутбук на 100 % у розетки» от «батареи нет» по этим данным невозможно. На практике это значит одно: решения принимаем только на основе низкого заряда без зарядки, а «всё в порядке» считаем поведением по умолчанию.

Небольшая функция для перевода секунд в понятный текст с учётом бесконечности:

function formatDuration(seconds) {
  if (!Number.isFinite(seconds)) return 'неизвестно';
  if (seconds === 0) return 'готово';

  const hours = Math.floor(seconds / 3600);
  const minutes = Math.floor((seconds % 3600) / 60);

  return hours > 0 ? `${hours} ч ${minutes} мин` : `${minutes} мин`;
}

formatDuration(8100);     // '2 ч 15 мин'
formatDuration(1500);     // '25 мин'
formatDuration(Infinity); // 'неизвестно'

Следим за изменениями

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

  • levelchange — изменился уровень заряда;
  • chargingchange — зарядку подключили или отключили;
  • chargingtimechange — пересчиталось время до полной зарядки;
  • dischargingtimechange — пересчиталось время до разрядки.

Можно назначать обработчики через свойства вида battery.onlevelchange, но addEventListener удобнее: подписчиков может быть несколько, и их легко снять. Удобный приём — одна функция отрисовки на все события:

const battery = await navigator.getBattery();

function render() {
  const percent = Math.round(battery.level * 100);
  const time = battery.charging
    ? `до полной: ${formatDuration(battery.chargingTime)}`
    : `осталось: ${formatDuration(battery.dischargingTime)}`;

  console.log(`${percent}% · ${time}`);
}

['levelchange', 'chargingchange', 'chargingtimechange', 'dischargingtimechange']
  .forEach((type) => battery.addEventListener(type, render));

render(); // первая отрисовка — сразу, не дожидаясь событий

Обратите внимание на последний вызов render(): события приходят только при изменениях, а уровень заряда меняется медленно — на ноутбуке у розетки можно ждать первого levelchange несколько минут. Без начальной отрисовки индикатор всё это время будет пустым.

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

Собираем индикатор с предупреждением

Соберём всё в небольшой виджет: процент, полоса заряда, статус и предупреждение, когда заряд опускается ниже 15 % без подключённой зарядки. Разметка минимальная:

<div class="battery" hidden>
  <div class="battery__bar"><span class="battery__fill"></span></div>
  <p class="battery__info"></p>
  <p class="battery__warning" hidden>Заряд ниже 15% — подключите зарядку</p>
</div>

Блок по умолчанию скрыт атрибутом hidden и появляется, только если данные удалось получить. В Firefox и Safari пользователь просто не увидит индикатор, и это правильно.

const LOW_LEVEL = 0.15;

async function initBatteryWidget(root) {
  if (!('getBattery' in navigator)) return;

  let battery;
  try {
    battery = await navigator.getBattery();
  } catch {
    return;
  }

  const fill = root.querySelector('.battery__fill');
  const info = root.querySelector('.battery__info');
  const warning = root.querySelector('.battery__warning');

  function update() {
    const percent = Math.round(battery.level * 100);
    const isLow = battery.level <= LOW_LEVEL && !battery.charging;

    fill.style.width = `${percent}%`;
    info.textContent = battery.charging
      ? `${percent}% · заряжается, до полной: ${formatDuration(battery.chargingTime)}`
      : `${percent}% · от батареи, осталось: ${formatDuration(battery.dischargingTime)}`;

    warning.hidden = !isLow;
    root.classList.toggle('battery--low', isLow);
  }

  ['levelchange', 'chargingchange', 'chargingtimechange', 'dischargingtimechange']
    .forEach((type) => battery.addEventListener(type, update));

  update();
  root.hidden = false;
}

initBatteryWidget(document.querySelector('.battery'));

Предупреждение здесь — элемент на странице, а не alert(). Модальное окно браузера блокирует страницу и выскакивало бы при каждом изменении уровня ниже порога, а плашка спокойно появляется и исчезает вместе с подключением зарядки.

Облегчённый режим при низком заряде

Самое полезное применение API — не показывать заряд, а экономить его. Идея простая: при низком заряде без зарядки ставим на <html> класс, а в CSS по этому классу отключаем всё тяжёлое.

async function watchPowerSaving(threshold = 0.2) {
  if (!('getBattery' in navigator)) return;

  try {
    const battery = await navigator.getBattery();

    const sync = () => {
      const save = battery.level <= threshold && !battery.charging;
      document.documentElement.classList.toggle('power-saving', save);
    };

    battery.addEventListener('levelchange', sync);
    battery.addEventListener('chargingchange', sync);
    sync();
  } catch {
    // нет доступа — остаёмся в обычном режиме
  }
}

watchPowerSaving();
.power-saving .hero-video {
  display: none;
}

.power-saving *,
.power-saving *::before,
.power-saving *::after {
  animation-play-state: paused !important;
  transition: none !important;
}

Тот же класс можно читать и в JS: реже опрашивать сервер, не подгружать тяжёлые превью, снижать частоту кадров в requestAnimationFrame-цикле. Хорошая пара для этого приёма — медиа-запрос prefers-reduced-motion: он отвечает за явное желание пользователя видеть меньше движения, а класс power-saving — за временную ситуацию с батареей.

Приватность и границы применения

Почему Firefox и Safari отказались от API, которое выглядит безобидно? Дело в fingerprinting (снятии «отпечатка» браузера для слежки без cookies). В исследовании «The leaking battery» показали, что точные значения уровня заряда и оставшегося времени меняются почти синхронно на всех открытых сайтах. Сочетание этих чисел на короткое время становится уникальным идентификатором устройства, и по нему можно связать визиты одного человека на разные сайты, даже если он почистил cookies или открыл приватное окно. После этого в спецификацию добавили рекомендацию огрублять значения, а Firefox убрал API целиком.

Из этого следует несколько практических правил:

  • данные о батарее — подсказка, а не источник истины: никакая важная логика не должна зависеть от того, ответил ли API;
  • не отправляйте уровень заряда в аналитику и на сервер без реальной необходимости — это ровно тот сценарий, из-за которого API ограничили;
  • не делайте выводов о пользователе по заряду (вроде «раз батарея садится, человек спешит — покажем дороже»): пользователь об этом не знает и не может от этого отказаться;
  • помните, что пользователь ни на что не соглашался: в отличие от геолокации, у Battery Status API нет запроса разрешения, поэтому ответственность за аккуратное использование лежит целиком на разработчике.

Про интерфейс, который, наоборот, всегда спрашивает разрешение и требует аккуратной подачи запроса, есть отдельная статья — как узнать местоположение пользователя и не получить отказ.

Коротко

  • navigator.getBattery() возвращает промис с объектом BatteryManager: level, charging, chargingTime, dischargingTime.
  • Работает только в Chromium-браузерах, только по HTTPS и только в основном потоке; вызов оборачиваем в проверку и try...catch.
  • Время бывает Infinity, а при отсутствии данных браузер изображает полную батарею на зарядке — реагируем только на низкий заряд без зарядки.
  • Обновления приходят событиями levelchange, chargingchange, chargingtimechange и dischargingtimechange; первую отрисовку делаем сразу.
  • Лучшее применение — облегчённый режим и бережное отношение к данным пользователя, а не процент на экране.