Titanium SDK 中的 iOS UserActivity 模块详解

Titanium SDK 中的 iOS UserActivity 模块详解

【免费下载链接】titanium-sdk 🚀 Native iOS and Android Apps with JavaScript 项目地址: https://gitcode.com/gh_mirrors/ti/titanium-sdk

概述

在 Titanium SDK 中，Titanium.App.iOS.UserActivity 模块为开发者提供了实现 iOS 设备间 Handoff（接力）功能以及创建用户活动的能力。这个功能允许用户在一台设备上开始某项任务，然后在另一台设备上无缝继续同一任务。本文将深入解析这个模块的核心功能、使用方法和最佳实践。

核心概念

什么是 UserActivity？

UserActivity 是 iOS 提供的一种机制，用于：

1. 实现设备间的 Handoff 功能
2. 创建可被搜索和索引的用户活动
3. 支持 Siri 快捷方式（iOS 12+）

工作原理

当用户在一台设备上执行某项操作时，应用可以创建一个 UserActivity 对象来描述这个操作。系统会通过蓝牙低功耗（BLE）广播这个活动，其他登录了相同 iCloud 账户的设备可以接收并继续这个活动。

基本使用

创建 UserActivity

创建一个基本的 UserActivity 需要以下步骤：

var activity = Ti.App.iOS.createUserActivity({
    activityType: 'com.yourcompany.yourapp.activitytype',
    title: '正在编辑文档',
    userInfo: {
        documentId: '12345'
    }
});

必要条件

要使 Handoff 正常工作，必须满足以下条件：

• 所有设备登录相同的 iCloud 账户
• 设备支持蓝牙 4.0 低功耗（BLE）
• 设备连接到同一 Wi-Fi 网络

关键属性详解

activityType

这是最重要的属性，必须使用反向 DNS 命名方案，格式为：com.<公司>.<应用>.<活动类型>。例如：com.apple.mail.compose。

必须在 tiapp.xml 中注册：

<ti:app>
  <ios>
    <plist>
      <dict>
        <key>NSUserActivityTypes</key>
        <array>
          <string>com.yourcompany.yourapp.activitytype</string>
        </array>
      </dict>
    </plist>
  </ios>
</ti:app>

其他重要属性

1. eligibleForHandoff：是否允许接力到其他设备（默认 true）
2. eligibleForSearch：是否加入设备本地搜索索引（默认 false）
3. eligibleForPublicIndexing：是否允许公开索引（默认 false）
4. eligibleForPrediction：是否允许 Siri 建议此活动作为快捷方式（iOS 12+）
5. persistentIdentifier：用于唯一标识活动的字符串（iOS 12+）
6. webpageURL：当目标设备没有安装应用时的备用网页 URL

方法详解

becomeCurrent()

标记活动为当前活动，使其可以传递给其他设备：

activity.becomeCurrent();

invalidate()

当活动不再有效时调用，例如相关窗口关闭时：

activity.invalidate();

管理活动（iOS 12+）

// 删除特定活动
activity.deleteSavedUserActivitiesForPersistentIdentifiers(['identifier']);

// 删除所有活动
activity.deleteAllSavedUserActivities();

事件处理

continueactivity

当活动在另一台设备上继续时触发：

Ti.App.iOS.addEventListener('continueactivity', function(e) {
    if (e.activityType === 'com.yourcompany.yourapp.activitytype') {
        // 处理继续逻辑
    }
});

useractivitydeleted

当活动被删除时触发（iOS 12+）：

activity.addEventListener('useractivitydeleted', function(e) {
    Ti.API.info('活动已删除');
});

Siri 快捷方式集成（iOS 12+）

从 iOS 12 开始，UserActivity 可以捐赠给 Siri 作为快捷方式：

var activity = Ti.App.iOS.createUserActivity({
    activityType: 'com.yourcompany.yourapp.siri_shortcut',
    title: '打开最近文档',
    eligibleForPrediction: true,
    persistentIdentifier: 'open_recent_doc'
});
activity.becomeCurrent();

最佳实践

1. 合理设置 activityType：确保类型名称唯一且有意义
2. 及时更新活动状态：当活动内容变化时设置 needsSave = true
3. 合理使用 userInfo：只包含恢复状态所需的最小数据
4. 处理不支持情况：始终检查 isSupported()
5. 清理不再需要的活动：特别是与 Siri 快捷方式相关的活动

常见问题

1. Handoff 不工作：

   • 检查所有设备是否登录相同 iCloud
   • 确认蓝牙和 Wi-Fi 已开启
   • 验证 activityType 已在 tiapp.xml 中注册

2. Siri 不显示建议：

   • 确保 eligibleForPrediction 设为 true
   • 确认用户已执行过相关操作多次

3. 活动无法继续：

   • 检查 userInfo 是否包含所有必要信息
   • 验证目标设备上的应用版本能够处理该活动类型

通过合理使用 UserActivity 模块，开发者可以为用户提供无缝的多设备体验，同时利用 iOS 的搜索和 Siri 集成功能增强应用的可发现性和便捷性。

【免费下载链接】titanium-sdk 🚀 Native iOS and Android Apps with JavaScript 项目地址: https://gitcode.com/gh_mirrors/ti/titanium-sdk