如何从零开始创建您的第一个 Telegram Mini App

还记得当年 PWA（渐进式 Web 应用）的火热吗？现在，Telegram Mini Apps (TMA) 也正经历类似的爆发式增长。这些内置于 Telegram 的 Web 应用已被开发者用于各种用途——从简单工具到支持加密支付的完整电商平台。今天，我们将带您了解如何创建自己的 Mini App，并让这个过程变得轻松易懂。

什么是 Telegram Mini Apps，为什么它们如此火爆？

TMA 本质上是运行在 Telegram 内部的 Web 应用。它们使用 HTML、CSS 和 JavaScript 构建，并能够调用 Telegram 提供的各种强大功能。例如，开发者可以直接访问用户数据或集成内置支付系统。

它们的优势在哪里？

无需经过 App Store 或 Google Play 审核，开发和上线速度更快。
用户无需安装任何应用，所有功能都可以直接在 Telegram 内运行。
技术栈自由选择，无论是 React、Vue 还是纯 JavaScript 都能轻松使用。
触达超过 9 亿 Telegram 用户，带来广阔的市场潜力。

成功的 Telegram Mini Apps 示例

让我们看看一些实际案例，以便更直观地了解 TMA 可以实现什么：

Wallet — 一个用于 TON 生态的加密钱包，支持购买个性化用户名。
Hamster Kombat — 一款点击类游戏（Tapper），迅速走红并吸引了 2.5 亿用户。
DurgerKing — 模仿知名快餐品牌的幽默应用，带来趣味互动体验。

如何开始开发

要创建 TMA，您需要准备以下工具和知识：

代码编辑器：VS Code 或 WebStorm 均可，选择自己熟悉的工具即可。
基础 Web 开发技能：HTML、CSS 和 JavaScript 这些前端技术是必备的。
Telegram 账号：确保您的手机和电脑上都安装了 Telegram，以便测试应用。
探索新事物的热情：只要愿意学习，任何人都可以上手开发自己的 Mini App！

步骤 1：创建助手机器人

首先，我们需要创建一个 Telegram 机器人，它将成为 Mini App 的入口。这个过程非常简单：

在 Telegram 中搜索 @BotFather。
发送命令 /newbot 创建新机器人。
为您的机器人命名，并为它设置一个唯一的用户名。
BotFather 会返回一个 API 令牌，请保存好它，以便稍后使用 API 进行交互。

机器人不仅可以启动您的 Mini App，还可以处理用户的指令。

例如：

“`javascript

// Пример простого бота на Node.js с использованием библиотеки node-telegram-bot-api

const TelegramBot = require(‘node-telegram-bot-api’);

const bot = new TelegramBot(token, {polling: true});

bot.onText(/\/start/, (msg) => {

const chatId = msg.chat.id;

bot.sendMessage(chatId, ‘Привет! Нажми на кнопку, чтобы открыть приложение’, {

reply_markup: {

inline_keyboard: [[

{

text: ‘Открыть приложение’,

web_app: {url: ‘https://ваш-домен.com/app’}

}

]]

}

});

“`

步骤 2：准备开发环境

创建项目的基本结构：

“`

my-tma/

├── index.html

├── styles/

│ └── main.css

├── scripts/

│ └── app.js

└── assets/

└── images/

“`

最小化的 index.html

“`html

<!DOCTYPE html>

<html>

<head>

<title>Моё первое TMA</title>

</head>

<body>

<h1>Привет, Telegram!</h1>

</div>

</body>

</html>

“`

步骤 3：编写应用程序

现在到了最有趣的部分。下面是一个带有数据保存功能的简单计数器应用示例：

// app.js

