tg-miniapp

tg-miniapp 是一款专注于 Telegram Mini App（TMA）开发的实用技能文档，系统性地整理了开发者在构建小程序过程中常遇到的技术陷阱与解决方案。该技能并非可执行程序，而是一份经过实战验证的开发参考手册，涵盖了从安全区域适配、全屏模式处理到分享功能实现的完整技术路径。

核心用法
开发者可将此技能作为技术字典随时查阅。其核心交付物包括三个部分：位于 references/KNOWLEDGE.md 的完整知识库，详细记录了 safe area 计算、position:fixed 失效问题（因 Telegram 容器应用 transform 导致）及 BackButton 事件监听等坑点；references/hooks.ts 提供的 React Hooks 代码片段，如 useSafeAreaInset 用于动态获取安全边距；以及 references/components.tsx 中的现成 UI 组件（SafeAreaHeader、DebugOverlay）。此外，技能还提供了 Inline Mode 分享消息的完整实现链路，包括后端 savePreparedInlineMessage 与前端 shareMessage 的对接流程。

显著优点
该技能的最大价值在于其"踩坑经验"的沉淀。针对 TMA 开发中 notorious 的 safe area 适配问题，它提供了响应式 Hook 方案而非硬编码；对于 React 开发者常见的 "0" 渲染陷阱（{count && }），也给出了明确的对比例子。更重要的是，它附带了完整的上线前测试清单（Test Checklist），覆盖 iOS/Android 双端、不同入口场景（文件夹/直接聊天）及分享流程的异常路径，显著降低上线后的兼容性风险。

潜在缺点与局限性
作为 T3 来源的社区贡献，该技能缺乏官方背书，代码示例虽经过验证但仍需开发者根据实际业务调整。技术栈上存在明显偏向性，所有示例均基于 React + TypeScript，Vue 或原生 JavaScript 开发者需要额外适配。此外，TMA 本身存在平台碎片化问题（iOS/Android/Web 表现差异），技能文档虽提及但无法完全消除平台特异性 Bug。部分高级功能（如分享消息）依赖 Telegram WebApp 8.0+ 版本，低版本客户端会面临兼容性问题。

适合的目标群体
主要面向正在使用或计划使用 React 技术栈开发 Telegram Mini App 的前端工程师。特别适合首次接触 TMA 开发的团队，可快速理解 WebApp SDK 的异步特性和容器限制。对于需要实现社交分享功能（通过 Inline Mode）的产品团队，该技能提供了端到端的实现参考。

使用风险
尽管技能本身为纯文档性质（A 级安全），但直接复制代码到生产环境仍存在常规风险：示例代码中的错误处理可能过于简化，需补充完整的边界情况校验；@telegram-apps/sdk 等依赖库需保持版本更新以适配 Telegram 客户端迭代；分享功能涉及的 prepared_message_id 为一次性消耗品，高并发场景下若未设计好后端缓存策略可能导致分享失败。建议在使用前进行代码审查，并在真机全量测试清单通过后再发布。