HarmonyOS鸿蒙Next实战开发-长时任务开发方案

HarmonyOS鸿蒙Next实战开发-长时任务开发方案 在鸿蒙应用开发中，当应用退到后台时，系统会限制其运行以节省资源，导致以下业务场景无法正常运行：

• 音乐播放类应用：退到后台几分钟后播放中断
• 运动健康应用：GPS轨迹记录、心率监测等功能在后台被终止
• 文件传输应用：大文件上传/下载在后台无法持续进行
• 即时通讯应用：无法保持长连接实时接收消息
• 后台数据同步：定期从服务器同步数据失败

根本原因

鸿蒙系统基于资源调度机制，对后台应用进行严格管理：

1. 系统资源限制
   • 后台应用CPU配额有限
   • 网络访问频率受限
   • 内存占用超过阈值会被回收
2. 生命周期管理
   • 应用退到后台进入挂起状态
   • 长时间无操作会被标记为"空闲应用"
   • 系统根据优先级终止进程

解决方案

1 权限配置

{
  "module": {
    "requestPermissions": [
      {
        "name": "ohos.permission.KEEP_BACKGROUND_RUNNING",
        "reason": "$string:keep_background_reason",
        "usedScene": {
          "abilities": ["MusicPlayerAbility"],
          "when": "always"
        }
      },
      {
        "name": "ohos.permission.RUNNING_LOCK",
        "reason": "$string:running_lock_reason"
      },
      {
        "name": "ohos.permission.LOCATION",
        "reason": "$string:location_reason"
      }
    ]
  }
}

2 后台任务管理器

BackgroundTaskManager.ets

import backgroundTaskManager from '@ohos.backgroundTaskManager';
import common from '@ohos.app.ability.common';
import Want from '@ohos.app.ability.Want';

export class BackgroundTaskService {
  private delaySuspendTime: number = 0; // 延迟挂起时间（毫秒）
  private backgroundRunningRequest: backgroundTaskManager.BackgroundRunningRequest | null = null;
  private runningLock: backgroundTaskManager.RunningLock | null = null;
  
  /**
   * 请求持续后台运行
   * @param context UIAbility上下文
   * @param reason 后台运行原因描述
   */
  async requestBackgroundRunning(context: common.UIAbilityContext, 
                                 reason: string): Promise<boolean> {
    try {
      let want: Want = {
        bundleName: context.abilityInfo.bundleName,
        abilityName: context.abilityInfo.name
      };
      
      this.backgroundRunningRequest = {
        id: 1,
        abilityName: context.abilityInfo.name,
        wantAgent: want
      };
      
      await backgroundTaskManager.requestBackgroundRunningDelaySuspend(
        context, 
        reason, 
        this.backgroundRunningRequest
      );
      
      console.info('Background running request successful');
      return true;
    } catch (error) {
      console.error('Request background running failed: ' + JSON.stringify(error));
      return false;
    }
  }
  
  /**
   * 停止后台运行
   * @param context UIAbility上下文
   */
  async stopBackgroundRunning(context: common.UIAbilityContext): Promise<void> {
    if (!this.backgroundRunningRequest) {
      return;
    }
    
    try {
      await backgroundTaskManager.stopBackgroundRunning(
        context, 
        this.backgroundRunningRequest.id
      );
      this.backgroundRunningRequest = null;
      console.info('Stop background running successful');
    } catch (error) {
      console.error('Stop background running failed: ' + JSON.stringify(error));
    }
  }
  
  /**
   * 获取运行锁（防止CPU休眠）
   * @param lockType 锁类型
   */
  async acquireRunningLock(lockType: backgroundTaskManager.RunningLockType): Promise<void> {
    try {
      this.runningLock = await backgroundTaskManager.createRunningLock(
        "background_task_lock", 
        lockType
      );
      
      if (this.runningLock) {
        await this.runningLock.lock(this.delaySuspendTime);
        console.info('Running lock acquired');
      }
    } catch (error) {
      console.error('Acquire running lock failed: ' + JSON.stringify(error));
    }
  }
  
  /**
   * 释放运行锁
   */
  async releaseRunningLock(): Promise<void> {
    if (this.runningLock) {
      try {
        await this.runningLock.unlock();
        this.runningLock = null;
        console.info('Running lock released');
      } catch (error) {
        console.error('Release running lock failed: ' + JSON.stringify(error));
      }
    }
  }
  
  /**
   * 设置延迟挂起时间
   */
  setDelaySuspendTime(timeMs: number): void {
    this.delaySuspendTime = timeMs;
  }
}

3 工作调度器实现

WorkSchedulerService.ets

import workScheduler from '@ohos.workScheduler';
import { BusinessError } from '@ohos.base';

