Как адаптировать отступ под вырез в Telegram Mini App

При разработке Telegram Mini App (TMA) в полноэкранном режиме разработчики сталкиваются с необходимостью учитывать вырез (notch) в верхней части экрана. На разных устройствах его размер и форма отличаются, а штатные кнопки закрытия и сворачивания приложения привязаны именно к этой области. Ручная установка отступа для каждого девайса неэффективна - гораздо удобнее использовать встроенные CSS-переменные.

Почему отступ сверху важен в Telegram Mini App

В полноэкранном режиме TMA контент может заходить под системную панель или вырез камеры. Если не задать корректный отступ, элементы интерфейса (кнопки, текст, меню) окажутся невидными или перекроются. Telegram предоставляет CSS-функцию safe-area-inset-top, которая автоматически возвращает актуальную высоту выреза для текущего устройства.

Использование safe-area-inset-top для адаптации

Свойство safe-area-inset-top - часть спецификации CSS env(). Оно возвращает значение в пикселях, соответствующее безопасной зоне в верхней части экрана. Для работы в Telegram Mini App необходимо добавить в CSS следующий код:

.app-container {
  padding-top: env(safe-area-inset-top);
}

Этот подход гарантирует, что отступ будет меняться динамически в зависимости от модели смартфона (iPhone с «чёлкой», Android с каплевидным вырезом и т.д.).

Дополнительные настройки для кнопок закрытия и сворачивания

Штатные кнопки TMA (закрытие, сворачивание) расположены в верхней части экрана сразу под вырезом. Чтобы ваш интерфейс не перекрывал их, добавьте отступ не только для контента, но и для верхней панели навигации:

.top-bar {
  position: fixed;
  top: 0;
  left: 0;
  right: 0;
  height: calc(env(safe-area-inset-top) + 44px);
  background: #fff;
}

Здесь 44px - примерная высота стандартной панели. Вы можете подобрать своё значение под дизайн приложения.

Поддержка старых браузеров и fallback

Не все версии WebView поддерживают env(). Для обеспечения обратной совместимости используйте fallback-значение:

.app-container {
  padding-top: 20px; /* fallback для старых устройств */
  padding-top: env(safe-area-inset-top);
}

Браузеры, не поддерживающие env(), проигнорируют второе правило и применят отступ 20px. Для самых современных устройств (iPhone X и новее) сработает именно safe-area-inset-top.

Проверка на разных устройствах

После внедрения CSS-переменной обязательно протестируйте Mini App на нескольких устройствах: iPhone с вырезом, Android-смартфоны с разными типами notch, а также на планшетах. Используйте эмуляторы или реальные девайсы. Telegram Desktop не имеет выреза, поэтому там отступ будет равен 0.

Заключение

Адаптация отступа под вырез в Telegram Mini App не требует ручной подстройки под каждое устройство. Достаточно применить CSS env(safe-area-inset-top) и добавить fallback для старых браузеров. Это обеспечит корректное отображение интерфейса и сохранит доступ к системным кнопкам закрытия и сворачивания на любом смартфоне.