Ограничения платформы
Виджет работает в жёстких рамках: маленький размер, песочница без сети, ограниченный набор HTML, CSS и JavaScript. Всё, что в эти рамки не входит, приложение Telegram убирает молча — виджет не падает, но выглядит и работает не так, как задумано. Шаблоны Widgram в эти рамки уже уложены; эта страница нужна тем, кто пишет виджет сам или хочет понять, почему шаблон устроен именно так.
Лимиты
| Что | Лимит |
|---|---|
| Код виджета | 32 768 байт в UTF-8 |
| Код после сжатия | 4 096 байт (zlib, уровень 9) |
| Состояние чата и общее состояние | по 1 024 байт |
| Запрос к боту | от 1 до 64 байт |
| Ответ бота | до 1 024 байт |
| Время на ответ | 15 секунд |
| Запросы от одного человека | 5 за 5 секунд |
| Обновление общего виджета | 1 раз в секунду |
| Период обновления общего виджета | 30 секунд по умолчанию, от 5 до 3 600 |
| Размер виджета | ширина от 200 px до ширины пузыря, высота 50–600 px |
| Хранилище на устройстве | 4 096 байт на область |
| Копируемый текст | до 256 символов, по нажатию |
| Адрес ссылки | до 256 символов |
| Узлы документа | 2 000 |
| Правила CSS | 400 правил и 32 анимаций @keyframes |
| Тяжёлые элементы (размытая тень, фильтр, прозрачность) | 16 одновременно |
| Таймеры | 64 одновременно |
| Процессорное время | 300 мс работы скрипта в секунду |
| Память | 8 МБ |
Размер после сжатия — главный лимит: в 4 096 байт должны поместиться и вёрстка, и стили, и вся логика. Проверка кода считает его так, как описано в руководстве Telegram: zlib, уровень 9.
Что приложение вырежет
- Поля ввода.
input,select,textareaудаляются вместе с содержимым. Единственный элемент управления —button. Клавиатуры нет. - Всё внешнее. Скрипты, стили, шрифты и картинки по ссылке не загружаются. Картинки — только
data:в форматах PNG, JPEG, GIF и WebP или встроенный SVG. - Сеть.
fetch,XMLHttpRequest,WebSocketи остальные сетевые вызовы бросают ошибку. Единственный выход наружу — запрос к боту. - Часть CSS. Единицы
vh, прокрутка (overflow: autoиscrollстановятсяhidden),position: sticky, 3D-трансформации,text-shadow,clip-path,:has(),@font-face,@import, вложенные правила, современные функции цвета вродеoklch(). - Именованные шрифты. Работают только общие семейства:
system-ui,sans-serif,serif,monospace. - Диалоги и буфер обмена.
alert,confirmиpromptничего не показывают,navigator.clipboardнедоступен. Скопировать текст можно методомTelegramWidget.copyText— по нажатию. - События клавиатуры, колеса и касаний. Вместо событий касаний — события указателя.
Что работает
- Обычная разметка: блоки, заголовки, списки, таблицы,
details,button,canvas, встроенный SVG. - Flexbox и grid, градиенты, скругления, тени, переходы и анимации
@keyframes. - Цвета темы чата — в переменных CSS
--tg-theme-*;prefers-color-schemeиprefers-reduced-motion. - JavaScript стандарта ES2023, таймеры,
requestAnimationFrame,localStorageв пределах лимита. - Объект
TelegramWidget: состояние, запрос к боту, зритель, ссылки, копирование текста.
Правила, которые мы соблюдаем в шаблонах
- Только цвета темы и относительные размеры: виджет выглядит как сообщение в светлой и тёмной теме.
- Высота не больше 560 px при ширине 320 px: всё, что выше 600 px, приложение обрежет.
- В правом нижнем углу ничего нажимаемого: там время сообщения.
- Данные автора попадают на страницу только как текст, а секреты — верные ответы, промокоды, веса колеса — остаются на сервере: код виджета публичен.
- Первый кадр рисуется сразу из состояния: приложение может уничтожить и создать виджет заново в любой момент.
Источник: официальное руководство Telegram по виджетам, профиль виджета 1. Правила задаёт Telegram и может их менять; если эта страница расходится с руководством, верно руководство.