TelegramProvider

Telegram Mini App 的根 Provider 组件,基于 @tma.js/sdk 封装,自动初始化 SDK 并应用主题。

导入

import { TelegramProvider } from '@xcloud/ui-telegram'

示例

基础使用

将 TelegramProvider 放在应用的根组件中:

import { TelegramProvider } from '@xcloud/ui-telegram'

function App() {
  return (
    <TelegramProvider>
      <YourApp />
    </TelegramProvider>
  )
}

功能说明

TelegramProvider 会自动完成以下初始化工作:

1. 初始化 Mini App SDK - 调用 miniApp.mount() 和 miniApp.ready()
2. 挂载 Viewport - 初始化视口管理
3. 挂载主题参数 - 监听主题变化
4. 应用主题颜色 - 将 Telegram 主题色同步到 CSS 变量

自动主题系统

Provider 会自动将 Telegram 的主题颜色应用到以下 CSS 变量:

--tg-theme-bg-color              /* 背景颜色 */
--tg-theme-text-color            /* 文字颜色 */
--tg-theme-hint-color            /* 提示文字颜色 */
--tg-theme-link-color            /* 链接颜色 */
--tg-theme-button-color          /* 按钮颜色 */
--tg-theme-button-text-color     /* 按钮文字颜色 */
--tg-theme-secondary-bg-color    /* 次要背景色 */
--tg-theme-header-bg-color       /* 标题栏背景色 */
--tg-theme-accent-text-color     /* 强调文字颜色 */
--tg-theme-section-bg-color      /* 分组背景色 */
--tg-theme-section-header-text-color  /* 分组标题文字颜色 */
--tg-theme-subtitle-text-color   /* 副标题文字颜色 */
--tg-theme-destructive-text-color /* 危险操作文字颜色 */

在你的组件中可以直接使用这些变量:

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

自定义主题处理

如果需要自定义主题处理逻辑,可以使用 onThemeChange 回调:

import { TelegramProvider } from '@xcloud/ui-telegram'
import type { ThemeParams } from '@tma.js/sdk'

function App() {
  const handleThemeChange = (theme: ThemeParams) => {
    console.log('Theme changed')
    console.log('Background:', theme.bgColor())
    console.log('Text:', theme.textColor())

    // 自定义主题处理逻辑
    updateCustomTheme(theme)
  }

  return (
    <TelegramProvider onThemeChange={handleThemeChange}>
      <YourApp />
    </TelegramProvider>
  )
}

禁用自动主题应用

如果你想完全自己控制主题,可以禁用自动主题应用:

<TelegramProvider applyTheme={false}>
  <YourApp />
</TelegramProvider>

调试模式

开发环境中可以启用调试模式:

<TelegramProvider debug>
  <YourApp />
</TelegramProvider>

组件 API

TelegramProvider Props

属性	类型	默认值	描述
children	ReactNode	-	子组件
debug	boolean	false	是否启用调试模式
applyTheme	boolean	true	是否自动应用 Telegram 主题到 CSS 变量
onThemeChange	(theme: ThemeParams) => void	-	主题变化回调

与其他组件配合

TelegramProvider 应该与其他 Telegram 组件配合使用:

import {
  TelegramProvider,
  TelegramBackButton,
  TelegramMainButton,
  Text,
  Headline
} from '@xcloud/ui-telegram'

function App() {
  return (
    <TelegramProvider>
      <TelegramBackButton onClick={() => history.back()} />

      <Headline weight="3">My Page</Headline>
      <Text>Content goes here...</Text>

      <TelegramMainButton
        text="Continue"
        onClick={handleContinue}
      />
    </TelegramProvider>
  )
}

注意事项

1. 必须在 Telegram 环境中运行: 组件依赖 Telegram WebApp SDK,在非 Telegram 环境中某些功能可能无法使用
2. 只需一个 Provider: 整个应用只需要一个 TelegramProvider,通常放在根组件
3. 生命周期管理: Provider 会自动处理 SDK 的挂载和卸载

相关链接

• TelegramBackButton - 返回按钮组件
• TelegramMainButton - 主按钮组件
• Typography - 排版组件
• @tma.js/sdk 文档