Telegram Bot API Formatting Options 使用说明教程

8 阅读 0 评论 0 点赞

## 1. Formatting Options 用途介绍

Formatting Options（格式选项）是 Telegram Bot API 提供的一组文本格式化功能，允许开发者在发送消息时使用不同的格式语法，使消息内容更加丰富和结构化。这些格式选项不是独立的 API 方法，而是作为 `sendMessage`、`editMessageText` 等消息相关方法的 `parse_mode` 参数值使用。

Formatting Options 支持三种格式：

- **MarkdownV2**：推荐使用的 Markdown 格式，支持最丰富的格式化功能

- **HTML**：使用标准 HTML 标签进行格式化，仅支持 Telegram 允许的特定标签

- **Markdown**：旧版 Markdown 格式，功能较少，不推荐使用

通过使用这些格式选项，开发者可以在消息中添加粗体、斜体、链接、代码、下划线、删除线等格式化效果，提升消息的可读性和交互性。

## 2. 原生 PHP 调用实例

### 2.1 使用 MarkdownV2 格式发送消息

<?php
// 机器人 API 令牌
$token = 'YOUR_BOT_TOKEN';

// 目标聊天 ID
$chatId = 123456789;

// 构建带有 MarkdownV2 格式的消息内容
$messageText = "*这是粗体文本*\n" .
               "_这是斜体文本_\n" .
               "__这是下划线文本__\n" .
               "~这是删除线文本~\n" .
               "`这是内联代码`\n" .
               "```php\n" .
               "// 这是 PHP 代码块\n" .
               "echo 'Hello Telegram!';\n" .
               "```\n" .
               "[这是一个链接](https://example.com)\n" .
               "@这是一个提及用户名\n" .
               "\*这是一个转义的星号\*";

// 构建 API 请求参数
$params = [
    'chat_id' => $chatId,
    'text' => $messageText,
    'parse_mode' => 'MarkdownV2'
];

// 创建 cURL 请求
$ch = curl_init();

// 设置 cURL 选项
curl_setopt($ch, CURLOPT_URL, "https://api.telegram.org/bot{$token}/sendMessage");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($params));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json'
]);

// 执行请求并获取响应
$response = curl_exec($ch);

// 检查错误
if (curl_errno($ch)) {
    echo 'cURL 错误: ' . curl_error($ch);
} else {
    // 解析 JSON 响应
    $result = json_decode($response, true);
    
    if ($result['ok']) {
        echo '消息发送成功！消息 ID: ' . $result['result']['message_id'];
    } else {
        echo '消息发送失败: ' . $result['description'];
    }
}

// 关闭 cURL
curl_close($ch);
?>

### 2.2 使用 HTML 格式发送消息

<?php
// 机器人 API 令牌
$token = 'YOUR_BOT_TOKEN';

// 目标聊天 ID
$chatId = 123456789;

// 构建带有 HTML 格式的消息内容
$messageText = "<b>这是粗体文本</b><br>" .
               "<i>这是斜体文本</i><br>" .
               "<u>这是下划线文本</u><br>" .
               "<s>这是删除线文本</s><br>" .
               "<code>这是内联代码</code><br>" .
               "<pre><code class=\"language-php\">" .
               "// 这是 PHP 代码块\n" .
               "echo 'Hello Telegram!';" .
               "</code></pre><br>" .
               "<a href=\"https://example.com\">这是一个链接</a><br>" .
               "@这是一个提及用户名";

// 构建 API 请求参数
$params = [
    'chat_id' => $chatId,
    'text' => $messageText,
    'parse_mode' => 'HTML'
];

// 创建 cURL 请求
$ch = curl_init();

// 设置 cURL 选项
curl_setopt($ch, CURLOPT_URL, "https://api.telegram.org/bot{$token}/sendMessage");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($params));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json'
]);

// 执行请求并获取响应
$response = curl_exec($ch);

// 检查错误
if (curl_errno($ch)) {
    echo 'cURL 错误: ' . curl_error($ch);
} else {
    // 解析 JSON 响应
    $result = json_decode($response, true);
    
    if ($result['ok']) {
        echo '消息发送成功！消息 ID: ' . $result['result']['message_id'];
    } else {
        echo '消息发送失败: ' . $result['description'];
    }
}

// 关闭 cURL
curl_close($ch);
?>

### 2.3 创建 MarkdownV2 转义工具函数

由于 MarkdownV2 需要转义多个特殊字符，创建一个转义函数可以提高开发效率：

<?php
/**
 * 转义 MarkdownV2 特殊字符
 * @param string $text 需要转义的文本
 * @return string 转义后的文本
 */
