gramdocs.tech
Документация

Тема оформления mini-app под клиент Telegram

Подстроишь цвета Mini App под тему Telegram через themeParams и CSS-переменные.

Тема клиента Telegram

Telegram передаёт в Mini App текущую тему пользователя: светлая/тёмная и палитра (themeParams). Те же цвета доступны как CSS-переменные --tg-theme-*. Задача — не хардкодить #ffffff / #000000, а опираться на эти токены, чтобы UI совпадал с чатом.

При смене темы в настройках Telegram клиент шлёт событие themeChanged — можно перекрасить интерфейс без перезагрузки.

CSS-переменные и themeParams

css
/* Базовая тема под Telegram WebApp */
:root {
  color-scheme: light dark;
}

body {
  margin: 0;
  min-height: 100vh;
  background: var(--tg-theme-bg-color, #ffffff);
  color: var(--tg-theme-text-color, #000000);
  font-family: system-ui, sans-serif;
}

a {
  color: var(--tg-theme-link-color, #2481cc);
}

.hint {
  color: var(--tg-theme-hint-color, #999999);
}

.card {
  background: var(--tg-theme-secondary-bg-color, #f1f1f1);
  border-radius: 12px;
  padding: 16px;
}

.section-title {
  color: var(--tg-theme-section-header-text-color, #6d6d71);
}

.danger {
  color: var(--tg-theme-destructive-text-color, #ff3b30);
}

.cta {
  background: var(--tg-theme-button-color, #2481cc);
  color: var(--tg-theme-button-text-color, #ffffff);
  border: 0;
  border-radius: 10px;
  padding: 12px 16px;
}

Подписка на смену темы и синхронизация header/background с клиентом:

typescript
// Telegram WebApp themeParams / setHeaderColor — telegram-web-app.js

const tg = window.Telegram.WebApp;

function applyTheme() {
  const scheme = tg.colorScheme; // "light" | "dark"
  document.documentElement.dataset.colorScheme = scheme;

  // Bot API 6.1+ / 7.0+: цвета хедера и фона WebView
  if (tg.themeParams.bg_color) {
    tg.setBackgroundColor?.(tg.themeParams.bg_color);
  }
  if (tg.themeParams.header_bg_color) {
    tg.setHeaderColor?.(tg.themeParams.header_bg_color);
  }

  console.log({
    colorScheme: scheme,
    bg: tg.themeParams.bg_color,
    text: tg.themeParams.text_color,
    button: tg.themeParams.button_color,
  });
}

tg.ready();
applyTheme();
tg.onEvent("themeChanged", applyTheme);

Как это работает

  • --tg-theme-bg-color и др. — клиент выставляет на :root при загрузке скрипта.
  • themeParams — тот же набор в JS (bg_color, text_color, button_color, …).
  • colorScheme — "light" или "dark"; удобно для своих ассетов (иконки).
  • themeChanged — событие при смене темы в Telegram.
  • setHeaderColor / setBackgroundColor — красят хром WebView, не только твой body.

Частые ошибки

Фиксируешь белый фон в CSS → в тёмной теме «белая дыра». Всегда var(--tg-theme-bg-color, fallback).

Красишь только body, забывая header WebView → шапка Telegram другого цвета. Вызови setHeaderColor / setBackgroundColor.

Игнорируешь themeChanged → после переключения темы в настройках UI остаётся старым, пока не переоткроешь Mini App.

Что дальше

Материалы gramdocs.tech носят образовательный характер и не являются финансовой, юридической или инвестиционной рекомендацией. Работа с блокчейном TON и токеном Gram связана с рисками потери средств. Правовая информация