export enum TaskType {
  DATA_SYNC = 1,      // 数据同步
  NOTIFICATION = 2,  // 通知任务
  LOCATION_UPDATE = 3, // 位置更新
  MEDIA_PLAYBACK = 4  // 媒体播放
}

export class WorkSchedulerService {
  private workInfo: workScheduler.WorkInfo | null = null;
  
  /**
   * 创建周期性的后台任务
   */
  createPeriodicWork(taskId: number, taskType: TaskType, interval: number): workScheduler.WorkInfo {
    let workInfo: workScheduler.WorkInfo = {
      workId: taskId,
      bundleName: "com.example.yourapp",
      abilityName: "BackgroundTaskAbility",
      networkType: workScheduler.NetworkType.NETWORK_TYPE_ANY, // 网络要求
      isCharging: true,  // 充电时执行
      batteryLevel: 20,  // 电量高于20%
      batteryStatus: workScheduler.BatteryStatus.BATTERY_STATUS_LOW_OR_OKAY,
      storage: workScheduler.StorageLevel.STORAGE_LEVEL_LOW_OR_OKAY, // 存储空间
      repeatCycleTime: interval,  // 执行间隔（毫秒）
      isRepeat: true,  // 是否重复
      isPersisted: true  // 是否持久化（重启后继续）
    };
    
    // 根据任务类型设置不同参数
    switch(taskType) {
      case TaskType.DATA_SYNC:
        workInfo.networkType = workScheduler.NetworkType.NETWORK_TYPE_WIFI;
        workInfo.isCharging = true;
        break;
      case TaskType.LOCATION_UPDATE:
        workInfo.batteryLevel = 30;
        workInfo.repeatCycleTime = 5 * 60 * 1000; // 5分钟
        break;
    }
    
    this.workInfo = workInfo;
    return workInfo;
  }
  
  /**
   * 开始调度任务
   */
  async startAndScheduleWork(): Promise<void> {
    if (!this.workInfo) {
      console.error('WorkInfo is not created');
      return;
    }
    
    try {
      await workScheduler.startAndScheduleWork(this.workInfo);
      console.info('Work scheduled successfully');
    } catch (error) {
      const err: BusinessError = error as BusinessError;
      console.error('Schedule work failed, code: ' + err.code + ', message: ' + err.message);
    }
  }
  
  /**
   * 停止任务
   */
  async stopWork(workId: number): Promise<void> {
    try {
      await workScheduler.stopWork(workId, true);
      console.info('Work stopped successfully');
    } catch (error) {
      const err: BusinessError = error as BusinessError;
      console.error('Stop work failed, code: ' + err.code + ', message: ' + err.message);
    }
  }
  
  /**
   * 获取所有任务
   */
  async getWorkStatus(workId: number): Promise<void> {
    try {
      const status = await workScheduler.getWorkStatus(workId);
      console.info('Work status: ' + JSON.stringify(status));
    } catch (error) {
      const err: BusinessError = error as BusinessError;
      console.error('Get work status failed: ' + err.code);
    }
  }
}

4 具体场景实现示例

1.音乐播放后台任务

// MusicBackgroundService.ets
import { BackgroundTaskService } from './BackgroundTaskManager';
import audio from '@ohos.multimedia.audio';

export class MusicBackgroundService {
  private backgroundTask: BackgroundTaskService = new BackgroundTaskService();
  private audioPlayer: audio.AudioPlayer | null = null;
  private isPlaying: boolean = false;
  
  // 初始化音乐播放后台任务
  async initMusicBackground(context: any): Promise<void> {
    // 请求后台运行权限
    const success = await this.backgroundTask.requestBackgroundRunning(
      context,
      "音乐播放需要后台持续运行"
    );
    
    if (success) {
      // 获取运行锁（防止CPU休眠影响播放）
      await this.backgroundTask.acquireRunningLock(
        backgroundTaskManager.RunningLockType.BACKGROUND
      );
      
      // 设置音频会话
      await this.setupAudioSession();
      
      // 注册前后台监听
      this.registerAppStateListener();
    }
  }
  
  private async setupAudioSession(): Promise<void> {
    try {
      // 创建音频播放器
      const audioManager = audio.getAudioManager();
      this.audioPlayer = await audioManager.createAudioPlayer();
      
      // 配置音频参数
      const audioParams: audio.AudioPlayerOptions = {
        source: {
          dataSource: audio.AudioDataSourceType.AUDIO_SOURCE_TYPE_URI,
          uri: 'your_music_uri'
        }
      };
      
      await this.audioPlayer.init(audioParams);
      
      // 设置音频焦点
      await audioManager.setAudioInterruptMode({
        focusType: audio.AudioFocusType.FOCUS_TYPE_GAIN,
        focusMode: audio.AudioFocusMode.FOCUS_MODE_DUCK
      });
      
    } catch (error) {
      console.error('Setup audio session failed: ' + JSON.stringify(error));
    }
  }
  
