文档开发者中心
我的
|

Ability Kit

应用接续实战:从手机到平板,让用户的操作“跟着走”

一、引言:用户不想“重新来一遍”

你有没有遇到过这样的场景:手机上正在编辑一篇笔记,想换到平板上继续写,结果打开平板上的同一个应用,还得重新找到那篇笔记、重新打开、再滚动到刚才编辑的位置——用户的操作状态完全没有“跟过来”。

应用接续(Continuation) 要解决的就是这个问题。它让用户在一个设备上操作应用时,能够在另一个设备上快速切换并继续该应用的任务,实现无缝衔接的使用体验。比如在手机上浏览文章到一半,换到平板上接着看,浏览器的滚动位置、阅读进度都能完美同步。

今天这篇,我们从配置 → 数据保存 → 数据恢复,完整走一遍应用接续的落地流程。

二、先搞懂:应用接续的核心流程

应用接续的完整流程可以分为三步:

  1. 源端保存状态:用户触发迁移,系统回调源端 UIAbility 的 onContinue() 接口,开发者在这里把当前页面的关键数据保存下来

  2. 系统传输数据:HarmonyOS 将保存的数据传输到目标设备

  3. 目标端恢复状态:目标设备上的 UIAbility 启动,开发者从 want 中读取数据,恢复页面状态

关键认知:应用接续传输的数据量有限制。官方建议 wantParam 小于 100KB。如果数据量较大(如长文本、图片等),应使用分布式数据对象或分布式数据库来传输。

三、Step 1:开启应用接续能力

在 module.json5 文件的 abilities 中,将 continuable 标签配置为 true,表示该 UIAbility 可被迁移。

收起
自动换行
深色代码主题
复制
{
  "module": {
    "abilities": [
      {
        "name": "EntryAbility",
        "continuable": true,   // 开启应用接续
        // ... 其他配置
      }
    ]
  }
}

四、Step 2:源端保存状态(onContinue)