function escapeMarkdownV2($text) {
    $specialChars = ['_', '*', '[', ']', '(', ')', '~', '`', '>', '#', '+', '-', '=', '|', '{', '}', '.', '!'];
    
    foreach ($specialChars as $char) {
        $text = str_replace($char, '\\' . $char, $text);
    }
    
    return $text;
}

// 使用示例
$userInput = "用户输入的文本*包含特殊字符*";
$escapedText = escapeMarkdownV2($userInput);
// 结果: "用户输入的文本\*包含特殊字符\*"

// 结合 sendMessage 使用
$messageText = "*重要消息*\n" . escapeMarkdownV2($userInput);
?>
```

### 2.4 完整的格式化消息发送类

```php
<?php
/**
 * Telegram Bot 格式化消息发送类
 */
class TelegramFormatter {
    private $token;
    
    /**
     * 构造函数
     * @param string $token 机器人 API 令牌
     */
    public function __construct($token) {
        $this->token = $token;
    }
    
    /**
     * 转义 MarkdownV2 特殊字符
     * @param string $text 需要转义的文本
     * @return string 转义后的文本
     */
    private function escapeMarkdownV2($text) {
        $specialChars = ['_', '*', '[', ']', '(', ')', '~', '`', '>', '#', '+', '-', '=', '|', '{', '}', '.', '!'];
        
        foreach ($specialChars as $char) {
            $text = str_replace($char, '\\' . $char, $text);
        }
        
        return $text;
    }
    
    /**
     * 发送格式化消息
     * @param int|string $chatId 目标聊天 ID
     * @param string $text 消息文本
     * @param string $parseMode 解析模式 (MarkdownV2 或 HTML)
     * @return array|null 响应结果或 null
     */
    public function sendFormattedMessage($chatId, $text, $parseMode = 'MarkdownV2') {
        // 如果使用 MarkdownV2，确保文本已正确转义
        if ($parseMode === 'MarkdownV2') {
            // 注意：这里假设文本已经过适当转义
            // 实际应用中可能需要更复杂的处理
        }
        
        $params = [
            'chat_id' => $chatId,
            'text' => $text,
            'parse_mode' => $parseMode
        ];
        
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, "https://api.telegram.org/bot{$this->token}/sendMessage");
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($params));
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Content-Type: application/json'
        ]);
        
        $response = curl_exec($ch);
        
        if (curl_errno($ch)) {
            error_log('Telegram API Error: ' . curl_error($ch));
            curl_close($ch);
            return null;
        }
        
        curl_close($ch);
        
        return json_decode($response, true);
    }
    
    /**
     * 发送粗体文本
     * @param int|string $chatId 目标聊天 ID
     * @param string $text 消息文本
     * @return array|null 响应结果或 null
     */
    public function sendBoldText($chatId, $text) {
        $formattedText = '*' . $this->escapeMarkdownV2($text) . '*';
        return $this->sendFormattedMessage($chatId, $formattedText, 'MarkdownV2');
    }
    
    /**
     * 发送代码块
     * @param int|string $chatId 目标聊天 ID
     * @param string $code 代码内容
     * @param string $language 代码语言
     * @return array|null 响应结果或 null
     */
    public function sendCodeBlock($chatId, $code, $language = '') {
        $formattedText = $language ? "```{$language}\n{$code}\n```" : "```\n{$code}\n```";
        return $this->sendFormattedMessage($chatId, $formattedText, 'MarkdownV2');
    }
}

// 使用示例
$token = 'YOUR_BOT_TOKEN';
$chatId = 123456789;

$formatter = new TelegramFormatter($token);

// 发送粗体消息
$formatter->sendBoldText($chatId, '这是一条粗体消息');

// 发送代码块
$phpCode = "<?php\necho 'Hello Telegram!';\n?>";
$formatter->sendCodeBlock($chatId, $phpCode, 'php');
?>

## 注意事项

1. Formatting Options 不是独立的 API 方法，而是作为消息相关方法的参数使用

2. MarkdownV2 是推荐的格式，支持最丰富的功能

3. 使用 MarkdownV2 时必须正确转义特殊字符

4. HTML 格式仅支持 Telegram 允许的特定标签

5. 消息文本长度限制为 4096 个字符

点赞(0) 打赏

本文分类：教程
本文标签：Formatting Options
浏览次数：8 次浏览
发布日期：2025-12-16 10:22:53
本文链接：https://telegrambotdev.com/jiaocheng/158.html

上一篇 > telegram机器人sendmessage用法
下一篇 > Paid Broadcasts 使用教程

Telegram Bot API Formatting Options 使用说明教程

评论列表共有 0 条评论

发表评论取消回复

Telegram Bot API Formatting Options 使用说明教程

Telegram Bot API Formatting Options 使用说明教程

评论列表 共有 0 条评论

发表评论 取消回复

评论列表共有 0 条评论

发表评论取消回复