Telegram WebApp 展示模式与返回按钮 API

Telegram WebApp 展示模式与返回按钮 API 总结

✅ 展示模式（Display Modes）

Telegram WebApp 提供三种展示模式，开发者可根据需要调用相应 API 控制 Web 应用的尺寸和行为。

1. 默认模式（Compact）

• 行为： 不调用任何扩展函数，WebApp 默认以“半屏模式”打开。
• 效果： 下方显示 WebApp 页面，上方保留 Telegram 聊天界面。
• 代码：

Telegram.WebApp.ready();
// 不调用 expand() 或 requestFullscreen()

---

2. Fullsize 模式（最大可用高度）

• 行为： 使用 expand() 使 WebApp 占据最大可用高度。
• 效果： 页面视觉上接近全屏，仅保留顶部导航栏。
• 代码：

Telegram.WebApp.ready();
Telegram.WebApp.expand();

---

3. Fullscreen 模式（真正全屏）

• 行为： 请求进入全屏，隐藏 Telegram 的顶部状态栏（仅部分客户端支持）。
• 效果： 真正的沉浸式全屏体验，Telegram 顶部栏消失。
• 代码：

Telegram.WebApp.ready();
Telegram.WebApp.expand(); // 通常一并使用
Telegram.WebApp.requestFullscreen?.(); // 可选链，避免旧版本报错

---

🔙 BackButton 返回按钮 API

Telegram WebApp 支持在页面中调用返回按钮（左上角的 ⬅️）并监听返回事件。

启用返回按钮

Telegram.WebApp.BackButton.show();

隐藏返回按钮

Telegram.WebApp.BackButton.hide();

监听用户点击返回按钮

Telegram.WebApp.BackButton.onClick(() => {
  // 在此执行返回逻辑，如导航回前一页
  history.back(); // 或自定义函数
});

取消监听

Telegram.WebApp.BackButton.offClick();

---

💡使用建议

• 在 SPA（单页面应用）中，通过 BackButton.onClick() 实现页面导航的返回控制，是常见的设计方式。
• 若页面具有导航栈，建议配合 window.history 控制返回行为。
• expand() 和 requestFullscreen() 可提升用户沉浸体验，但部分 Telegram 客户端版本或操作系统不完全支持 fullscreen。

---

📚 参考资料

• Telegram Web Apps API 文档
• 实际测试环境：iOS / Android Telegram 客户端、浏览器

---