Собираем экран с прокручиваемой формой
Добавьте viewport-fit=cover в meta viewport и подключите скрипт Telegram до скрипта приложения. Сохраните три блока ниже как index.html, app.css и app.js. Это демонстрация вёрстки: форма покажет сообщение в интерфейсе, а запрос к серверу вы добавите в обработчик отправки.
<!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.
: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.
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'). Проверьте верх и низ в портретном режиме, а также левый и правый края после поворота.
Проверяем на iPhone и Android
Откройте приложение в Telegram на iPhone и Android. Сверните и разверните окно. Нижняя кнопка должна оставаться доступной, а форма — прокручиваться.
Нажмите на последнее поле, наберите несколько строк и закройте клавиатуру. Проверьте каретку, кнопку и возврат формы к исходной высоте.
Переключите тему Telegram. Проверьте читаемость текста, подсказок, границ полей и кнопки в обеих темах.
На телефоне с вырезом или жестовой навигацией проверьте края экрана после поворота. Повторите проверку в компактном и развёрнутом окне, если приложение поддерживает оба режима.