HarmonyOS 7 / API 26 多设备任务续接：手机、平板和鸿蒙电脑之间状态怎么交接

多设备场景里，页面状态不能只放在当前组件里。设备切换后，当前页、筛选条件、未完成任务都要能恢复。 这类问题如果只看官方接口说明，通常只能知道“能力能不能用”；真放到工程里，还要继续回答：什么情况下会坏、怎么复现、失败以后页面怎么恢复、日志能不能解释、后面能不能复用。

本文按排查顺序写：先说明版本边界，再写两个可复现案例，然后比较几种处理方案，最后给一套可以落到项目里的 ContinuationStateAdapter 封装。重点不是堆 API 名称，而是把问题拆到开发者能验证、能复盘、能继续扩展的程度。

版本边界先固定

写 HarmonyOS 7 相关内容时，版本边界必须放在前面。Beta 阶段适合做适配、验证和问题定位，但不能把当前接口行为写成永远不变的结论。正式上架或提交活动文章前，还要回到官方版本说明里复核一次。

可复核的官方入口：

• HarmonyOS 版本概览：https://developer.huawei.com/consumer/cn/doc/harmonyos-releases/overview-allversion

• build-profile.json5 工程配置：https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/ide-hvigor-build-profile-app

• ArkTS / API 26 常见问题：https://developer.huawei.com/consumer/cn/doc/harmonyos-faqs/faqs-arkts-26

问题怎么发生

用户在手机上筛选内容，随后切到平板或鸿蒙电脑继续处理。如果没有状态快照，另一台设备只能打开首页，用户要重新操作。 这种问题的特点是：单看某一段代码都像是对的，但组合起来就会出问题。真正要排查的不是“有没有调用 API”，而是状态、版本、设备形态、异步顺序和失败兜底有没有对齐。

我通常先做三件事。第一，造一个稳定复现路径，不接受“偶现所以不好查”。第二，把成功、失败、取消、降级四条路径都打出日志。第三，把页面展示和业务执行拆开，避免所有逻辑都堆在组件里。

反例：页面里直接补判断

@Entry
@Component
struct ProblemPage {
  @State message: string = '等待处理'
  @State running: boolean = false

  async run() {
    this.running = true
    this.message = '处理中'
    await new Promise<void>((resolve) => setTimeout(resolve, 600))
    this.message = '处理完成'
    this.running = false
  }

  build() {
    Column({ space: 12 }) {
      Text(this.message).fontSize(16)
      Button(this.running ? '处理中' : '开始')
        .enabled(!this.running)
        .onClick(() => this.run())
    }.padding(16)
  }
}

这段代码的问题不是不能运行，而是只有成功路径。版本不满足怎么办，页面销毁后回调回来怎么办，用户连续触发怎么办，设备形态变化怎么办，失败以后怎么解释，都没有答案。短期补几个 if 看着快，后面排查会很慢。

案例一：先做版本和任务边界

type RunStage = 'version' | 'prepare' | 'run' | 'fallback' | 'done'

interface RunContext {
  traceId: string
  apiVersion: number
  releaseStage: 'Beta' | 'Release'
  source: string
}

interface GuardResult {
  passed: boolean
  stage: RunStage
  reason: string
}

class Api26Guard {
  static check(ctx: RunContext): GuardResult {
    if (ctx.apiVersion < 26) {
      return { passed: false, stage: 'version', reason: 'API version below 26' }
    }
    return { passed: true, stage: 'version', reason: 'API 26 path enabled' }
  }
}

这一步解决的是“能不能走当前路径”。很多问题不是后面的业务代码错了，而是一开始就没有判断当前设备、当前 API、当前入口是否满足条件。把版本判断收口成 guard，后面改支持范围时也不用到处翻页面。

案例二：再做请求序号和失败兜底

interface RunResult {
  traceId: string
  requestId: number
  stage: RunStage
  ok: boolean
  message: string
}

class ContinuationStateAdapter {
  private lastRequestId = 0
  private alive = true

  dispose() {
    this.alive = false
  }

