外观与主题

Mini App 支持自动适配用户的明暗主题，并提供丰富的主题颜色参数和 CSS 变量。

ThemeParams

ThemeParams 对象包含客户端当前主题的颜色参数。通过 Telegram.WebApp.themeParams 访问。

颜色属性

属性	类型	描述
bg_color	String	背景颜色
text_color	String	主要文字颜色
hint_color	String	提示文字颜色
link_color	String	链接颜色
button_color	String	按钮背景颜色
button_text_color	String	按钮文字颜色
secondary_bg_color	String	次要背景颜色
header_bg_color	String	标题栏背景颜色。Bot API 7.10+
bottom_bar_bg_color	String	底部栏背景颜色。Bot API 7.10+
accent_text_color	String	强调文字颜色。Bot API 7.10+
section_bg_color	String	区块背景颜色。Bot API 7.10+
section_header_text_color	String	区块标题文字颜色。Bot API 7.10+
section_separator_color	String	区块分隔线颜色。Bot API 7.10+
subtitle_text_color	String	副标题文字颜色。Bot API 7.10+
destructive_text_color	String	危险操作文字颜色。Bot API 7.10+

CSS 变量

Mini App SDK 会自动将所有主题颜色注入为 CSS 变量，可直接在样式表中使用：

.my-element {
  background-color: var(--tg-theme-bg-color);
  color: var(--tg-theme-text-color);
}

.my-button {
  background-color: var(--tg-theme-button-color);
  color: var(--tg-theme-button-text-color);
}

.my-link {
  color: var(--tg-theme-link-color);
}

.my-hint {
  color: var(--tg-theme-hint-color);
}

完整 CSS 变量列表：

CSS 变量	对应属性
--tg-theme-bg-color	bg_color
--tg-theme-text-color	text_color
--tg-theme-hint-color	hint_color
--tg-theme-link-color	link_color
--tg-theme-button-color	button_color
--tg-theme-button-text-color	button_text_color
--tg-theme-secondary-bg-color	secondary_bg_color
--tg-theme-header-bg-color	header_bg_color
--tg-theme-bottom-bar-bg-color	bottom_bar_bg_color
--tg-theme-accent-text-color	accent_text_color
--tg-theme-section-bg-color	section_bg_color
--tg-theme-section-header-text-color	section_header_text_color
--tg-theme-section-separator-color	section_separator_color
--tg-theme-subtitle-text-color	subtitle_text_color
--tg-theme-destructive-text-color	destructive_text_color

主题变化监听

Telegram.WebApp.onEvent('themeChanged', () => {
  const theme = Telegram.WebApp.themeParams;
  console.log('背景色:', theme.bg_color);
  console.log('主题模式:', Telegram.WebApp.colorScheme);
});

SafeAreaInset

SafeAreaInset 对象描述了设备安全区域的内边距（如刘海屏、圆角等区域）。通过 Telegram.WebApp.safeAreaInset 访问。Bot API 8.0+

属性	类型	描述
top	Integer	顶部安全区域内边距（像素）
bottom	Integer	底部安全区域内边距（像素）
left	Integer	左侧安全区域内边距（像素）
right	Integer	右侧安全区域内边距（像素）

示例

const inset = Telegram.WebApp.safeAreaInset;
document.body.style.paddingTop = inset.top + 'px';
document.body.style.paddingBottom = inset.bottom + 'px';

ContentSafeAreaInset

ContentSafeAreaInset 对象描述了内容安全区域的内边距（排除 Mini App 自身 UI 元素占用的空间）。通过 Telegram.WebApp.contentSafeAreaInset 访问。Bot API 8.0+

属性	类型	描述
top	Integer	顶部内容安全区域内边距（像素）
bottom	Integer	底部内容安全区域内边距（像素）
left	Integer	左侧内容安全区域内边距（像素）
right	Integer	右侧内容安全区域内边距（像素）

示例

const contentInset = Telegram.WebApp.contentSafeAreaInset;

// 结合设备安全区域使用
const safeInset = Telegram.WebApp.safeAreaInset;
const totalTop = safeInset.top + contentInset.top;

document.querySelector('.content').style.paddingTop = totalTop + 'px';