Telegram 迷你应用开发

针对常见 Telegram 迷你应用问题的实战验证解决方案。

快速参考

安全区域（全屏模式）

// 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：

import { createPortal } from 'react-dom';
createPortal(<Modal />, document.body);

返回按钮无响应

请使用@telegram-apps/sdk，而非原始的 WebApp：

import { onBackButtonClick, showBackButton } from '@telegram-apps/sdk';
onBackButtonClick(handleBack);

通过内联模式分享

1. 启用内联模式：@BotFather →/setinline→ 选择机器人
2. 后端调用savePreparedInlineMessage→ 返回prepared_message_id
3. 前端调用WebApp.shareMessage(prepared_message_id)

注意： prepared_message_id是一次性使用—— 每次分享点击时都需重新准备。 对于静态内容，可考虑在 R2/CDN 上缓存图片，并按每次点击准备。

React "0" 渲染

// WRONG: renders literal "0"
{count && <span>{count}</span>}

// CORRECT
{count > 0 && <span>{count}</span>}

详细指南

• references/KNOWLEDGE.md—— 包含所有注意事项和解决方案的完整知识库
• references/hooks.ts—— 可复制的 React 钩子（useSafeAreaInset、useFullscreen 等）
• references/components.tsx—— 即用型组件（SafeAreaHeader、DebugOverlay）

测试清单

发布前，请测试：

• 从文件夹打开（聊天列表）
• 从直接机器人聊天打开
• iOS 设备
• Android 设备
• 分享流程（点击 → 关闭 → 再次点击）
• 分享到不同类型的聊天（用户、群组、频道）
• 返回按钮
• 带粘性标题的滚动