  async run(ctx: RunContext): Promise<RunResult> {
    const requestId = ++this.lastRequestId
    const guard = Api26Guard.check(ctx)
    if (!guard.passed) {
      return { traceId: ctx.traceId, requestId, stage: guard.stage, ok: false, message: guard.reason }
    }

    await new Promise<void>((resolve) => setTimeout(resolve, 300))
    if (!this.alive || requestId !== this.lastRequestId) {
      return { traceId: ctx.traceId, requestId, stage: 'fallback', ok: false, message: 'stale result ignored' }
    }

    return { traceId: ctx.traceId, requestId, stage: 'done', ok: true, message: 'handled' }
  }
}

这里的 requestId 和 alive 标记很关键。用户连续触发、页面切走、设备形态变化、旧回调晚回来时，旧结果不能覆盖新状态。这个判断如果散落在页面里，很容易漏；放到 adapter 里，页面只消费最终结果。

两个复现场景

场景 A：只同步路由，不同步筛选条件，结果页面能打开但内容不对。 这个场景主要验证问题能不能稳定复现，以及页面有没有暴露错误状态。

场景 B：同步路由、筛选条件和任务进度，设备切换后继续原来的上下文。 这个场景主要验证修复后的边界处理，不只看成功路径，也要看取消、失败和恢复。

const cases: RunContext[] = [
  { traceId: 'case-low-api', apiVersion: 24, releaseStage: 'Release', source: 'phone' },
  { traceId: 'case-api26-main', apiVersion: 26, releaseStage: 'Beta', source: 'tablet' },
  { traceId: 'case-api26-repeat', apiVersion: 26, releaseStage: 'Beta', source: 'multi-window' }
]

const adapter = new ContinuationStateAdapter()
for (const item of cases) {
  adapter.run(item).then((result) => {
    console.info('[HarmonyCase]', JSON.stringify(result))
  })
}

这里至少要跑三类输入：低版本降级、API 26 正常路径、连续触发或窗口变化。只有一条成功路径不够，工程里的问题往往就藏在后两类输入里。

预期日志

[HarmonyCase] {"traceId":"case-low-api","stage":"version","ok":false,"message":"API version below 26"}
[HarmonyCase] {"traceId":"case-api26-main","stage":"done","ok":true,"message":"handled"}
[HarmonyCase] {"traceId":"case-api26-repeat","stage":"fallback","ok":false,"message":"stale result ignored"}

日志字段要固定。traceId 用来串起一次操作，stage 用来定位卡在哪一段，ok 表示最终是否成功，message 解释失败原因。线上遇到问题时，能从日志回到代码位置，比单纯打印 error 有用得多。

三种方案对比

我更倾向第三种。不是为了显得架构复杂，而是为了让每个失败点都能解释。页面负责展示，guard 负责能不能走当前路径，adapter 负责执行和兜底，日志负责复盘。

封装以后怎么复用

interface FeatureAdapter<T> {
  name: string
  minApiVersion: number
  run(ctx: RunContext): Promise<T>
  fallback(ctx: RunContext, reason: string): T
}

async function runFeature<T>(
  adapter: FeatureAdapter<T>,
  ctx: RunContext
): Promise<T> {
  if (ctx.apiVersion < adapter.minApiVersion) {
    return adapter.fallback(ctx, 'api version not matched')
  }

  try {
    return await adapter.run(ctx)
  } catch (err) {
    return adapter.fallback(ctx, String(err))
  }
}

这个封装可以继续扩展到 跨设备、多设备协同、状态快照、任务续接 之外的能力。只要新能力也有版本边界、执行阶段、失败兜底和日志要求，就可以复用同一套思路。

发布前怎么验证

• 能说清楚 HarmonyOS 7 / API 26 的版本边界。

• 至少有两个案例：一个复现问题，一个验证修复。

• 有低版本、失败、取消或旧回调的兜底路径。

• 有可复制的代码块，不只讲概念。

• 有日志输出，能证明问题发生在哪个阶段。

• 有方案对比，说明为什么选当前方案。

• 没有把 Beta 阶段能力写成永久稳定承诺。

总结

跨设备、多设备协同、状态快照、任务续接 这类文章要写出价值，不能只摘官方接口名。更可靠的写法是把版本边界、问题复现、失败路径、代码封装、日志验证和复用方式放在一起。这样读者拿到的不只是一个知识点，而是一套能放回工程里排查问题的方法。