  private registerAppStateListener(): void {
    // 监听应用状态变化
    app.on('applicationStateChange', (state) => {
      if (state === app.ApplicationState.STATE_BACKGROUND) {
        this.onAppBackground();
      } else if (state === app.ApplicationState.STATE_FOREGROUND) {
        this.onAppForeground();
      }
    });
  }
  
  private onAppBackground(): void {
    console.info('App entered background, maintaining music playback');
    // 后台时降低音量或保持静音播放
    if (this.audioPlayer && this.isPlaying) {
      this.audioPlayer.setVolume(0.3); // 降低音量
    }
  }
  
  private onAppForeground(): void {
    console.info('App entered foreground');
    if (this.audioPlayer && this.isPlaying) {
      this.audioPlayer.setVolume(1.0); // 恢复音量
    }
  }
  
  // 清理资源
  async cleanup(): Promise<void> {
    if (this.audioPlayer) {
      await this.audioPlayer.release();
      this.audioPlayer = null;
    }
    
    await this.backgroundTask.releaseRunningLock();
  }
}

2. 位置更新后台任务

// LocationBackgroundService.ets
import geoLocationManager from '@ohos.geoLocationManager';
import { WorkSchedulerService, TaskType } from './WorkSchedulerService';

export class LocationBackgroundService {
  private workScheduler: WorkSchedulerService = new WorkSchedulerService();
  private locationRequest: geoLocationManager.LocationRequest | null = null;
  private locationCallback: geoLocationManager.LocationCallback | null = null;
  
  // 开始后台位置更新
  async startBackgroundLocationUpdate(): Promise<void> {
    // 创建周期性位置更新任务
    const workInfo = this.workScheduler.createPeriodicWork(
      1001,
      TaskType.LOCATION_UPDATE,
      5 * 60 * 1000 // 5分钟间隔
    );
    
    // 设置位置更新条件
    workInfo.isCharging = false;
    workInfo.batteryLevel = 15; // 电量高于15%
    
    await this.workScheduler.startAndScheduleWork();
    
    // 初始化位置服务
    await this.initLocationService();
  }
  
  private async initLocationService(): Promise<void> {
    try {
      // 请求位置权限
      await this.requestLocationPermission();
      
      // 配置位置请求参数
      this.locationRequest = {
        priority: geoLocationManager.LocationRequestPriority.FIRST_FIX,  // 快速获取位置
        scenario: geoLocationManager.LocationRequestScenario.UNSET,  // 通用场景
        timeInterval: 300,  // 上报间隔（秒）
        distanceInterval: 50,  // 上报距离（米）
        maxAccuracy: 10  // 精度（米）
      };
      
      // 注册位置变化回调
      this.locationCallback = {
        onLocationReport: (location: geoLocationManager.Location) => {
          this.handleLocationUpdate(location);
        },
        onErrorReport: (error: BusinessError) => {
          console.error('Location error: ' + JSON.stringify(error));
        }
      };
      
      // 开始监听位置
      await geoLocationManager.on('locationChange', 
        this.locationRequest, 
        this.locationCallback
      );
      
    } catch (error) {
      console.error('Init location service failed: ' + JSON.stringify(error));
    }
  }
  
  private async requestLocationPermission(): Promise<void> {
    // 实际项目中应使用权限请求API
    console.info('Requesting location permission...');
  }
  
  private handleLocationUpdate(location: geoLocationManager.Location): void {
    // 处理位置更新
    const locationData = {
      latitude: location.latitude,
      longitude: location.longitude,
      accuracy: location.accuracy,
      timestamp: location.timeStamp,
      altitude: location.altitude
    };
    
    console.info('Location updated: ' + JSON.stringify(locationData));
    
    // 保存到本地或上传到服务器
    this.saveLocationData(locationData);
  }
  
  private saveLocationData(location: any): void {
    // 实现数据保存逻辑
    // 1. 保存到本地数据库
    // 2. 批量上传到服务器
    // 3. 触发相关业务逻辑
  }
  
  // 停止位置更新
  async stopLocationUpdate(): Promise<void> {
    if (this.locationCallback) {
      await geoLocationManager.off('locationChange', this.locationCallback);
      this.locationCallback = null;
    }
    
    await this.workScheduler.stopWork(1001);
  }
}

可复用组件

1. BackgroundTaskManager​ - 通用后台任务管理器
2. WorkSchedulerService​ - 工作调度服务
3. 场景化任务模板​ - 音乐、定位、传输等

注意事项

1. 严格遵守用户隐私政策，透明告知后台行为
2. 提供用户可控选项，允许关闭后台任务
3. 定期评估任务必要性，及时清理无效任务
4. 遵守各应用商店后台任务政策要求
5. 在应用描述中清晰说明后台功能