Telegram WebApp API

📦 Telegram WebApp API 功能模块（概览）

🧩 基础配置与初始化

1
2
3
Telegram.WebApp.ready();
Telegram.WebApp.expand();
Telegram.WebApp.requestFullscreen?.();

✅ MainButton 主按钮

1
2
3
4
5
Telegram.WebApp.MainButton.setText("确认");
Telegram.WebApp.MainButton.show();
Telegram.WebApp.MainButton.onClick(() => {
  // 处理点击
});

🔙 返回按钮控制 BackButton

1
2
3
4
Telegram.WebApp.BackButton.show();
Telegram.WebApp.BackButton.hide();
Telegram.WebApp.BackButton.onClick(() => { ... });
Telegram.WebApp.BackButton.offClick(() => { ... });

💥 震动反馈 HapticFeedback

1
2
3
Telegram.WebApp.HapticFeedback.impactOccurred("light" | "medium" | "heavy" | "rigid" | "soft");
Telegram.WebApp.HapticFeedback.notificationOccurred("success" | "warning" | "error");
Telegram.WebApp.HapticFeedback.selectionChanged();

💬 弹窗反馈 UI提示

1
2
3
4
5
6
7
Telegram.WebApp.showAlert("纯提示");
Telegram.WebApp.showConfirm("是否确认").then(res => ...);
Telegram.WebApp.showPopup({
  title: "提示",
  message: "操作成功",
  buttons: [{ id: "ok", type: "ok", text: "好的" }]
});

🎨 外观控制

1
2
3
Telegram.WebApp.setHeaderColor("bg_color" | "secondary_bg_color");
Telegram.WebApp.setBackgroundColor(color);
Telegram.WebApp.setViewportHeight(height); // API可变

📱 页面控制（关闭/确认）

1
2
3
Telegram.WebApp.enableClosingConfirmation();   // 开启关闭确认提示
Telegram.WebApp.disableClosingConfirmation();  // 禁用关闭确认
Telegram.WebApp.close();

🧾 请求权限 RequestWriteAccess

1
Telegram.WebApp.requestWriteAccess().then(granted => ...);

🧍 用户信息

1
2
3
4
5
Telegram.WebApp.initDataUnsafe?.user?.id
Telegram.WebApp.initDataUnsafe?.user?.username
Telegram.WebApp.initDataUnsafe?.user?.language_code
Telegram.WebApp.initDataUnsafe?.user?.first_name
Telegram.WebApp.initDataUnsafe?.user?.last_name

📐 窗口信息

1
2
3
4
Telegram.WebApp.viewportStableHeight // 稳定高度
Telegram.WebApp.viewportHeight       // 当前高度
Telegram.WebApp.isExpanded           // 是否展开
Telegram.WebApp.isClosingConfirmationEnabled // 是否启用了关闭确认

📤 与主机器人通信 sendData

1
Telegram.WebApp.sendData("要发送给主机器人的数据字符串");

🔐 安全验证类

1
2
Telegram.WebApp.initData;         // 包含用户信息的编码数据
Telegram.WebApp.initDataUnsafe;   // 解码后的对象形式（推荐用来拿用户信息）

🌐 语言与平台信息

1
2
3
Telegram.WebApp.platform; // 例如："ios"、"android"
Telegram.WebApp.version;  // WebApp SDK 版本
Telegram.WebApp.themeParams; // 当前主题颜色

🧭 1. navigateTo(url, options)

•	作用：在 WebApp 中打开一个链接，可以选择新建窗口还是当前窗口

1
2
3
Telegram.WebApp.navigateTo("https://example.com", {
  try_instant_view: true,   // 尝试用 Telegram 的 Instant View 打开
});

🧪 2. Cloud Storage（云端存储）⚠️目前仅部分合作 WebApp 支持

1
2
3
4
5
6
7
8
9
Telegram.WebApp.CloudStorage.getItem("key", (value) => {
  console.log("取出值:", value);
});

Telegram.WebApp.CloudStorage.setItem("key", "value", (success) => {
  console.log(success ? "保存成功" : "保存失败");
});

Telegram.WebApp.CloudStorage.removeItem("key", callback);

📥 3. requestWriteAccess()

•	向用户请求将当前 WebApp 固定到聊天列表顶部

1
2
3
4
5
6
Telegram.WebApp.requestWriteAccess()
  .then((granted) => {
    if (granted) {
      // 用户允许固定 WebApp
    }
  });

🖼 4. themeParams 详细使用（自动适配主题颜色）

1
2
3
const theme = Telegram.WebApp.themeParams;
const bgColor = theme.bg_color || "#ffffff";
const textColor = theme.text_color || "#000000";

🔍 5. 判断当前 WebApp 运行环境

1
2
3
Telegram.WebApp.platform  // "android" / "ios" / "tdesktop" / "web" / "uninitialized"
Telegram.WebApp.isExpanded
Telegram.WebApp.isClosingConfirmationEnabled

🧵 6. viewportStableHeight 和 viewportHeight（视图高度）

• 实时响应窗口高度变化，常用于自适应布局

1
2
3
4
5
Telegram.WebApp.viewportHeight
Telegram.WebApp.viewportStableHeight
Telegram.WebApp.onEvent('viewportChanged', () => {
  // 视图变化时执行
});

✅ 全部常见事件绑定

1
2
3
4
5
Telegram.WebApp.onEvent('themeChanged', () => {});
Telegram.WebApp.onEvent('viewportChanged', () => {});
Telegram.WebApp.onEvent('mainButtonClicked', () => {});
Telegram.WebApp.onEvent('backButtonClicked', () => {});
Telegram.WebApp.offEvent('mainButtonClicked'); // 解绑事件

💡 灵感来源

  1. Telegram 官方 WebApp 文档
  2. Telegram WebApp 示例项目
  3. Telegram Desktop 和 Android 客户端源码（反编译查看 API 支持）