UI 组件

Mini App 提供多种原生 UI 组件，可通过 Telegram.WebApp 对象访问。

BackButton

返回按钮，显示在 Mini App 标题栏左侧。

属性

属性	类型	描述
isVisible	Boolean	返回按钮当前是否可见

方法

方法	描述
show()	显示返回按钮
hide()	隐藏返回按钮
onClick(callback)	注册点击事件回调
offClick(callback)	移除点击事件回调

示例

const backButton = Telegram.WebApp.BackButton;

backButton.show();
backButton.onClick(() => {
  // 处理返回逻辑
  window.history.back();
});

BottomButton

底部按钮组件，包括主按钮（MainButton）和次要按钮（SecondaryButton）。

MainButton 是 Mini App 底部的全宽按钮，常用于提交或确认操作。SecondaryButton 是 Bot API 7.10+ 新增的次要按钮。

属性

属性	类型	描述
type	String	按钮类型："main" 或 "secondary"
text	String	按钮上显示的文字（最多 64 个字符）
color	String	按钮背景颜色
textColor	String	按钮文字颜色
isVisible	Boolean	按钮是否可见
isActive	Boolean	按钮是否可点击
hasShineEffect	Boolean	按钮是否显示光泽效果。Bot API 7.10+
position	String	按钮位置："left"、"right"、"top"、"bottom"。Bot API 7.10+
isProgressVisible	Boolean	是否显示加载进度指示器

方法

方法	描述
setText(text)	设置按钮文字
show()	显示按钮
hide()	隐藏按钮
enable()	启用按钮
disable()	禁用按钮
showProgress(leaveActive)	显示加载进度。leaveActive 为 true 时按钮保持可点击
hideProgress()	隐藏加载进度
setParams(params)	批量设置按钮参数
onClick(callback)	注册点击事件回调
offClick(callback)	移除点击事件回调

setParams

Telegram.WebApp.MainButton.setParams({
  text: '提交',
  color: '#2481cc',
  text_color: '#ffffff',
  has_shine_effect: true,
  is_active: true,
  is_visible: true
})

参数	类型	必填	描述
text	String	否	按钮文字
color	String	否	按钮背景颜色
text_color	String	否	文字颜色
has_shine_effect	Boolean	否	是否显示光泽效果
position	String	否	按钮位置（仅 SecondaryButton）
is_active	Boolean	否	是否可点击
is_visible	Boolean	否	是否可见

示例

const mainButton = Telegram.WebApp.MainButton;

mainButton.setText('确认支付');
mainButton.color = '#31b545';
mainButton.textColor = '#ffffff';

mainButton.onClick(() => {
  mainButton.showProgress();
  // 处理支付逻辑...
  setTimeout(() => {
    mainButton.hideProgress();
  }, 2000);
});

mainButton.show();

SettingsButton

设置按钮，显示在 Mini App 的更多菜单中。Bot API 7.0+

属性

属性	类型	描述
isVisible	Boolean	设置按钮是否可见

方法

方法	描述
show()	显示设置按钮
hide()	隐藏设置按钮
onClick(callback)	注册点击事件回调
offClick(callback)	移除点击事件回调

示例

const settingsButton = Telegram.WebApp.SettingsButton;

settingsButton.show();
settingsButton.onClick(() => {
  // 打开设置页面
  navigateTo('/settings');
});

HapticFeedback

触觉反馈控制器，提供三种类型的振动反馈。

方法

impactOccurred

Telegram.WebApp.HapticFeedback.impactOccurred(style)

触发碰撞类型的触觉反馈。

参数	类型	必填	描述
style	String	是	碰撞强度："light"、"medium"、"heavy"、"rigid"、"soft"

notificationOccurred

Telegram.WebApp.HapticFeedback.notificationOccurred(type)

触发通知类型的触觉反馈。

参数	类型	必填	描述
type	String	是	通知类型："error"、"success"、"warning"

selectionChanged

Telegram.WebApp.HapticFeedback.selectionChanged()

触发选择变化类型的触觉反馈，通常用于用户改变选择项时。

示例

const haptic = Telegram.WebApp.HapticFeedback;

// 按钮点击反馈
document.getElementById('btn').addEventListener('click', () => {
  haptic.impactOccurred('medium');
});

// 操作成功反馈
function onSuccess() {
  haptic.notificationOccurred('success');
}

// 选择变化反馈
document.querySelectorAll('.option').forEach(el => {
  el.addEventListener('click', () => {
    haptic.selectionChanged();
  });
});