Перейти к содержимому
Widgram

Ограничения платформы

Виджет работает в жёстких рамках: маленький размер, песочница без сети, ограниченный набор 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 и может их менять; если эта страница расходится с руководством, верно руководство.