WebApp 方法

window.Telegram.WebApp 对象提供以下方法来控制 Mini App 的行为和交互。

生命周期

ready

Telegram.WebApp.ready()

通知客户端 Mini App 已准备就绪，可以显示。建议在页面加载完成后尽早调用。

close

Telegram.WebApp.close()

关闭 Mini App。

isVersionAtLeast

Telegram.WebApp.isVersionAtLeast(version)

检查当前客户端版本是否满足要求。

参数	类型	必填	描述
version	String	是	需要的最低版本号，如 "7.10"

返回值：Boolean

UI 控制

setHeaderColor

Telegram.WebApp.setHeaderColor(color)

设置 Mini App 标题栏颜色。

参数	类型	必填	描述
color	String	是	颜色关键字（bg_color、secondary_bg_color）或十六进制颜色值

setBackgroundColor

Telegram.WebApp.setBackgroundColor(color)

设置 Mini App 背景颜色。

参数	类型	必填	描述
color	String	是	颜色关键字或十六进制颜色值

setBottomBarColor

Telegram.WebApp.setBottomBarColor(color)

设置底部栏颜色。Bot API 7.10+

参数	类型	必填	描述
color	String	是	颜色关键字或十六进制颜色值

enableClosingConfirmation

Telegram.WebApp.enableClosingConfirmation()

启用关闭确认。启用后，用户关闭 Mini App 时会弹出确认对话框。

disableClosingConfirmation

Telegram.WebApp.disableClosingConfirmation()

禁用关闭确认。

enableVerticalSwipes

Telegram.WebApp.enableVerticalSwipes()

启用垂直滑动手势，允许用户通过向下滑动关闭或最小化 Mini App。Bot API 7.7+

disableVerticalSwipes

Telegram.WebApp.disableVerticalSwipes()

禁用垂直滑动手势。Bot API 7.7+

requestFullscreen

Telegram.WebApp.requestFullscreen()

请求全屏模式。Bot API 8.0+

exitFullscreen

Telegram.WebApp.exitFullscreen()

退出全屏模式。Bot API 8.0+

lockOrientation

Telegram.WebApp.lockOrientation()

锁定当前屏幕方向。Bot API 8.0+

unlockOrientation

Telegram.WebApp.unlockOrientation()

解锁屏幕方向。Bot API 8.0+

展开与滚动

expand

Telegram.WebApp.expand()

将 Mini App 展开到最大可用高度。

requestViewport

Telegram.WebApp.requestViewport()

请求刷新视口信息。

数据与通信

sendData

Telegram.WebApp.sendData(data)

向 Bot 发送数据。调用后 Mini App 将关闭，数据将通过 web_app_data 服务消息发送给 Bot。

参数	类型	必填	描述
data	String	是	要发送的数据，长度 1-4096 字节

注意

此方法仅在 Mini App 通过 Keyboard Button 启动时可用。

switchInlineQuery

Telegram.WebApp.switchInlineQuery(query, chat_types)

切换到 inline 模式，在指定的聊天类型中插入 inline 查询。Bot API 6.7+

参数	类型	必填	描述
query	String	是	要插入的 inline 查询文本
chat_types	Array of String	否	允许的聊天类型："users"、"bots"、"groups"、"channels"

链接与导航

openLink

Telegram.WebApp.openLink(url, options)

在外部浏览器中打开链接。

参数	类型	必填	描述
url	String	是	要打开的 URL
options	Object	否	配置项
options.try_instant_view	Boolean	否	是否尝试使用 Instant View 打开

openTelegramLink

Telegram.WebApp.openTelegramLink(url)

在应用内打开 Telegram 链接。

参数	类型	必填	描述
url	String	是	Telegram 链接（https://t.me/...）

分享与社交

shareToStory

Telegram.WebApp.shareToStory(media_url, params)

分享内容到故事。Bot API 7.8+

参数	类型	必填	描述
media_url	String	是	媒体文件 URL（图片或视频）
params	Object	否	分享参数
params.text	String	否	附加文字说明
params.widget_link	Object	否	小组件链接
params.widget_link.url	String	否	链接 URL
params.widget_link.name	String	否	链接显示名称

shareMessage

Telegram.WebApp.shareMessage(msg_id, callback)

分享由 Bot 准备的消息到聊天。Bot API 8.0+

参数	类型	必填	描述
msg_id	String	是	由 Bot 预先准备的消息 ID
callback	Function	否	回调函数，参数 sent（Boolean）表示是否发送成功

setEmojiStatus

Telegram.WebApp.setEmojiStatus(custom_emoji_id, params, callback)

为用户设置自定义 emoji 状态。Bot API 8.0+

参数	类型	必填	描述
custom_emoji_id	String	是	自定义 emoji ID
params	Object	否	参数
params.duration	Integer	否	状态持续时间（秒）
callback	Function	否	回调函数，参数 set（Boolean）表示是否设置成功

downloadFile

Telegram.WebApp.downloadFile(params, callback)

请求下载文件。Bot API 8.0+

参数	类型	必填	描述
params	Object	是	下载参数
params.url	String	是	文件下载 URL
params.file_name	String	是	建议的文件名
callback	Function	否	回调函数，参数 accepted（Boolean）表示用户是否同意下载

事件

onEvent

Telegram.WebApp.onEvent(eventType, eventHandler)

订阅事件。详见事件系统。

参数	类型	必填	描述
eventType	String	是	事件名称
eventHandler	Function	是	事件处理函数

offEvent

Telegram.WebApp.offEvent(eventType, eventHandler)

取消订阅事件。

参数	类型	必填	描述
eventType	String	是	事件名称
eventHandler	Function	是	之前注册的事件处理函数

使用示例

const tg = window.Telegram.WebApp;

// 初始化
tg.ready();
tg.expand();

// 设置 UI
tg.setHeaderColor('#1a1a2e');
tg.setBackgroundColor('#16213e');
tg.enableClosingConfirmation();

// 监听主题变化
tg.onEvent('themeChanged', () => {
  console.log('主题已更新:', tg.colorScheme);
});

// 发送数据给 Bot
tg.MainButton.setText('提交');
tg.MainButton.onClick(() => {
  tg.sendData(JSON.stringify({ action: 'submit' }));
});
tg.MainButton.show();