Titanium SDK 手势模块深度解析：设备方向与摇动检测-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00348/article/details/148782541

Titanium SDK 手势模块深度解析：设备方向与摇动检测

titanium-sdk 🚀 Native iOS and Android Apps with JavaScript 项目地址: https://gitcode.com/gh_mirrors/ti/titanium-sdk

概述

在移动应用开发中，手势识别是提升用户体验的重要环节。Titanium SDK 提供的 Gesture 模块专门处理设备级别的高级手势操作，主要包括设备方向变化检测和摇动手势识别两大功能。本文将深入解析该模块的核心功能、使用方法和注意事项。

设备方向检测

方向状态属性

Gesture 模块提供了两个布尔属性来快速判断当前设备方向状态：

portrait - 设备处于竖屏模式时返回 true
landscape - 设备处于横屏模式时返回 true

这两个属性在 Android、iOS 和 macOS 平台上均可用，且为只读属性。

精确方向判断

如果需要更精确的方向信息，可以使用 orientation 属性，它返回以下常量之一：

Titanium.UI.PORTRAIT - 标准竖屏
Titanium.UI.UPSIDE_PORTRAIT - 倒置竖屏
Titanium.UI.LANDSCAPE_LEFT - 横屏（设备左侧朝下）
Titanium.UI.LANDSCAPE_RIGHT - 横屏（设备右侧朝下）
Titanium.UI.FACE_UP - 设备屏幕朝上
Titanium.UI.FACE_DOWN - 设备屏幕朝下
Titanium.UI.UNKNOWN - 未知方向

重要说明：在 iOS 和 Windows 平台上，此属性返回的是设备的实际物理方向，而非窗口方向。要获取窗口方向，应使用 Window.orientation 属性。

方向变化事件

orientationchange 事件

当设备方向发生变化时，会触发 orientationchange 事件。事件对象包含 orientation 属性，表示新的设备方向。

Android 平台特殊说明：

应用必须至少打开一个 heavyweight 窗口或标签组才能接收此事件
该窗口不必是最顶层的窗口
大多数实际应用都会满足此条件，仅在没有打开窗口的测试场景中可能遇到问题

事件监听示例

Ti.Gesture.addEventListener('orientationchange', function(e) {
    console.log('新方向:', e.orientation);
    if (e.orientation === Ti.UI.PORTRAIT) {
        console.log('现在是竖屏模式');
    } else if (e.orientation === Ti.UI.LANDSCAPE_LEFT || 
               e.orientation === Ti.UI.LANDSCAPE_RIGHT) {
        console.log('现在是横屏模式');
    }
});

摇动手势检测

shake 事件

当用户摇动设备时，会触发一系列 shake 事件。每个事件对象包含以下属性：

timestamp - 与前一个摇动事件的时间间隔（Android 为毫秒，iOS 为秒）
x - X 轴加速度（以 G 为单位）
y - Y 轴加速度（以 G 为单位）
z - Z 轴加速度（以 G 为单位）

iOS 平台特殊说明：

一系列摇动事件中的第一个事件的 timestamp 值为 0

摇动检测示例

Ti.Gesture.addEventListener('shake', function(e) {
    console.log('检测到摇动手势');
    console.log('时间间隔:', e.timestamp);
    console.log('加速度 - X:', e.x, 'Y:', e.y, 'Z:', e.z);
});

性能优化

停止监听器

从 Titanium SDK 12.1.0 开始，Android 平台提供了 stopListener 方法。当您只需要一次性检查方向状态时，可以使用此方法停止持续监听以节省资源：

// 检查当前方向
if (Ti.Gesture.landscape) {
    console.log('当前是横屏模式');
}

// 停止监听以节省资源
Ti.Gesture.stopListener();

最佳实践

方向变化处理：
- 对于复杂的布局调整，建议使用 orientationchange 事件而非持续轮询方向状态
- 考虑添加适当的动画效果使方向切换更平滑
摇动手势：
- 由于摇动会触发一系列事件，建议添加去抖逻辑避免重复处理
- 可以结合加速度数据实现更精确的手势识别
跨平台兼容性：
- 测试不同平台上的方向变化行为差异
- 注意 Android 上需要 heavyweight 窗口才能接收方向变化事件