# Telegram Bot 按钮与键盘实现指南

> 完整的 Telegram Bot 交互式功能开发参考

---

## 📋 目录

1. [按钮和键盘类型](#按钮和键盘类型)
2. [实现方式对比](#实现方式对比)
3. [核心代码示例](#核心代码示例)
4. [最佳实践](#最佳实践)

---

## 按钮和键盘类型

### 1. Inline Keyboard（内联键盘）

**特点**：
- 显示在消息下方
- 点击后触发回调，不发送消息
- 支持回调数据、URL、切换查询等

**应用场景**：确认/取消、菜单导航、分页控制、设置选项

### 2. Reply Keyboard（底部虚拟键盘）

**特点**：
- 显示在输入框上方
- 点击后发送文本消息
- 可设置持久化或一次性

**应用场景**：快捷命令、常用操作、表单输入、主菜单

### 3. Bot Command Menu（命令菜单）

**特点**：
- 显示在输入框左侧 "/" 按钮
- 通过 BotFather 或 API 设置
- 提供命令列表和描述

**应用场景**：功能索引、新用户引导、快速命令访问

### 4. 类型对比

| 特性 | Inline | Reply | Command Menu |
|------|--------|-------|--------------|
| 位置 | 消息下方 | 输入框上方 | "/" 菜单 |
| 触发 | 回调查询 | 文本消息 | 命令 |
| 持久化 | 随消息 | 可配置 | 始终存在 |
| 场景 | 临时交互 | 常驻功能 | 命令索引 |

---

## 实现方式对比

### python-telegram-bot（推荐 Bot 开发）

**优点**：
- 官方推荐，完整的 Handler 系统
- 丰富的按钮和键盘支持
- 异步版本性能优异

**安装**：
```bash
pip install python-telegram-bot==20.7
```

### Telethon（适合用户账号自动化）

**优点**：
- 完整的 MTProto API 访问
- 可使用用户账号和 Bot
- 强大的消息监听能力

**安装**：
```bash
pip install telethon cryptg
```

---

## 核心代码示例

### 1. Inline Keyboard 实现

**python-telegram-bot：**
```python
from telegram import Update, InlineKeyboardButton, InlineKeyboardMarkup
from telegram.ext import Application, CommandHandler, CallbackQueryHandler, ContextTypes

async def start(update: Update, context: ContextTypes.DEFAULT_TYPE):
    """显示内联键盘"""
    keyboard = [
        [
            InlineKeyboardButton("📊 查看数据", callback_data="view_data"),
            InlineKeyboardButton("⚙️ 设置", callback_data="settings"),
        ],
        [
            InlineKeyboardButton("🔗 访问网站", url="https://example.com"),
        ],
    ]
    reply_markup = InlineKeyboardMarkup(keyboard)
    await update.message.reply_text("请选择：", reply_markup=reply_markup)

async def button_callback(update: Update, context: ContextTypes.DEFAULT_TYPE):
    """处理按钮点击"""
    query = update.callback_query
    await query.answer()  # 必须调用

    if query.data == "view_data":
        await query.edit_message_text("显示数据...")
    elif query.data == "settings":
        await query.edit_message_text("设置选项...")

# 注册处理器
app = Application.builder().token("TOKEN").build()
app.add_handler(CommandHandler("start", start))
app.add_handler(CallbackQueryHandler(button_callback))
app.run_polling()
```

**Telethon：**
```python
from telethon import TelegramClient, events, Button

client = TelegramClient('bot', api_id, api_hash).start(bot_token=BOT_TOKEN)

@client.on(events.NewMessage(pattern='/start'))
async def start(event):
    buttons = [
        [Button.inline("📊 查看数据", b"view_data"), Button.inline("⚙️ 设置", b"settings")],
        [Button.url("🔗 访问网站", "https://example.com")]
    ]
    await event.respond("请选择：", buttons=buttons)

@client.on(events.CallbackQuery)
async def callback(event):
    if event.data == b"view_data":
        await event.edit("显示数据...")
    elif event.data == b"settings":
        await event.edit("设置选项...")

client.run_until_disconnected()
```

### 2. Reply Keyboard 实现

**python-telegram-bot：**
```python
from telegram import KeyboardButton, ReplyKeyboardMarkup, ReplyKeyboardRemove

async def menu(update: Update, context: ContextTypes.DEFAULT_TYPE):
    """显示底部键盘"""
    keyboard = [
        [KeyboardButton("📊 查看数据"), KeyboardButton("⚙️ 设置")],
        [KeyboardButton("📚 帮助"), KeyboardButton("❌ 隐藏键盘")],
    ]
    reply_markup = ReplyKeyboardMarkup(
        keyboard,
        resize_keyboard=True,
        one_time_keyboard=False
    )
    await update.message.reply_text("菜单已激活", reply_markup=reply_markup)

async def handle_text(update: Update, context: ContextTypes.DEFAULT_TYPE):
    """处理文本消息"""
    text = update.message.text
    if text == "📊 查看数据":
        await update.message.reply_text("显示数据...")
    elif text == "❌ 隐藏键盘":
        await update.message.reply_text("已隐藏", reply_markup=ReplyKeyboardRemove())
```

**Telethon：**
```python
@client.on(events.NewMessage(pattern='/menu'))
async def menu(event):
    buttons = [
        [Button.text("📊 查看数据"), Button.text("⚙️ 设置")],
        [Button.text("📚 帮助"), Button.text("❌ 隐藏键盘")]
    ]
    await event.respond("菜单已激活", buttons=buttons)

@client.on(events.NewMessage)
async def handle_text(event):
    if event.text == "📊 查看数据":
        await event.respond("显示数据...")
```

### 3. Bot Command Menu 设置

**通过 BotFather：**
```
1. 发送 /setcommands 到 @BotFather
2. 选择你的 Bot
3. 输入命令列表（每行格式：command - description）

start - 启动机器人
help - 获取帮助
menu - 显示主菜单
settings - 配置设置
```

**通过 API（python-telegram-bot）：**
```python
from telegram import BotCommand

async def set_commands(app: Application):
    """设置命令菜单"""
    commands = [
        BotCommand("start", "启动机器人"),
        BotCommand("help", "获取帮助"),
        BotCommand("menu", "显示主菜单"),
        BotCommand("settings", "配置设置"),
    ]
    await app.bot.set_my_commands(commands)

# 在启动时调用
app.post_init = set_commands
```

### 4. 项目结构示例

```
telegram_bot/
├── bot.py                    # 主程序
├── config.py                 # 配置管理
├── requirements.txt
├── .env
├── handlers/
│   ├── command_handlers.py   # 命令处理器
│   ├── callback_handlers.py  # 回调处理器
│   └── message_handlers.py   # 消息处理器
├── keyboards/
│   ├── inline_keyboards.py   # 内联键盘布局
│   └── reply_keyboards.py    # 回复键盘布局
└── utils/
    ├── logger.py             # 日志
    └── database.py           # 数据库
```

**模块化示例（keyboards/inline_keyboards.py）：**
```python
from telegram import InlineKeyboardButton, InlineKeyboardMarkup

def get_main_menu():
    """主菜单键盘"""
    return InlineKeyboardMarkup([
        [
            InlineKeyboardButton("📊 数据", callback_data="data"),
            InlineKeyboardButton("⚙️ 设置", callback_data="settings"),
        ],
        [InlineKeyboardButton("📚 帮助", callback_data="help")],
    ])

def get_data_menu():
    """数据菜单键盘"""
    return InlineKeyboardMarkup([
        [
            InlineKeyboardButton("📈 实时", callback_data="data_realtime"),
            InlineKeyboardButton("📊 历史", callback_data="data_history"),
        ],
        [InlineKeyboardButton("⬅️ 返回", callback_data="back")],
    ])
```

---

## 最佳实践

### 1. Handler 优先级

```python
# 先注册先匹配，按从特殊到通用的顺序
app.add_handler(CommandHandler("start", start))           # 1. 特定命令
app.add_handler(CallbackQueryHandler(callback))           # 2. 回调查询
app.add_handler(ConversationHandler(...))                 # 3. 对话流程
app.add_handler(MessageHandler(filters.TEXT, text_msg))   # 4. 通用消息（最后）
```

### 2. 错误处理

```python
async def error_handler(update: Update, context: ContextTypes.DEFAULT_TYPE):
    """全局错误处理"""
    logger.error(f"更新 {update} 引起错误", exc_info=context.error)

    # 通知用户
    if update and update.effective_message:
        await update.effective_message.reply_text("操作失败，请重试")

app.add_error_handler(error_handler)
```

### 3. 回调数据管理

```python
# 使用结构化的 callback_data
callback_data = "action:page:item"  # 例如 "view:1:product_123"

# 解析回调数据
async def callback(update: Update, context: ContextTypes.DEFAULT_TYPE):
    query = update.callback_query
    parts = query.data.split(":")
    action, page, item = parts

    if action == "view":
        await show_item(query, page, item)
```

### 4. 键盘设计原则

- **简洁**：每行最多 2-3 个按钮
- **清晰**：使用 emoji 增强识别度
- **一致**：保持统一的布局风格
- **响应**：及时反馈用户操作

### 5. 安全考虑

```python
# 验证用户权限
ADMIN_IDS = [123456789]

async def admin_only(update: Update, context: ContextTypes.DEFAULT_TYPE):
    user_id = update.effective_user.id
    if user_id not in ADMIN_IDS:
        await update.message.reply_text("无权限")
        return

    # 执行管理员操作
```

### 6. 部署方案

**Webhook（推荐生产环境）：**
```python
from flask import Flask, request

app_flask = Flask(__name__)

@app_flask.route('/webhook', methods=['POST'])
def webhook():
    update = Update.de_json(request.get_json(), bot)
    application.update_queue.put(update)
    return "OK"

# 设置 webhook
bot.set_webhook(f"https://yourdomain.com/webhook")
```

**Systemd Service（Linux）：**
```ini
[Unit]
Description=Telegram Bot
After=network.target

[Service]
Type=simple
User=your_user
WorkingDirectory=/path/to/bot
ExecStart=/path/to/venv/bin/python bot.py
Restart=always

[Install]
WantedBy=multi-user.target
```

### 7. 常用库版本

```txt
# requirements.txt
python-telegram-bot==20.7
python-dotenv==1.0.0
aiosqlite==0.19.0
httpx==0.25.2
```

---

## 快速参考

### Inline Keyboard 按钮类型

```python
InlineKeyboardButton("文本", callback_data="data")     # 回调按钮
InlineKeyboardButton("链接", url="https://...")        # URL按钮
InlineKeyboardButton("切换", switch_inline_query="")   # 内联查询
InlineKeyboardButton("登录", login_url=...)            # 登录按钮
InlineKeyboardButton("支付", pay=True)                 # 支付按钮
InlineKeyboardButton("应用", web_app=WebAppInfo(...))  # Mini App
```

### 常用事件类型

- `events.NewMessage` - 新消息
- `events.CallbackQuery` - 回调查询
- `events.InlineQuery` - 内联查询
- `events.ChatAction` - 群组动作

---

**这份指南涵盖了 Telegram Bot 按钮和键盘的所有核心实现！**