Telegram Mini App Dev

核心用法

本技能是 Telegram Mini App 开发的工程化解决方案集，专注于解决平台特有的技术陷阱。核心能力分为四层：

1. 安全区域与视口适配 —— 提供 useSafeAreaInset 响应式 Hook，处理 iOS/Android 异形屏的 env(safe-area-inset-*) 动态值，解决全屏模式下顶部内容被刘海/状态栏遮挡的问题

2. 布局层级修复 —— 针对 Telegram 容器强制注入 transform 导致 position: fixed 失效的底层 Bug，提供 createPortal 注入方案，确保 Modal、Toast 等浮层正常显示

3. 导航与分享链路 —— 标准化 BackButton 事件绑定（推荐 @telegram-apps/sdk 替代原生 WebApp API），并完整梳理 Inline Mode 分享流程：后端调用 savePreparedInlineMessage 获取单次有效的 prepared_message_id，前端触发 shareMessage

4. React 工程陷阱 —— 显式标注布尔渲染短路问题（{count && ...} 在 count=0 时渲染 "0"），提供防御性写法

显著优点

• 即插即用：hooks.ts 和 components.tsx 可直接复制到生产项目，无需额外依赖
• 平台深度适配：覆盖 iOS/Android 双端差异、文件夹入口与直接聊天入口的行为区别
• 分享链路完整：从 BotFather 配置到后端 API 调用再到前端触发，闭环解决最复杂的 Mini App 功能之一

局限性与风险

• 单次分享限制：prepared_message_id 只能使用一次，高频分享场景需配合 CDN 缓存或延迟准备策略
• 平台依赖性强：解决方案深度绑定 Telegram WebApp 容器特性，迁移至其他小程序平台需完全重写
• SDK 版本敏感：建议使用 @telegram-apps/sdk 而非官方旧版 WebApp API，但 SDK 迭代较快需锁定版本

适合人群

React/TypeScript 技术栈的前端开发者，正在开发或维护 Telegram Mini App，尤其是对平台特有 Bug（fixed 定位、安全区域异步取值）感到困扰的工程师。

常规风险提示

• 安全区域值异步获取：必须在 Hook 内监听变化，硬编码 padding 会导致设备适配失败
• 分享流程状态管理：用户可能取消分享或切换聊天，需处理 prepared_message_id 的过期与重试逻辑

核心用途

该 Skill 是 Telegram Mini App（TMA）开发的实战指南，专门针对 TMA 生态中高频出现的技术痛点提供解决方案。内容涵盖安全区（Safe Area）计算、全屏模式适配、position: fixed 失效问题、返回按钮事件监听、内联分享（Inline Mode）完整流程，以及 React 常见陷阱（如条件渲染显示 "0"）。

显著优点

1. 实战导向：所有方案均来自真实踩坑经验，而非官方文档的简单翻译。例如安全区数值的异步特性、分享消息的 prepared_message_id 一次性使用限制，都是开发者易忽略的细节。

2. 即用代码：提供可直接复制的 React Hooks（useSafeAreaInset、useFullscreen）和组件（SafeAreaHeader、DebugOverlay），大幅降低接入成本。

3. 测试清单完整：包含从文件夹入口、私信入口到多平台（iOS/Android）、多分享场景的完整验证流程，帮助避免上线后才发现的兼容性问题。

潜在局限性

• 技术栈偏向 React：虽然核心概念通用，但代码示例以 React/TypeScript 为主，Vue/Svelte 开发者需要自行转换。
• 依赖官方 SDK 演进：Telegram WebApp API 持续更新，部分方案可能随 SDK 版本迭代而失效（如 @telegram-apps/sdk 的 API 变动）。
• 无后端服务代码：分享功能涉及 savePreparedInlineMessage 等后端调用，仅提供前端集成说明，需开发者自行实现服务端逻辑。

适合人群

• 正在开发或维护 Telegram Mini App 的前端工程师
• 从 H5/小程序迁移到 TMA 平台的开发者
• 遇到特定 Bug（如返回按钮不触发、分享失败、全屏布局异常）需要快速排查的开发者

常规风险

• API 变更风险：Telegram 平台策略调整可能导致分享流程、权限模型变化，建议关注官方更新。
• 设备碎片化：iOS Safari 与 Android WebView 的 WebApp 表现仍有差异，需真机验证。
• 一次性消息 ID 误用：prepared_message_id 的单次使用特性易导致分享失败，生产环境需确保每次点击都重新准备消息。