鸿蒙三方库 | harmony-utils之AppUtil前后台监听详解

2301_79533122

20人浏览 · 2026-07-12 23:23:19

2301_79533122 · 2026-07-12 23:23:19 发布

前言

应用前后台状态监听是移动开发中的常见需求，用于暂停/恢复动画、保存临时数据、控制网络请求等场景。@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 = [];
  }
}