还记得当年 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>
<meta charset=”UTF-8″>
<meta name=”viewport” content=”width=device-width, initial-scale=1.0″>
<title>Моё первое TMA</title>
<link rel=”stylesheet” href=”styles/main.css”>
<script src=”https://telegram.org/js/telegram-web-app.js”></script>
</head>
<body>
<div id=”app”>
<h1>Привет, Telegram!</h1>
</div>
<script src=”scripts/app.js”></script>
</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>
<button id=”increment”>+1</button>
<button id=”decrement”>-1</button>
`;
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 = `
<input type=”text” id=”new-task” placeholder=”Новая задача”>
<button type=”submit”>Добавить</button>
<ul id=”task-list”></ul>
`;
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}
<button onclick=”todoApp.deleteTask(${index})”>✕</button>
</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 设计指南
