Перейти к содержанию
12 минут чтения
Тема: Практика Mini Apps · iPhone · Android · CSS

Как адаптировать Telegram Mini App под iPhone и Android

Для примера сделаем экран, на котором покупатель указывает имя и комментарий к заказу. На маленьком экране форма прокручивается, нижняя кнопка остаётся доступной, а цвета меняются вместе с темой Telegram. Этот экран можно использовать и для записи на услугу.

Собираем экран с прокручиваемой формой

Добавьте viewport-fit=cover в meta viewport и подключите скрипт Telegram до скрипта приложения. Сохраните три блока ниже как index.html, app.css и app.js. Это демонстрация вёрстки: форма покажет сообщение в интерфейсе, а запрос к серверу вы добавите в обработчик отправки.

HTML · index.html
<!doctype html>
<html lang="ru">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">
  <title>Контакт для заказа</title>
  <link rel="stylesheet" href="app.css">
  <script src="https://telegram.org/js/telegram-web-app.js"></script>
  <script src="app.js" defer></script>
</head>
<body>
  <form id="contact-form" class="screen">
    <main class="screen__body">
      <h1>Контакт для заказа</h1>
      <label>Имя <input name="name" autocomplete="name" required></label>
      <label>Комментарий <textarea name="comment" rows="5"></textarea></label>
      <p role="status"></p>
    </main>
    <footer class="screen__actions">
      <button type="submit">Продолжить</button>
    </footer>
  </form>
</body>
</html>

Задайте высоту всей оболочки через --tg-viewport-stable-height. При растягивании окна Telegram обновляет это значение после завершения жеста. viewportHeight описывает текущую видимую высоту, но обновляется слишком редко для плавной привязки кнопки к нижней границе. В обычном браузере предусмотрите 100dvh с запасным значением 100vh.

CSS · app.css
:root {
  --browser-height: 100vh;
  color-scheme: light dark;
  font: 16px/1.5 system-ui, sans-serif;
}
@supports (height: 100dvh) {
  :root { --browser-height: 100dvh; }
}
body {
  margin: 0;
  color: var(--tg-theme-text-color, CanvasText);
  background: var(--tg-theme-bg-color, Canvas);
}
.screen {
  box-sizing: border-box;
  block-size: min(
    var(--tg-viewport-stable-height, var(--browser-height)),
    var(--editing-height, 100vh)
  );
  display: grid;
  grid-template-rows: minmax(0, 1fr) auto;
  padding-top: calc(var(--tg-safe-area-inset-top, env(safe-area-inset-top, 0px))
    + var(--tg-content-safe-area-inset-top, 0px));
  padding-left: calc(var(--tg-safe-area-inset-left, env(safe-area-inset-left, 0px))
    + var(--tg-content-safe-area-inset-left, 0px));
  padding-right: calc(var(--tg-safe-area-inset-right, env(safe-area-inset-right, 0px))
    + var(--tg-content-safe-area-inset-right, 0px));
  padding-bottom: calc(var(--tg-safe-area-inset-bottom, env(safe-area-inset-bottom, 0px))
    + var(--tg-content-safe-area-inset-bottom, 0px));
}
.screen__body {
  overflow: auto;
  padding: 16px;
  scroll-padding: 16px;
}
.screen__actions { padding: 12px 16px; }
label { display: grid; gap: 6px; margin-block: 12px; }
input, textarea, button { font: inherit; }
input, textarea {
  color: inherit;
  background: var(--tg-theme-secondary-bg-color, Canvas);
}
button {
  width: 100%;
  min-height: 44px;
  border: 0;
  border-radius: 8px;
  background: var(--tg-theme-button-color, ButtonFace);
  color: var(--tg-theme-button-text-color, ButtonText);
}

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

Учитываем экранную клавиатуру

Когда клавиатура открывается, видимая область может уменьшаться отдельно от основного размера страницы. Пока поле редактируется, ограничьте высоту оболочки значением visualViewport.height, если WebView его предоставляет. После потери фокуса уберите временное ограничение. Дополнительно слушайте viewportChanged, чтобы обработать изменение окна Telegram.

Одна форма при закрытой и открытой клавиатуре: доступная высота уменьшается, кнопка остаётся в отдельной строке.
Одна форма при закрытой и открытой клавиатуре: доступная высота уменьшается, кнопка остаётся в отдельной строке.
Схема на основе HTML/CSS статьи. Клавиатура показана условно; поведение WebView необходимо проверять на реальных устройствах.
JavaScript · app.js
const app = window.Telegram?.WebApp;
const viewport = window.visualViewport;
const root = document.documentElement;
const form = document.querySelector('#contact-form');

function updateTheme() {
  root.style.colorScheme = app?.initData ? app.colorScheme : 'light dark';
}

function fitEditor() {
  const field = document.activeElement;
  const editing = form.contains(field) && field.matches('input, textarea');
  if (editing && viewport?.height > 0) {
    root.style.setProperty('--editing-height', viewport.height + 'px');
    field.scrollIntoView({ block: 'nearest', inline: 'nearest' });
  } else {
    root.style.removeProperty('--editing-height');
  }
}

function fitOnNextFrame() {
  requestAnimationFrame(fitEditor);
}

form.addEventListener('focusin', fitOnNextFrame);
form.addEventListener('focusout', fitOnNextFrame);
viewport?.addEventListener('resize', fitOnNextFrame);
app?.onEvent('viewportChanged', ({ isStateStable }) => {
  if (isStateStable) fitOnNextFrame();
});
app?.onEvent('themeChanged', updateTheme);