const app = {

data: {

count: 0

init() {

// Инициализация приложения

this.setupTheme();

this.setupCounter();

this.setupMainButton();

setupTheme() {

// Применяем тему Telegram

const theme = window.Telegram.WebApp.themeParams;

document.body.style.backgroundColor = theme.bg_color;

document.body.style.color = theme.text_color;

setupCounter() {

// Создаём счётчик

const counter = document.createElement(‘div’);

counter.innerHTML = `

<h2>Счётчик: <span id=”count”>0</span></h2>

document.querySelector(‘#app’).appendChild(counter);

// Добавляем обработчики

document.querySelector(‘#increment’).onclick = () => this.updateCount(1);

document.querySelector(‘#decrement’).onclick = () => this.updateCount(-1);

setupMainButton() {

// Настраиваем главную кнопку

const MainButton = window.Telegram.WebApp.MainButton;

MainButton.setText(‘Сохранить’);

MainButton.onClick(() => this.saveData());

MainButton.show();

updateCount(delta) {

this.data.count += delta;

document.querySelector(‘#count’).textContent = this.data.count;

saveData() {

// Отправляем данные боту

window.Telegram.WebApp.sendData(JSON.stringify(this.data));

}

};

// Запускаем приложение

window.Telegram.WebApp.ready();

app.init();

应用程序样式化

确保您的应用在 Telegram 中看起来更加原生化。

以下是基本样式：

“`css

/* main.css */

body {

margin: 0;

padding: 16px;

font-family: -apple-system, BlinkMacSystemFont, ‘Segoe UI’, Roboto, Helvetica, Arial, sans-serif;

}

#app {

max-width: 600px;

margin: 0 auto;

}

button {

background: var(–tg-theme-button-color, #3390ec);

color: var(–tg-theme-button-text-color, #ffffff);

border: none;

border-radius: 8px;

padding: 8px 16px;

margin: 4px;

cursor: pointer;

}

button:hover {

opacity: 0.9;

}

“`

扩展功能

用户数据处理

Telegram 提供了用户的基本信息：

“`javascript

const user = window.Telegram.WebApp.initDataUnsafe.user;

if (user) {

console.log(`Привет, ${user.first_name}!`);

// Доступны также: last_name, username, language_code и др.

}

“`

通过 TON 添加支付功能

如果您希望接收支付，可以集成 TON Connect:

“`javascript

import { TonConnectUI } from ‘@tonconnect/ui’;

const tonConnectUI = new TonConnectUI({

manifestUrl: ‘https://your-app.com/tonconnect-manifest.json’,

buttonRootId: ‘connect-wallet’

});

// Создаём транзакцию

async function sendTransaction() {

const transaction = {

validUntil: Date.now() + 1000000,

messages: [

{

address: ‘EQCD39VS5jcptHL8vMjEXrzGaRcCVYto7HUn4bpAOg8xqB2N’,

amount: ‘10000000’, // 0.01 TON

}

]

};

try {

const result = await tonConnectUI.sendTransaction(transaction);

console.log(‘Транзакция отправлена:’, result);

} catch (error) {

console.error(‘Ошибка:’, error);

}

“`

如何进行测试

在本地开发阶段，推荐使用以下工具进行调试：

Local HTTPS —— 可以使用 mkcert 配置本地 HTTPS，或使用 ngrok 创建安全隧道。
Telegram 测试服务器 —— 避免直接对真实用户进行测试，确保开发环境安全。
浏览器 DevTools —— 便于调试和优化前端代码。

本地 HTTPS 配置示例：

“`bash

# Установка mkcert

brew install mkcert # для macOS

mkcert -install

mkcert localhost

# Запуск сервера с HTTPS

npx serve –ssl-cert localhost.pem –ssl-key localhost-key.pem

“`

常见坑点

1. 加载问题

一个常见的错误是应用程序太重，影响加载速度。以下方法可以优化性能：

“`javascript

// Ленивая загрузка изображений

const images = document.querySelectorAll(‘img[data-src]’);

const imageObserver = new IntersectionObserver((entries) => {

entries.forEach(entry => {

if (entry.isIntersecting) {

const img = entry.target;

img.src = img.dataset.src;

imageObserver.unobserve(img);

}

});

images.forEach(img => imageObserver.observe(img));

“`

2. 布局问题

使用 Telegram 的 CSS 变量来适配不同的界面：

“`css

:root {

–tg-viewport-height: 100vh;

–tg-viewport-stable-height: 100vh;

}

.app-container {

min-height: var(–tg-viewport-stable-height);

padding-bottom: var(–tg-viewport-height, 0px);

}

“`

3. 不清晰的 UI 设计

遵循 Telegram 的界面设计原则：

使用系统字体，以保持一致的视觉风格
支持深色模式，以提升用户体验
设计足够大的触控区域（最小 44×44 像素），方便点击

接下来做什么？

当基础版本准备就绪后：

将代码上传到支持 HTTPS 的服务器
通过 @BotFather 添加应用 URL
在真实环境中测试应用的运行情况
收集用户反馈并优化产品

推广应用

将应用添加到 @miniapps 目录——这是 Telegram Mini Apps 的官方列表
在 Telegram 开发者频道中推广您的应用
创建专属频道，用于发布更新和用户支持
通过 Google Analytics 或其他分析系统跟踪关键指标

从简单到复杂

先从小项目入手——开发一个能解决特定问题的简单应用。之后可以逐步添加新功能：

集成 TON 以支持支付
将数据存储到服务器
增加复杂逻辑和动画

以下是一个适合作为起点的简单应用示例——待办事项列表：

“`javascript

const todoApp = {

tasks: [],

init() {

this.setupUI();

this.loadTasks();

setupUI() {

const form = document.createElement(‘form’);

form.innerHTML = `

<button type=”submit”>Добавить</button>

form.onsubmit = (e) => {

e.preventDefault();

this.addTask();

};

document.querySelector(‘#app’).appendChild(form);

addTask() {

const input = document.querySelector(‘#new-task’);

const task = input.value.trim();

if (task) {

this.tasks.push(task);

this.renderTasks();

input.value = ”;

this.saveTasks();

}

renderTasks() {

const list = document.querySelector(‘#task-list’);

list.innerHTML = this.tasks

.map((task, index) => `

<li>

${task}

</li>

.join(”);

deleteTask(index) {

this.tasks.splice(index, 1);

this.renderTasks();

this.saveTasks();

saveTasks() {

// Отправляем данные боту

window.Telegram.WebApp.sendData(JSON.stringify({

type: ‘tasks’,

data: this.tasks

}));

loadTasks() {

// В реальном приложении здесь был бы запрос к серверу

this.tasks = [];

this.renderTasks();

}

};

todoApp.init();

“`

实用链接

Mini Apps 官方文档
Telegram Web App SDK
GitHub 上的 Mini Apps 示例
TON Connect 文档
Telegram 设计指南

如何从零开始创建您的第一个 Telegram Mini App

什么是 Telegram Mini Apps，为什么它们如此火爆？

成功的 Telegram Mini Apps 示例

如何开始开发

步骤 1：创建助手机器人

步骤 2：准备开发环境