Telegram Mini App Dev

核心用法

本技能提供 Telegram Mini App 开发的系统性解决方案，主要覆盖以下场景：

1. 安全区与全屏适配

• 使用 useSafeAreaInset() 响应式 Hook 获取动态安全边距（顶部刘海、底部导航栏区域）
• 替代传统的 CSS env(safe-area-inset-*)，因 Telegram WebView 中这些值可能异步获取或上下文依赖

2. 定位问题修复

• position: fixed 在 Telegram 容器中失效的根本原因是父级被应用了 transform
• 解决方案：使用 React 的 createPortal 将模态框等固定元素渲染到 document.body

3. 返回按钮事件处理

• 避免直接使用 Telegram WebApp 原生 API
• 推荐 @telegram-apps/sdk 的 onBackButtonClick 和 showBackButton，提供更可靠的跨平台事件订阅

4. 分享功能完整链路

• 需先在 @BotFather 启用 /setinline 内联模式
• 后端调用 savePreparedInlineMessage 生成消息模板
• 前端通过 WebApp.shareMessage(prepared_message_id) 触发分享

5. React 常见陷阱

• 条件渲染时避免 {count && <Component />}，当 count 为 0 时会渲染字面量 "0"
• 正确写法：{count > 0 && <Component />}

显著优点

• 实战经验导向：所有方案均来自生产环境验证，非文档理论
• 即插即用代码：提供完整的 TypeScript Hooks 和组件（SafeAreaHeader、DebugOverlay）
• 跨平台覆盖：明确区分 iOS/Android 差异，含完整测试清单
• 现代技术栈：基于 @telegram-apps/sdk 而非原始 WebApp API，TypeScript 友好

潜在缺点与局限性

• 生态依赖：深度绑定 React 和 @telegram-apps/sdk，Vue/原生 JS 项目需额外适配
• Telegram 版本碎片化：部分 API 行为在不同 Telegram 客户端版本中存在差异
• 审核依赖：分享功能需后端配合且受 BotFather 配置限制，无法纯前端实现
• 测试成本高：必须在真机测试（iOS/Android），模拟器无法完全复现 WebView 行为

适合人群

• 正在开发或维护 Telegram Mini App 的前端工程师
• 遇到 WebView 适配、安全区、分享功能等技术障碍的开发者
• 需要将现有 Web 应用迁移至 Telegram 生态的团队

常规风险

• API 变更风险：Telegram WebApp API 非标准化，官方更新可能破坏现有实现
• 平台限制：iOS 对 WebView 的限制（如全屏、手势冲突）可能无法完全规避
• 用户体验一致性：Telegram 客户端主题、字体、动画与 Web App 难以完美统一
• 分享功能失败：若 Bot 未正确配置 inline 模式或后端集成有误，分享流程将中断

核心用法

本 Skill 是针对 Telegram Mini App 开发的问题驱动型速查手册，聚焦开发者在实际生产中反复踩坑的 6 大场景：

1. Safe Area 适配：提供 useSafeAreaInset() Hook，自动处理 iOS/Android 刘海屏、状态栏高度差异，避免内容被遮挡。
2. position:fixed 失效问题：Telegram WebView 会对容器应用 transform 导致定位异常，方案是使用 createPortal 将模态框直接挂载到 document.body。
3. BackButton 事件不触发：推荐使用 @telegram-apps/sdk 官方封装，而非直接操作 window.Telegram.WebApp，确保事件监听可靠。
4. 分享功能完整链路：从前端 shareMessage 到后端 savePreparedInlineMessage，配合 BotFather 开启 inline 模式的完整配置指南。
5. React 渲染陷阱：明确指出 {count && <span>{count}</span>} 在 count=0 时会渲染字面量 "0" 的 Bug。
6. 测试清单：覆盖从文件夹入口、直接对话入口、iOS/Android 双端、分享回流、返回键、吸顶滚动等 7 项上线前必测场景。

配套资源包括：

• references/KNOWLEDGE.md：全量知识库
• references/hooks.ts：可直接复制的 React Hooks（useSafeAreaInset、useFullscreen 等）
• references/components.tsx：现成组件（SafeAreaHeader、DebugOverlay）

显著优点

• 痛点精准：所有解决方案均来自生产环境验证，非文档复述
• 代码即拿即用：Hook 和组件经过封装，接入成本极低
• 跨端兼容：同时考虑 iOS Safari 和 Android WebView 的差异
• 官方 SDK 最佳实践：明确区分「官方推荐方式」与「踩坑方式」

潜在局限

• 框架限定：示例代码基于 React，Vue/Svelte 开发者需自行转译
• 语言单一：文档为英文，中文开发者阅读存在门槛
• 后端链路简略：分享功能的后端 savePreparedInlineMessage 仅提及调用，无具体实现示例
• 测试依赖真机：部分场景（如安全区高度计算）无法在桌面浏览器模拟

适合人群

• 正在开发或维护 Telegram Mini App 的前端工程师
• 从 Web 端迁移到 Telegram 生态、需要快速了解 WebView 特殊性的开发者
• 遇到「返回键不响应」「fixed 定位错乱」「分享无法唤起」等具体问题的调试者

常规风险

• SDK 版本漂移：@telegram-apps/sdk 仍在迭代，建议锁定版本号
• 平台策略变更：Telegram 可能调整 WebView 安全区计算逻辑，需关注官方更新
• 无 LICENSE：当前项目未声明开源协议，商用需自行确认版权状态
• 纯客户端代码：虽无数据收集风险，但分享功能涉及后端配合，需自行确保服务端安全