# Telegram 迷你应用程序开发 ## 快速参考 ### WebApp 对象 (window.Telegram.WebApp) // 初始化应用程序 Telegram.WebApp.ready(); Telegram.WebApp.expand(); // 获取用户数据（不安全 - 仅用于显示） const user = Telegram.WebApp.initDataUnsafe.user; // { id, 名字, 姓氏, 用户名, languageCode, isPremium } // 获取签名数据（发送到后端进行验证） const initDataRaw = Telegram.WebApp.initData; // 发送方式：授权：tma ${initDataRaw} ### 关键方法方法|目的 ---|--- `准备好（）` |信号应用程序已加载 `展开()` |展开至全高 `关闭()` |关闭应用程序 `发送数据（数据）` |向机器人发送数据（关闭应用程序） `openLink(url)` |打开外部网址 `openTelegramLink(url)` |打开电报链接 `showAlert(msg)` |显示本机警报 `显示确认（消息）` |显示本机确认 `showPopup(参数)` |显示自定义弹出窗口 `setHeaderColor(颜色)` |更改标题颜色 `设置背景颜色（颜色）` |改变背景 `triggerHapticFeedback（类型，样式）` |振动反馈 ### 主按钮配置 const mainButton = Telegram.WebApp.MainButton; mainButton.text = '保存设置'; mainButton.color = '#5288c1'; mainButton.textColor = '#ffffff'; mainButton.show(); mainButton.onClick(() => { // 处理点击 mainButton.showProgress(); // ... 异步操作 mainButton.hideProgress(); }); ### 返回按钮 const backButton = Telegram.WebApp.BackButton; 返回按钮.show(); backButton.onClick(() => { // 导航回来 }); 返回按钮.隐藏(); ### 主题颜色 const 主题 = Telegram.WebApp.themeParams; // { // bg_color、text_color、hint_color、link_color、 // 按钮颜色、按钮文本颜色、辅助背景颜色、 // header_bg_color、accent_text_color、section_bg_color、 //section_header_text_color, subtitle_text_color, // 破坏性文本颜色 // } // 可用的 CSS 变量： // var(--tg-主题-bg-颜色) // var(--tg-主题-文本-颜色) // 等等 ### 活动 // 主题已更改 Telegram.WebApp.onEvent('themeChanged', () => { const newTheme = Telegram.WebApp.themeParams; }); // 视口改变 Telegram.WebApp.onEvent('viewportChanged', () => { const height = Telegram.WebApp.viewportHeight; }); // 主按钮被点击 Telegram.WebApp.onEvent('mainButtonClicked', () => { // 句柄 }); // 返回按钮被点击 Telegram.WebApp.onEvent('backButtonClicked', () => { // 导航 }); ### 存储 API // 设备存储（每个机器人 5MB）等待 Telegram.WebApp.DeviceStorage.setItem('key', 'value'); const value = wait Telegram.WebApp.DeviceStorage.getItem('key'); // 安全存储（加密，最多 10 项）等待 Telegram.WebApp.SecureStorage.setItem('token', 'secret'); // 云存储（跨设备同步）等待 Telegram.WebApp.CloudStorage.setItem('preference', 'dark'); ## SDK 使用 (@telegram-apps/sdk-react) ### 安装 npm install @telegram-apps/sdk @telegram-apps/sdk-react ### 提供商设置从 '@telegram-apps/sdk-react' 导入 { SDKProvider, useLaunchParams }; 函数应用程序（）{ 返回（ <路由器> <应用程序内容/> ）； } ### 挂钩导入{ 使用启动参数，使用初始化数据，使用InitDataRaw，使用主题参数，使用视口，使用主按钮，使用后退按钮，使用云存储，来自“@telegram-apps/sdk-react”；函数 MyComponent() { // 用户数据 const initData = useInitData(); const 用户 = initData?.user; // 后端原始数据 const initDataRaw = useInitDataRaw(); // 主题 const themeParams = useThemeParams(); // 视口 const viewport = useViewport(); const { 高度, stableHeight, isExpanded } = 视口; // 主按钮 const mainButton = useMainButton(); mainButton.setParams({ 文本：“保存”，可见：真实， }); mainButton.on('点击',handleSave); } ### 模拟环境（开发）从'@telegram-apps/sdk-react'导入{mockTelegramEnv}；如果（导入.meta.env.DEV）{ 模拟电报环境（{ 主题参数：{ 背景颜色: '#17212b', 文本颜色: '#f5f5f5', 按钮颜色: '#5288c1', 按钮文本颜色: '#ffffff', // ...其他参数 }, 初始化数据：{ 用户：{ 身份证号：99281932，名字：'测试'，姓氏：'用户'，用户名：'测试用户'，语言代码: 'en', isPremium：真实， }, 哈希：'模拟哈希'， authDate：新的日期（）， }, 版本：'7.2'，平台：'tdesktop'， }); } ## 后端身份验证（Kotlin/Spring） ### 初始化数据验证导入 javax.crypto.Mac 导入 javax.crypto.spec.SecretKeySpec @服务类 TelegramAuthService( @Value("\${telegram.bot.token}") private val botToken: String ）{ 有趣的 validateInitData(initDataRaw: String): TelegramUser? { val 参数 = parseInitData(initDataRaw) val hash = params["hash"] ?: 返回 null val dataCheckString = 参数 .filterKeys { it != "哈希" } .toSortedMap() .map { "${it.key}=${it.value}" } .joinToString("\n") val SecretKey = hmacSha256("WebAppData".toByteArray(), botToken.toByteArray()) val计算哈希 = hmacSha256(secretKey, dataCheckString.toByteArray()) .toHexString() if (calculatedHash != hash) 返回 null val authDate = params["auth_date"]?.toLongOrNull() ?: 返回 null if (System.currentTimeMillis() / 1000 - authDate > 3600) 返回 null return parseUser(params["user"] ?: 返回 null) } 私人乐趣 hmacSha256（键：ByteArray，数据：ByteArray）：ByteArray { val mac = Mac.getInstance("HmacSHA256") mac.init(SecretKeySpec(密钥, "HmacSHA256")) 返回 mac.doFinal(数据) } } ### REST 控制器模式 @RestController @RequestMapping(“/api/v1/miniapp”) 类 MiniAppController( 私有 val authService：TelegramAuthService，私有值设置服务：ChatSettingsService ）{ @GetMapping("/聊天") 有趣的 getUserChats( @RequestHeader("授权") authHeader: String ): ResponseEntity> { val initData = authHeader.removePrefix("tma ") val 用户 = authService.validateInitData(initData) ?: 抛出 UnauthorizedException("无效的 initData") val chats = settingsService.findChatsWhereAdmin(user.id) 返回 ResponseEntity.ok(chats.map { it.toResponse() }) } @PutMapping("/chats/{chatId}/settings") 有趣的更新聊天设置（ @PathVariable chatId：长， @RequestHeader("授权") authHeader: 字符串, @RequestBody请求：UpdateSettingsRequest ): ResponseEntity { val 用户 = validateAuth(authHeader) if (!adminService.isAdmin(user.id, chatId)) { throw ForbiddenException(“此聊天中不是管理员”) } val 设置 = settingsService.update(chatId, 请求) 返回 ResponseEntity.ok(settings.toResponse()) } } ## 组件库 (@telegram-apps/ui) ### 安装 npm 安装@telegram-apps/ui ### 组件导入{ 应用程序根目录，按钮，细胞，部分，开关，输入，选择，滑块，旋转器，占位符，来自“@telegram-apps/ui”；函数设置页面() { 返回（ <应用程序根目录> <节标题=“聊天设置”> <细胞之后={<开关检查={isEnabled} onChange={setIsEnabled} />} 描述=“启用消息收集” > 收藏 <细胞 after={<选择值={action} onChange={setAction}> <选项值=“警告”>警告 } 描述=“达到警告阈值时的操作” > 阈值动作 <滑块分钟={1} 最大值={10} 值={最大警告} onChange={setMaxWarnings} /> <按钮尺寸=“大”拉伸onClick = {handleSave}> 保存设置）； } ## 限制 1. **需要 HTTPS** \- 生产应用程序必须通过 HTTPS 提供服务 2. **4KB 数据限制** \- `sendData()` 限制为 4096 字节 3. **无摄像头/麦克风** \- 无法直接访问 4. **initData 过期** \- 自 auth_date 起约 1 小时内有效 5. **WebView 约束** \- 仅限于 WebView 功能 6. **跨客户端差异** \- iOS/Android/桌面之间的功能可能有所不同 ## 资源 * [官方文档]() * [社区文档]() * [@telegram-apps/sdk]() * [反应模板]()

Telegram 迷你应用程序

包含技能