form.addEventListener('submit', (event) => {
  event.preventDefault();
  form.querySelector('[role="status"]').textContent = 'Форма заполнена.';
  form.querySelector('[role="status"]').scrollIntoView({ block: 'nearest' });
});

updateTheme();
app?.ready();

Клиенты Telegram по-разному меняют размер видимой области и прокручивают страницу при фокусе. Проверьте на телефоне, видно ли каретку и можно ли дойти до последнего поля. Если закреплённая кнопка отнимает слишком много высоты, перенесите действие внутрь прокручиваемой формы. При отсутствии visualViewport форма продолжит использовать высоту Telegram или браузера.

На версиях с поддержкой hideKeyboard() можно скрыть клавиатуру после явного действия пользователя. Проверьте app.isVersionAtLeast('9.1') и наличие метода. Во время ввода оставьте клавиатуру открытой. expand() разворачивает окно Mini App до доступной высоты и решает другую задачу.

Если после закрытия клавиатуры остаётся пустая полоса, проверьте, снимается ли --editing-height на focusout и пришёл ли resize. Если последнее поле прячется за кнопкой, проверьте высоту .screen__body и наличие minmax(0, 1fr): без разрешённого сжатия содержимое может вытолкнуть нижнюю строку за экран. Эмулятор браузера помогает найти ошибку сетки, но поведение клавиатуры принимайте на настоящем телефоне.

Подстраиваем цвета и безопасные отступы

Переменные --tg-theme-* подставляют цвета темы Telegram. color-scheme синхронизирует системное оформление полей и полос прокрутки. Событие themeChanged нужно для настроек, которые считывает JavaScript. Например, при рисовании на canvas получите свежие app.themeParams и перерисуйте сцену.

Системные отступы safeAreaInset учитывают вырез экрана и элементы ОС. contentSafeAreaInset учитывает элементы Telegram. В примере CSS использует оба набора, а при отсутствии системных переменных Telegram берёт env(safe-area-inset-*) браузера. Добавляйте отступ на одном уровне оболочки и проверяйте, что внутренний блок не учитывает тот же край второй раз.

Если положение элементов рассчитывает JavaScript, обновляйте его при safeAreaChanged и contentSafeAreaChanged. Поддержку этих событий проверяйте через isVersionAtLeast('8.0'). Проверьте верх и низ в портретном режиме, а также левый и правый края после поворота.

Светлая и тёмная версии формы с обозначенными верхним и нижним безопасными отступами.
Светлая и тёмная версии формы с обозначенными верхним и нижним безопасными отступами.
Макет из примера с демонстрационными цветами темы. Цветные полосы поясняют безопасные отступы и не являются элементами интерфейса Telegram.

Выбираем нижнюю кнопку

В примере кнопка принадлежит HTML-форме и работает в браузере. Если хотите использовать нативную нижнюю кнопку Telegram, задайте текст через MainButton.setText(), вызовите show(), а в onClick() передайте обработчик с form.requestSubmit(). Так выполнится встроенная валидация формы. В Telegram оставьте одно основное действие на экране, а HTML-кнопку используйте как запасной вариант в браузере.

При переходе на другой экран снимите обработчик через offClick() с той же функцией и спрячьте кнопку. Пока сохраняется форма, используйте disable() и при необходимости showProgress(). Для оформления заказа дополнительно нужна серверная обработка повторов.

Добавьте этот блок в конец app.js, если выбираете кнопку Telegram. Он использует уже созданные app и form, поэтому второй обработчик отправки формы не нужен. В обычном браузере останется HTML-кнопка. Возвращённую функцию вызывайте при уходе с экрана в одностраничном приложении.

JavaScript · подключение нативной кнопки к той же форме
function mountTelegramButton() {
  const button = app?.initData ? app.MainButton : null;
  const footer = form.querySelector('.screen__actions');
  if (!button) return () => {};
  const submit = () => form.requestSubmit();
  button.setText('Продолжить');
  button.enable();
  button.onClick(submit);
  button.show();
  footer.hidden = true;
  return () => {
    button.offClick(submit);
    button.hideProgress();
    button.hide();
    footer.hidden = false;
  };
}
const unmountTelegramButton = mountTelegramButton();
// При размонтировании экрана вызовите unmountTelegramButton().

Сначала нажмите кнопку с пустым обязательным полем: браузер должен показать ошибку, а обработчик submit не выполниться. Затем заполните поле и убедитесь, что сообщение «Форма заполнена» появляется один раз. При подключении серверного сохранения блокируйте повторный submit переменной busy внутри обработчика и сбрасывайте её в finally; состояние MainButton только отражает эту переменную.

Различайте три состояния формы: ещё не заполнена, отправляется, сохранена. При сетевой ошибке сохраняйте введённые поля и показывайте сообщение рядом с действием, чтобы человек мог повторить попытку. Не закрывайте Mini App до подтверждённого ответа сервера. Сбой ввода и недоступность сервера пользователь должен отличать без открытия консоли.

Проверяем на iPhone и Android

  • Откройте приложение в Telegram на iPhone и Android. Сверните и разверните окно. Нижняя кнопка должна оставаться доступной, а форма — прокручиваться.

  • Нажмите на последнее поле, наберите несколько строк и закройте клавиатуру. Проверьте каретку, кнопку и возврат формы к исходной высоте.

  • Переключите тему Telegram. Проверьте читаемость текста, подсказок, границ полей и кнопки в обеих темах.

  • На телефоне с вырезом или жестовой навигацией проверьте края экрана после поворота. Повторите проверку в компактном и развёрнутом окне, если приложение поддерживает оба режима.

Интерфейс Telegram Mini Apps · Спецификация VisualViewport