Форма заказа в Telegram Mini App может выглядеть исправно до тех пор, пока пользователь не поставит курсор в последнее поле. На телефоне появляется экранная клавиатура, полезная высота уменьшается, а кнопка подтверждения или сообщение об ошибке оказывается вне видимой области. Пользователь нажимает повторно, теряет заполненные данные либо вообще не понимает, оформлен ли заказ. Это не только визуальная проблема: неверная обработка кнопки способна создать повторную заявку.
Решение нужно проверять внутри Telegram на реальных устройствах. Скриншот веб-страницы в обычном браузере не показывает весь жизненный цикл встроенного окна, переключения клавиатуры, системных отступов и нижней кнопки интерфейса. Цель приёмки — гарантировать доступность действия и ошибки при короткой и длинной форме, не используя опасные догадки о высоте экрана.
Что именно меняется при появлении клавиатуры
У Mini App есть видимая область viewport и события её изменения. В официальной документации Telegram различаются текущая высота viewportHeight и высота последнего устойчивого состояния viewportStableHeight. Текущее значение может изменяться во время жестов и анимаций, поэтому использовать его как непрерывно обновляемую координату закреплённой кнопки ненадёжно. Стабильную высоту и событие viewportChanged можно учитывать после завершения изменения окна.
Кроме высоты есть безопасные зоны: системные области, вырезы экрана и нижние элементы интерфейса. Доступные API Telegram для отступов следует использовать с проверкой поддержки конкретной версии клиента и платформы; нельзя просто вычесть произвольные 50 пикселей и считать результат универсальным. При отсутствии доступного значения система должна сохранять рабочую адаптивную компоновку с прокруткой и достаточными внутренними отступами.
Кнопку подтверждения можно разместить в содержимом Mini App либо использовать поддерживаемую Telegram нижнюю кнопку MainButton / BottomButton. Это разные сценарии. Для встроенной кнопки нужно управлять видимостью, текстом, состоянием доступности и однократной обработкой подтверждения. Для HTML-кнопки нельзя перекрывать полями и клавиатурой последний доступный участок прокрутки. Наличие API не освобождает от теста на iOS и Android.
Как спроектировать форму заказа, а не только её низ
Сначала отделите обязательные поля от необязательных и определите момент валидации. Для короткой формы достаточно имени, контакта и одного выбора. Для длинной добавляются адрес, комментарий, несколько позиций и подтверждение условий. При ошибке система должна показать конкретное поле, сохранить другие значения и направить фокус так, чтобы сообщение оставалось видимым, а не пряталось за клавиатурой.
Полезны три независимых состояния: «заполняется», «проверяется перед отправкой», «отправлено и подтверждено сервером». Нажатие на кнопку запускает проверку, но ещё не означает оформленный заказ. Если сеть оборвалась после отправки, приложение должно получить серверный статус по идентификатору заявки; повторное нажатие без защиты от дублей может породить два заказа. Поэтому алгоритм идемпотентной отправки и уникальный ключ запроса — часть работы разработчика.
В спецификации Telegram-ботов и Mini Apps заранее включайте не только внешний вид формы, но и ошибочные состояния, правила сохранения черновика, отправку и возврат из внешнего сценария. При интеграции с CRM владельцем подтверждённого заказа обычно является серверный процесс, а не визуальное состояние кнопки.
Проверка клавиатуры на мобильном экране имеет полезный аналог: разбор перекрытой формы Tilda объясняет разницу visual/layout viewport, но не является готовым решением для Telegram WebView. Сценарная приёмка адаптивного сайта на телефоне поможет построить тест фокуса, длинных значений и ошибок. Если после ввода открывается платёжный этап, отдельно проверьте серверное подтверждение оплаты после возврата в Mini App: видимость кнопки не доказывает оформление заказа.
Практический тест: две формы и два мобильных клиента
Условный заказ ORD-47 создаётся в Mini App. В короткой форме есть три поля: имя, телефон, способ получения. В длинной — ещё адрес из трёх строк, две позиции и комментарий. У тестовой среды есть два клиента — Telegram на iOS и Telegram на Android. До начала теста команда фиксирует версии ОС, Telegram, режимы навигации и ориентацию устройства. Приведённые обозначения учебные, это не результат реальных испытаний.
- Тест A. Короткая форма, курсор в телефоне, клавиатура открыта. Кнопка подтверждения доступна после закрытия клавиатуры либо через предусмотренное безопасное действие, содержимое не перекрывается.
- Тест B. Длинная форма, курсор в последней строке комментария. Пользователь видит поле, может прокрутить его над клавиатурой и открыть сообщение о неверном адресе без потери ранее введённых данных.
- Тест C. Клавиатура закрыта, Mini App свернут и развернут. Макет реагирует на стабильное изменение области и не оставляет кнопку за нижней границей.
- Тест D. Неверный телефон вызывает ошибку именно у этого поля. После исправления один запрос ORD-47 отправляется на сервер один раз даже при двух быстрых нажатиях.
- Тест E. Во время отправки пропадает сеть. После восстановления приложение не отображает «успешно» до проверки статуса ORD-47 и не удаляет черновик без подтверждения.
Для каждого теста запишите устройство, экранный сценарий, видимость полей и кнопок, состояние фокуса, фактический результат и решение о приёмке. Слова «проверили на телефоне» недостаточно: ошибка может проявляться только на длинной форме и конкретном мобильном клиенте. При невозможности воспроизвести условие на одном устройстве статус теста — «не выполнен», а не «пройден».
Что проверить в реализации
Обновляйте расчёт нижнего отступа при изменении области, но не перемещайте кнопку каждую миллисекунду по анимационной высоте. Используйте структуру с реальной прокруткой, заметным фокусом и видимыми подсказками; внутренний прокручиваемый блок не должен конкурировать с прокруткой Telegram-окна. Модальные окна с подтверждением следует испытывать отдельно: клавиатура может остаться открытой, а диалог появиться вне доступной высоты.
Не блокируйте отправку бесконечно при ошибке клиентского API. Если конкретная версия Telegram не предоставляет новые safe-area значения, интерфейс обязан иметь предсказуемый запас и прокручиваемую форму. Данные не должны исчезать после изменения ориентации, возврата с платежа или стандартного изменения высоты окна. Если отправка влияет на деньги или резерв, финальное решение подтверждает сервер.
Приёмочные тесты должны охватывать доступность, в том числе масштабирование текста, контраст состояния ошибки и нажатие без исключительного требования «попасть в крошечную область». Пользователь не обязан закрывать клавиатуру способом, который доступен только на одной ОС. Сообщение о неверном поле должно иметь текстовую причину, а не только красную рамку.
Оценка доработки и границы ответственности
Смета зависит от сложности формы, способов запуска Mini App, версии Telegram SDK, обработки системной кнопки, серверной проверки, CRM-интеграции, количества устройств и языков для проверки. Иногда достаточно изменить компоновку, а иногда ошибка возникает из-за состояния заказа, которое нельзя исправить CSS. Поэтому подрядчику нужны ссылка на тестовое приложение, доступы, список устройств и короткая запись воспроизведения.
В коммерческом предложении по Telegram описаны базовые сценарии и индивидуальная оценка нестандартных интеграций. Не стоит переносить базовую цену разработки на объём, включающий исправление сложной существующей системы, обработку платежей и полное регрессионное тестирование. Приёмка — рабочая короткая и длинная форма, все отрицательные тесты, один подтверждённый заказ и отсутствие потери данных на согласованных устройствах.
Чтобы обсудить исправление, направьте через контакты запись с открытой клавиатурой, версию Telegram, пример тестового заказа и схему передачи данных. Это позволит оценить именно реальную неисправность.