tg-miniapp

TotalClaw 作者 totalclaw

轻松构建 Telegram 迷你应用程序。包括安全区域、全屏模式、BackButton 处理程序、与内联模式共享、位置：已修复问题和 React 陷阱的解决方案。在构建或调试 Telegram Mini 应用程序时，或者在遇到 WebApp API、安全区域或共享问题时使用。

安装 / 下载方式

TotalClaw CLI推荐

totalclaw install totalclaw:totalclaw~zenith2828-tg-miniapp

cURL直接下载，无需登录

curl -fsSL https://skills.taituai.com/api/skills/totalclaw%3Atotalclaw~zenith2828-tg-miniapp/file -o zenith2828-tg-miniapp.md

## 概述（中文）

轻松构建 Telegram 迷你应用程序。包括安全区域、全屏模式、BackButton 处理程序、与内联模式共享、位置：已修复问题和 React 陷阱的解决方案。在构建或调试 Telegram Mini 应用程序时，或者在遇到 WebApp API、安全区域或共享问题时使用。

## 原文

# Telegram Mini App Development

Battle-tested solutions for common Telegram Mini App issues.

## Quick Reference

### Safe Area (Fullscreen Mode)
```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 Broken
Telegram applies `transform` to container. Use `createPortal`:
```tsx
import { createPortal } from 'react-dom';
createPortal(<Modal />, document.body);
```

### BackButton Not Firing
Use `@telegram-apps/sdk`, not raw WebApp:
```typescript
import { onBackButtonClick, showBackButton } from '@telegram-apps/sdk';
onBackButtonClick(handleBack);
```

### Sharing with Inline Mode
1. Enable inline mode: @BotFather → `/setinline` → select bot
2. Backend calls `savePreparedInlineMessage` → returns `prepared_message_id`
3. Frontend calls `WebApp.shareMessage(prepared_message_id)`

**Note:** `prepared_message_id` is **single-use** — prepare fresh for each share tap.
For static content, consider caching images on R2/CDN and preparing per-tap.

### React "0" Rendering
```tsx
// WRONG: renders literal "0"
{count && <span>{count}</span>}

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

## Detailed Guides

- **[references/KNOWLEDGE.md](references/KNOWLEDGE.md)** — Full knowledge base with all gotchas and solutions
- **[references/hooks.ts](references/hooks.ts)** — Copy-paste React hooks (useSafeAreaInset, useFullscreen, etc.)
- **[references/components.tsx](references/components.tsx)** — Ready-to-use components (SafeAreaHeader, DebugOverlay)

## Testing Checklist

Before shipping, test:
- [ ] Open from folder (chat list)
- [ ] Open from direct bot chat
- [ ] iOS device
- [ ] Android device
- [ ] Share flow (tap → dismiss → tap again)
- [ ] Share to different chat types (user, group, channel)
- [ ] Back button
- [ ] Scroll with sticky header