SafeW API

简体中文

English

简体中文

English

主题

事件系统 ​

Mini App 通过事件系统与客户端通信。使用 Telegram.WebApp.onEvent() 订阅事件，使用 Telegram.WebApp.offEvent() 取消订阅。

javascript
// 订阅事件
Telegram.WebApp.onEvent(eventType, eventHandler);

// 取消订阅
Telegram.WebApp.offEvent(eventType, eventHandler);

生命周期事件 ​

activated ​

Mini App 进入活跃状态时触发。Bot API 8.0+

deactivated ​

Mini App 进入非活跃状态时触发。Bot API 8.0+

视图事件 ​

themeChanged ​

客户端主题发生变化时触发。

javascript
Telegram.WebApp.onEvent('themeChanged', () => {
  console.log('新主题:', Telegram.WebApp.colorScheme);
  console.log('主题参数:', Telegram.WebApp.themeParams);
});

viewportChanged ​

Mini App 视口尺寸变化时触发。

回调参数：Object

字段类型描述
isStateStableBoolean视口变化是否已稳定
javascript
Telegram.WebApp.onEvent('viewportChanged', (event) => {
  if (event.isStateStable) {
    console.log('视口高度:', Telegram.WebApp.viewportHeight);
  }
});

safeAreaChanged ​

设备安全区域变化时触发。Bot API 8.0+

contentSafeAreaChanged ​

内容安全区域变化时触发。Bot API 8.0+

fullscreenChanged ​

全屏模式状态变化时触发。Bot API 8.0+

fullscreenFailed ​

请求全屏失败时触发。Bot API 8.0+

回调参数：Object

字段类型描述
errorString错误原因："UNSUPPORTED" 或 "ALREADY_FULLSCREEN"

按钮事件 ​

backButtonClicked ​

返回按钮被点击时触发。

javascript
Telegram.WebApp.onEvent('backButtonClicked', () => {
  window.history.back();
});

mainButtonClicked ​

主按钮被点击时触发。

secondaryButtonClicked ​

次要按钮被点击时触发。Bot API 7.10+

settingsButtonClicked ​

设置按钮被点击时触发。Bot API 7.0+

交互事件 ​

popupClosed ​

弹窗关闭时触发。

回调参数：Object

字段类型描述
button_idString | null用户点击的按钮 ID，如果用户关闭弹窗则为 null

qrTextReceived ​

QR 码扫描成功时触发。Bot API 6.9+

回调参数：Object

字段类型描述
dataString扫描到的文本内容

scanQrPopupClosed ​

QR 码扫描弹窗关闭时触发。Bot API 7.7+

clipboardTextReceived ​

读取剪贴板内容完成时触发。Bot API 6.9+

回调参数：Object

字段类型描述
dataString | null剪贴板文本内容，如果读取失败则为 null

invoiceClosed ​

发票支付界面关闭时触发。

回调参数：Object

字段类型描述
urlString发票链接
statusString支付状态："paid"、"cancelled"、"failed"、"pending"

writeAccessRequested ​

请求写入权限的结果。Bot API 6.9+

回调参数：Object

字段类型描述
statusString结果："allowed" 或 "cancelled"

contactRequested ​

请求联系人信息的结果。Bot API 6.9+

回调参数：Object

字段类型描述
statusString结果："sent" 或 "cancelled"

分享事件 ​

shareMessageSent ​

消息分享成功时触发。Bot API 8.0+

shareMessageFailed ​

消息分享失败时触发。Bot API 8.0+

回调参数：Object

字段类型描述
errorString错误原因："UNSUPPORTED"、"MESSAGE_EXPIRED"、"MESSAGE_SEND_FAILED"、"USER_DECLINED"

emojiStatusSet ​

Emoji 状态设置成功时触发。Bot API 8.0+

emojiStatusFailed ​

Emoji 状态设置失败时触发。Bot API 8.0+

回调参数：Object

字段类型描述
errorString错误原因："UNSUPPORTED"、"SUGGESTED_EMOJI_INVALID"、"DURATION_INVALID"、"USER_DECLINED"

emojiStatusAccessRequested ​

请求 emoji 状态权限的结果。Bot API 8.0+

回调参数：Object

字段类型描述
statusString结果："allowed" 或 "cancelled"

fileDownloadRequested ​

文件下载请求结果。Bot API 8.0+

回调参数：Object

字段类型描述
statusString结果："downloading" 或 "cancelled"

传感器事件 ​

accelerometerStarted ​

加速度计开始采集时触发。Bot API 8.0+

accelerometerStopped ​

加速度计停止采集时触发。Bot API 8.0+

accelerometerChanged ​

加速度计数据更新时触发。Bot API 8.0+

accelerometerFailed ​

加速度计启动失败时触发。Bot API 8.0+

回调参数：Object

字段类型描述
errorString错误原因："UNSUPPORTED"

deviceOrientationStarted ​

设备方向传感器开始采集时触发。Bot API 8.0+

deviceOrientationStopped ​

设备方向传感器停止采集时触发。Bot API 8.0+

deviceOrientationChanged ​

设备方向数据更新时触发。Bot API 8.0+

deviceOrientationFailed ​

设备方向传感器启动失败时触发。Bot API 8.0+

回调参数：Object

字段类型描述
errorString错误原因："UNSUPPORTED"

gyroscopeStarted ​

陀螺仪开始采集时触发。Bot API 8.0+

gyroscopeStopped ​

陀螺仪停止采集时触发。Bot API 8.0+

gyroscopeChanged ​

陀螺仪数据更新时触发。Bot API 8.0+

gyroscopeFailed ​

陀螺仪启动失败时触发。Bot API 8.0+

回调参数：Object

字段类型描述
errorString错误原因："UNSUPPORTED"

位置事件 ​

locationManagerUpdated ​

位置管理器状态更新时触发。Bot API 8.0+

locationRequested ​

位置请求结果。Bot API 8.0+

回调参数：Object

字段类型描述
locationDataLocationData位置数据对象，请求失败时为 null

生物识别事件 ​

biometricManagerUpdated ​

生物识别管理器状态更新时触发。Bot API 7.2+

biometricAuthRequested ​

生物识别认证结果。Bot API 7.2+

回调参数：Object

字段类型描述
isAuthenticatedBoolean认证是否成功
biometricTokenString认证成功时返回的 token

biometricTokenUpdated ​

生物识别 token 更新结果。Bot API 7.2+

回调参数：Object

字段类型描述
isUpdatedBooleantoken 是否更新成功

使用示例 ​

javascript
const tg = Telegram.WebApp;

// 监听多个事件
tg.onEvent('viewportChanged', (e) => {
  if (e.isStateStable) {
    adjustLayout();
  }
});

tg.onEvent('themeChanged', () => {
  applyTheme(tg.themeParams);
});

tg.onEvent('popupClosed', (e) => {
  if (e.button_id === 'confirm') {
    handleConfirm();
  }
});

tg.onEvent('invoiceClosed', (e) => {
  if (e.status === 'paid') {
    showSuccess();
  }
});