当应用触发迁移时,系统会回调源端 UIAbility 的 onContinue() 接口。开发者在这个接口中完成两件事:

  1. 保存关键数据:把当前页面的关键信息(如文本内容、当前页面路由、滚动位置等)通过键值对的方式保存在 wantParam 中

  2. 版本兼容性检测:从 wantParam.version 获取对端应用的版本号,与源端版本比对,判断是否支持此次迁移

    收起
    自动换行
    深色代码主题
    复制
    import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit';
    
    export default class EntryAbility extends UIAbility {
      // 源端:保存迁移数据
      async onContinue(wantParam: Record<string, Object>) {
        // 1. 版本兼容性检测
        const targetVersion = wantParam.version as number;
        if (targetVersion < 3) {
          // 对端版本太低,不支持迁移
          return AbilityConstant.OnContinueResult.MISMATCH;
        }
        
        // 2. 保存页面状态数据
        // 从 NavPathStack 或页面状态中获取当前页面信息
        wantParam['pagePath'] = this.currentPagePath;   // 当前页面路由
        wantParam['pageParams'] = this.currentPageParams; // 页面参数
        wantParam['contentId'] = this.currentContentId;   // 内容ID
        wantParam['scrollPosition'] = this.scrollPosition; // 滚动位置
        
        // 3. 返回同意迁移
        return AbilityConstant.OnContinueResult.AGREE;
      }
    }

    五、Step 3:目标端恢复状态(onCreate / onNewWant)

    在目标端设备上,UIAbility 启动时通过 launchParam.launchReason 判断是否为应用接续场景。如果是,就从 want 中读取保存的数据,恢复页面状态。

    收起
    自动换行
    深色代码主题
    复制
    onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
      // 判断是否为应用接续场景
      if (launchParam.launchReason !== AbilityConstant.LaunchReason.CONTINUATION) {
        // 非接续场景,走正常启动流程
        return;
      }
      
      // 恢复迁移数据
      this.restoreData(want);
    }
    
    private restoreData(want: Want) {
      const pagePath = want.parameters?.pagePath as string;
      const pageParams = want.parameters?.pageParams as Record<string, Object>;
      const contentId = want.parameters?.contentId as string;
      const scrollPosition = want.parameters?.scrollPosition as number;
      
      // 将数据保存到 AppStorage 或 LocalStorage
      AppStorage.setOrCreate('pagePath', pagePath);
      AppStorage.setOrCreate('pageParams', pageParams);
      AppStorage.setOrCreate('contentId', contentId);
      AppStorage.setOrCreate('scrollPosition', scrollPosition);
    }

    ⚠️ 单实例应用(singleton 模式)的额外处理:如果 UIAbility 是单实例模式,在目标端设备上可能已经存在实例,此时系统会回调 onNewWant() 而不是 onCreate()。需要在 onNewWant() 中也做同样的数据恢复逻辑。

    收起
    自动换行
    深色代码主题
    复制
    onNewWant(want: Want, launchParam: AbilityConstant.LaunchParam): void {
      if (launchParam.launchReason !== AbilityConstant.LaunchReason.CONTINUATION) {
        return;
      }
      this.restoreData(want);
    }

    六、进阶:快速拉起——让用户少等一会儿

    常规的应用接续流程是:源端先保存数据,等数据传输完成,目标端再启动应用。如果数据量较大,用户可能需要等待几秒钟。

    快速拉起(Quick Start) 功能支持在用户触发迁移、等待迁移数据返回的过程中,并行拉起目标应用,减小用户等待时间。

    开启方式:在 module.json5 配置文件的 continueType 标签的取值中添加 "_ContinueQuickStart" 后缀。

    收起
    自动换行
    深色代码主题
    复制
    {
      "module": {
        "abilities": [
          {
            "name": "EntryAbility",
            "continuable": true,
            "continueType": "migration_ContinueQuickStart"  // 开启快速拉起
          }
        ]
      }
    }

    开启后,目标端应用会在数据到达前先拉起界面占位,待数据传输完成后再刷新内容。配合 continueManager.on('prepareContinue', ...) 可以监听快速拉起的结果。

    七、适用场景与数据量控制

    典型适用场景:

  3. 笔记/文档编辑页面的进度同步

  4. 购物车内容跨设备继续下单

  5. 浏览器阅读进度同步

  6. 视频播放进度接续

  7. 数据量控制:

  8. wantParam 建议小于 100KB

  9. 大数据(如长文本、图片、文件)使用分布式数据对象或分布式数据库

  10. 迁移时只传最小必要状态(如内容ID、页面路由、会话ID、版本号),目标端根据ID重新拉取完整数据

  11. 目标端已有 UIAbility 实例,迁移数据只在 onCreate 中恢复,onNewWant 没处理,导致数据丢失。

    ✅ 解法:onCreate 和 onNewWant 都要做数据恢复。

    九、结语

    应用接续的核心就是存状态、传数据、恢现场三步。配置好 continuable: true,在 onContinue 里保存最小必要数据,在目标端 onCreate/onNewWant 里恢复,就能让用户的操作“跟着走”。

    记住三个核心原则:

  12. 只传最小状态——ID+路由,大数据走分布式数据对象

  13. 版本要兼容——不兼容时返回 MISMATCH

  14. 单实例要双处理——onCreate 和 onNewWant 都要恢复数据

  15. 八、常见踩坑点

    坑1:忘记在 module.json5 中配置 continuable: true

    onContinue() 不会被回调,迁移失败。

    ✅ 解法:在 UIAbility 的配置中加上 "continuable": true。

    坑2:数据量太大导致迁移失败

    在 wantParam 里塞了十几 MB 的数据,迁移超时或失败。

    ✅ 解法:只传最小必要状态(ID+路由),大数据用分布式数据对象。

    坑3:目标端版本不兼容时没有返回 MISMATCH

    对端版本太低,但 onContinue() 返回了 AGREE,导致目标端恢复数据时出错。

    ✅ 解法:在 onContinue() 中做版本兼容性检测,不兼容时返回 MISMATCH。

    坑4:单实例应用忘记实现 onNewWant

点赞
收藏
回复
分享
举报
浏览82 发布于2026-09-07 03:03天津
全部评论
最多点赞
最新发布
最早发布
暂无评论
暂无评论
写回答
新增插入模板功能
一键使用模板,快速填写内容,轻松发帖~
知道了
  • 为了保障您的信息安全,请勿上传您的敏感个人信息(如您的密码等信息)和您的敏感资产信息(如关键源代码、签名私钥、调试安装包、业务日志等信息),且您需自行承担由此产生的信息泄露等安全风险。
  • 如您发布的内容为转载内容,请注明内容来源。

我要发帖子

目录 收起
一、引言:用户不想“重新来一遍”
二、先搞懂:应用接续的核心流程
三、Step 1:开启应用接续能力
四、Step 2:源端保存状态(onContinue)
五、Step 3:目标端恢复状态(onCreate / onNewWant)
六、进阶:快速拉起——让用户少等一会儿
七、适用场景与数据量控制
九、结语
八、常见踩坑点
了解社区公约,与您携手共创和谐专业的开发者社区。