介绍
# Telegram Mini App Development
针对常见 Telegram Mini App 问题的久经考验的解决方案。
## 快速参考
### 安全区域（全屏模式） ```typescript // Use reactive hook - values are async and context-dependent const safeArea = useSafeAreaInset(); // from references/hooks.ts <div style={{ paddingTop: safeArea.top }}>Header</div> ```
### position:fixed 失效 Telegram 会将 `transform` 应用于容器。请使用 `createPortal`： ```tsx import { createPortal } from 'react-dom'; createPortal(<Modal />, document.body); ```
### BackButton 不触发 使用 `@telegram-apps/sdk`，而不是原始的 WebApp： ```typescript import { onBackButtonClick, showBackButton } from '@telegram-apps/sdk'; onBackButtonClick(handleBack); ```
### 使用 Inline Mode 分享 1. 启用 inline 模式：@BotFather → `/setinline` → 选择机器人 2. 后端调用 `savePreparedInlineMessage` → 返回 `prepared_message_id` 3. 前端调用 `WebApp.shareMessage(prepared_message_id)`
**注意：** `prepared_message_id` 是**一次性使用**的 —— 每次分享点击都需要重新准备。对于静态内容，可以考虑将图片缓存在 R2/CDN 上，并在每次点击时进行准备。
### React “0” 渲染 ```tsx // WRONG: renders literal "0" {count && <span>{count}</span>}
// CORRECT {count > 0 && <span>{count}</span>} ```
## 详细指南
- **[references/KNOWLEDGE.md](references/KNOWLEDGE.md)** — 包含所有坑点和解决方案的完整知识库 - **[references/hooks.ts](references/hooks.ts)** — 可复制的 React hooks（useSafeAreaInset, useFullscreen 等） - **[references/components.tsx](references/components.tsx)** — 开箱即用的组件（SafeAreaHeader, DebugOverlay）
## 测试清单
发布前，请测试以下内容： - [ ] 从文件夹打开（聊天列表） - [ ] 从直接的机器人聊天打开 - [ ] iOS 设备 - [ ] Android 设备 - [ ] 分享流程（点击 → 关闭 → 再次点击） - [ ] 分享到不同的聊天类型（用户、群组、频道） - [ ] 返回按钮 - [ ] 滚动带粘性头部