传感器

Mini App 支持访问设备的加速度计、陀螺仪和方向传感器。所有传感器 API 均需 Bot API 8.0+。

Accelerometer

加速度计，用于测量设备在三个轴上的加速度（含重力）。通过 Telegram.WebApp.Accelerometer 访问。

属性

属性	类型	描述
isStarted	Boolean	加速度计是否正在采集数据
x	Float	X 轴加速度（m/s²）
y	Float	Y 轴加速度（m/s²）
z	Float	Z 轴加速度（m/s²）

方法

start

Telegram.WebApp.Accelerometer.start(params, callback)

开始采集加速度数据。

参数	类型	必填	描述
params	Object	否	启动参数
params.refresh_rate	Integer	否	刷新频率（毫秒），默认 1000，范围 20-1000
callback	Function	否	回调函数，参数 (started)

stop

Telegram.WebApp.Accelerometer.stop(callback)

停止采集加速度数据。

参数	类型	必填	描述
callback	Function	否	回调函数，参数 (stopped)

示例

const accel = Telegram.WebApp.Accelerometer;

accel.start({ refresh_rate: 100 }, (started) => {
  if (started) {
    console.log('加速度计已启动');
  }
});

Telegram.WebApp.onEvent('accelerometerChanged', () => {
  console.log(`X: ${accel.x}, Y: ${accel.y}, Z: ${accel.z}`);
});

// 停止采集
// accel.stop();

DeviceOrientation

设备方向传感器，提供设备在三维空间中的朝向信息。通过 Telegram.WebApp.DeviceOrientation 访问。

属性

属性	类型	描述
isStarted	Boolean	传感器是否正在采集数据
absolute	Boolean	方向数据是否为绝对值（相对于地球坐标系）
alpha	Float	Z 轴旋转角度（0-360°）
beta	Float	X 轴旋转角度（-180° 到 180°）
gamma	Float	Y 轴旋转角度（-90° 到 90°）

方法

start

Telegram.WebApp.DeviceOrientation.start(params, callback)

开始采集设备方向数据。

参数	类型	必填	描述
params	Object	否	启动参数
params.refresh_rate	Integer	否	刷新频率（毫秒），默认 1000，范围 20-1000
params.need_absolute	Boolean	否	是否需要绝对方向数据，默认 false
callback	Function	否	回调函数，参数 (started)

stop

Telegram.WebApp.DeviceOrientation.stop(callback)

停止采集设备方向数据。

参数	类型	必填	描述
callback	Function	否	回调函数，参数 (stopped)

示例

const orientation = Telegram.WebApp.DeviceOrientation;

orientation.start({
  refresh_rate: 100,
  need_absolute: true
}, (started) => {
  if (started) {
    console.log('设备方向传感器已启动');
  }
});

Telegram.WebApp.onEvent('deviceOrientationChanged', () => {
  console.log(`Alpha: ${orientation.alpha}`);
  console.log(`Beta: ${orientation.beta}`);
  console.log(`Gamma: ${orientation.gamma}`);
  console.log(`绝对值: ${orientation.absolute}`);
});

Gyroscope

陀螺仪，用于测量设备在三个轴上的角速度。通过 Telegram.WebApp.Gyroscope 访问。

属性

属性	类型	描述
isStarted	Boolean	陀螺仪是否正在采集数据
x	Float	X 轴角速度（rad/s）
y	Float	Y 轴角速度（rad/s）
z	Float	Z 轴角速度（rad/s）

方法

start

Telegram.WebApp.Gyroscope.start(params, callback)

开始采集陀螺仪数据。

参数	类型	必填	描述
params	Object	否	启动参数
params.refresh_rate	Integer	否	刷新频率（毫秒），默认 1000，范围 20-1000
callback	Function	否	回调函数，参数 (started)

stop

Telegram.WebApp.Gyroscope.stop(callback)

停止采集陀螺仪数据。

参数	类型	必填	描述
callback	Function	否	回调函数，参数 (stopped)

示例

const gyro = Telegram.WebApp.Gyroscope;

gyro.start({ refresh_rate: 50 }, (started) => {
  if (started) {
    console.log('陀螺仪已启动');
  }
});

Telegram.WebApp.onEvent('gyroscopeChanged', () => {
  console.log(`角速度 X: ${gyro.x}, Y: ${gyro.y}, Z: ${gyro.z}`);
});

注意事项

• 所有传感器 API 均需 Bot API 8.0+
• 并非所有设备都支持传感器，请监听相应的 *Failed 事件处理不支持的情况
• 使用完毕后请调用 stop() 方法释放传感器资源，节省电量
• refresh_rate 值越小，数据更新越频繁，但也更耗电