前言

应用前后台状态监听是移动开发中的常见需求，用于暂停/恢复动画、保存临时数据、控制网络请求等场景。@pura/harmony-utils 的 AppUtil 提供了便捷的前后台状态监听方法，开发者无需手动注册 AbilityLifecycleCallbacks，即可轻松感知应用状态变化。本文将从API说明、代码实战、进阶用法、常见问题等多个维度进行全面讲解，帮助开发者快速掌握并应用到实际项目中。

一、前后台监听核心API

AppUtil 提供了以下前后台监听方法，支持注册和取消监听：

方法	说明	参数	返回类型
onForeground(callback)	监听应用切到前台	() => void	void
onBackground(callback)	监听应用切到后台	() => void	void
offForeground(callback)	取消前台监听	() => void	void
offBackground(callback)	取消后台监听	() => void	void

1.1 核心特性

• 简洁易用：无需手动注册AbilityLifecycleCallbacks，一行代码即可监听
• 回调机制：基于回调函数的事件驱动模式，灵活高效
• 生命周期安全：支持注册和取消，避免内存泄漏
• 主线程执行：回调在主线程执行，可直接更新UI

1.2 前后台回调适用场景

场景	前台回调	后台回调
动画控制	恢复动画	暂停动画
定时任务	重启定时器	清除定时器
数据保存	-	保存草稿数据
网络请求	恢复轮询	暂停轮询
播放器	继续播放	暂停播放

二、完整使用步骤

2.1 安装依赖

ohpm install @pura/harmony-utils

2.2 监听前后台切换

import { AppUtil } from '@pura/harmony-utils';

@Entry
@Component
struct ForegroundDemo {
  @State result: string = '';
  private foregroundCallback = () => {
    this.result = '应用已切到前台 ✅\n可以恢复动画和网络请求';
  };
  private backgroundCallback = () => {
    this.result = '应用已切到后台 ⏸️\n建议暂停动画和定时任务';
  };

  aboutToAppear() {
    AppUtil.onForeground(this.foregroundCallback);
    AppUtil.onBackground(this.backgroundCallback);
  }

  aboutToDisappear() {
    AppUtil.offForeground(this.foregroundCallback);
    AppUtil.offBackground(this.backgroundCallback);
  }

  build() {
    Column({ space: 12 }) {
      Button('检查监听状态')
        .width('100%')
        .onClick(() => {
          this.result = '前后台监听已注册\n切换应用即可触发回调';
        });
      Text(this.result).fontSize(14).fontColor('#333333')
    }
    .padding(16)
  }
}

三、实际应用场景

3.1 暂停/恢复动画

AppUtil.onBackground(() => {
  this.pauseAnimation();
});
AppUtil.onForeground(() => {
  this.resumeAnimation();
});

3.2 保存临时数据

import { AppUtil, PreferencesUtil } from '@pura/harmony-utils';

AppUtil.onBackground(() => {
  PreferencesUtil.putString('draft', this.draftContent);
});

3.3 控制定时器

AppUtil.onBackground(() => {
  clearInterval(this.timerId);
});
AppUtil.onForeground(() => {
  this.startTimer();
});

四、进阶用法

4.1 封装前后台管理器

import { AppUtil } from '@pura/harmony-utils';

class AppLifecycleManager {
  private callbacks: Array<() => void> = [];

  registerOnForeground(callback: () => void) {
    AppUtil.onForeground(callback);
    this.callbacks.push(callback);
  }

  registerOnBackground(callback: () => void) {
    AppUtil.onBackground(callback);
    this.callbacks.push(callback);
  }

  unregisterAll() {
    this.callbacks.forEach(cb => {
      AppUtil.offForeground(cb);
      AppUtil.offBackground(cb);
    });
    this.callbacks = [];
  }
}

五、注意事项

1. 生命周期管理：务必在 aboutToDisappear 中取消监听，避免内存泄漏
2. 回调引用：注册和取消监听需使用同一个回调引用
3. 主线程执行：回调在主线程执行，避免耗时操作
4. 初始化依赖：使用前需确保 AppUtil.init() 已调用
5. 多次注册：避免对同一个回调重复注册

六、常见问题

Q1: 回调没有触发怎么办？

检查 AppUtil.init() 是否已正确调用，以及回调引用是否正确。

Q2: 取消监听后仍然收到回调？

确保注册和取消使用的是同一个回调函数引用，建议使用类成员变量保存引用。

Q3: 可以注册多个回调吗？

可以注册多个不同的回调函数，每个回调都会在前后台切换时被调用。

Q4: 回调中可以执行异步操作吗？

回调在主线程执行，可以启动异步任务，但不建议在回调中直接执行耗时同步操作。

总结

AppUtil 的前后台监听方法简化了应用状态感知的实现，开发者可以轻松在前后台切换时执行相应逻辑。本文详细介绍了核心API、使用步骤、实际应用场景、进阶用法以及常见问题的解决方案。合理利用前后台回调，可以优化应用性能和用户体验。

本文基于 @pura/harmony-utils 工具库，更多功能请参考官方文档与后续系列文章。