# task_manage_project

**Repository Path**: Fie_Ryan/task_manage_project

## Basic Information

- **Project Name**: task_manage_project
- **Description**: 后台任务管理工具 (长时任务和短时任务可用)：
后台任务管理工具是一个用于管理 HarmonyOS 应用后台长时任务或者短时任务的工具类，支持任务的启动、停止、更新以及通知栏交互功能。该工具确保应用在后台能够持续执行关键任务，并通过通知栏提供用户交互能力。
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 1
- **Created**: 2025-09-08
- **Last Updated**: 2025-09-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: 后台服务, 长时任务, 鸿蒙, 短时任务

## README

# 后台任务管理工具 (长时任务和短时任务可用)
后台任务管理工具是一个用于管理 HarmonyOS 应用后台长时任务或者短时任务的工具类，支持任务的启动、停止、更新以及通知栏交互功能。该工具确保应用在后台能够持续执行关键任务，并通过通知栏提供用户交互能力。

## 使用 ohpm 下载安装使用
```typescript
 ohpm install @ryan/task_manage
```
## 下面仅显示主要代码, 更多使用示例demo可以前往 [后台任务管理工具](https://gitee.com/Fie_Ryan/task_manage_project) 查看

## 后台任务管理工具 (BackgroundTaskManager)
用于在应用中进行后台服务的注册和销毁
### 使用过程必须初始化和销毁
#### 在 Ability 的 onWindowStageCreate 方法中进行后台服务初始化
```extendtypescript
onWindowStageCreate(windowStage: window.WindowStage): void {
  // 开启后台服务监听
  BackgroundTaskManage.init(this.context, windowStage)
}
```

#### 在 Ability 的 onDestroy 方法中进行后台服务销毁
```extendtypescript
onDestroy(): void {
  // 销毁后台服务监听
  BackgroundTaskManage.destroy()
}
```
### 主要方法
```extendtypescript
/**
 * 后台任务管理类，采用单例模式确保全局唯一实例
 * 负责初始化和销毁后台任务相关资源
 */
class BackgroundTaskManager {
  /**
   * 初始化后台任务管理器
   * @param context 应用上下文
   * @param windowStage 窗口实例
   * @throws {Error} 当上下文或窗口舞台为空时抛出错误
   */
  init(context: Context, windowStage: window.WindowStage): void ;

  /**
   * 销毁后台任务管理器，释放相关资源
   */
  public destroy(): void;
}
```



## 长时任务工具 (LongTimeTaskManage)
长时任务管理工具是一个用于管理 HarmonyOS 应用后台长时任务的单例类，支持任务的启动、停止、更新以及通知栏交互功能。该工具确保应用在后台能够持续执行关键任务，并通过通知栏提供用户交互能力。
### 功能特点
- 单例模式设计，确保任务管理的一致性
- 支持启动、停止和更新后台长时任务
- 提供通知栏交互能力，点击通知可拉起应用
- 支持异步启动任务，适应应用前后台状态变化
- 完整的事件监听机制，便于处理任务生命周期事件
- 支持自定义任务类型、通知交互行为等参数

### 主要使用方法
```extendtypescript
/**
 * 长时任务管理类
 * 负责后台长时任务的启动、停止和更新，支持通知栏交互
 * 采用单例模式确保任务管理的一致性
 */
export class LongTimeTaskManage {
  // ***************************** 长时任务操作方法 *****************************
  /**
   * 立即启动长时任务
   * @param wants 任务相关的Want数组（包含bundleName和abilityName）
   * @param reason 任务描述（用于通知展示）
   * @param listener 事件监听
   * @param callback 任务启动成功后的回调
   * @returns 任务结果（包含任务ID或错误信息）
   */
  public async startContinuousTask(wants: Array<Want>, reason?: string, listener?: TaskListener, callback?: (result: BackgroundTaskSuccessResult) => void): Promise<BackgroundTaskSuccessResult>;
  /**
   * 停止长时任务
   * @param callback 任务停止后的回调
   * @returns 停止结果
   */
  public async stopContinuousTask(callback?: (id: number) => void): Promise<void>;

  /**
   * 更新长时任务类型
   * @param bgModes 新的任务模式列表
   * @param reason 任务描述更新
   * @param callback 更新成功后的回调
   * @returns 更新结果
   */
  public async updateContinuousTask(bgModes: Array<string>, reason?: string, callback?: (result: BackgroundTaskSuccessResult) => void): Promise<BackgroundTaskSuccessResult>;

  /**
   * 异步启动长时任务，当应用处于后台时触发，前台时自动停止
   * @param wants 任务相关的Want数组
   * @param reason 任务描述
   * @param listener 事件监听
   * @param callback 任务启动成功后的回调
   */
  public async startAsyncContinuousTask(wants: Array<Want>, reason?: string, listener?: TaskListener, callback?: (result: BackgroundTaskSuccessResult) => void): Promise<boolean>;

  /**
   * 根据指定taskId取消异步任务
   * @param taskId 任务ID
   */
  public async stopAsyncContinuousTask(taskId: number): Promise<void>;

  /**
   * 停止所有异步任务
   */
  public async stopAllAsyncContinuousTask(): Promise<void>;

  // ***************************** 属性 配置方法 *****************************
  /**
   * 获取当前运行的任务ID
   * @returns 当前任务ID，未运行时返回-1
   */
  public getCurrentTaskId(): number;

  /**
   * 检查是否有正在运行的任务
   * @returns 有运行中的任务返回true，否则返回false
   */
  public isTaskRunning(): boolean;

  /**
   * 支持的任务类型(默认是监听 BackgroundMode 全部类型), 可链式调用
   * @param taskTypes 任务类型数组 使用 BackgroundMode 类型
   * @returns 当前实例
   */
  public setTaskTypes(taskTypes: Array<string>);

  /**
   * 返回支持的任务类型
   * @returns 任务类型列表
   */
  public getTaskTypes(): Array<string>;

  /**
   * 设置动作执行属性,默认: wantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG , 可链式调用
   * @param actionFlags
   * @returns 当前实例
   */
  public setActionFlags(actionFlags: Array<wantAgent.WantAgentFlags>);

  /**
   * 动作执行属性
   * @returns 动作执行属性列表
   */
  public getActionFlags(): Array<wantAgent.WantAgentFlags>;

  /**
   * 点击通知后的动作类型,(默认: wantAgent.OperationType.START_ABILITY), 可链式调用
   * @param actionType 动作类型列表
   * @returns 当前实例
   */
  public setActionType(actionType: wantAgent.OperationType);

  /**
   * 点击通知后的动作类型
   * @returns 点击通知后的动作类型
   */
  public getActionType(): wantAgent.OperationType;

  /**
   * 自定义请求码, 默认为0, 可链式调用
   * @param requestCode 请求码
   * @returns 当前实例
   */
  public setRequestCode(requestCode: number);

  /**
   * 返回自定义请求码
   * @returns 请求码
   */
  public getRequestCode(): number;

  /**
   * 设置事件监听对象
   * @param listener 事件监听对象
   * @returns 当前示例
   */
  public setListener(listener: TaskListener);

  /**
   * 获取事件监听对象
   * @returns 事件监听对象
   */
  public getListener(): TaskListener;
}
```
### 使用示例
```extendtypescript
wants: Array<Want> = [
  {
    bundleName: "com.ryan.task",
    abilityName: "EntryAbility"
  }
]
Column({ space: 25 }) {
  Button("开启同步长时任务")
    .width("100%")
    .onClick(async () => {
      const result: BackgroundTaskSuccessResult =
        await LongTimeTaskManage.startContinuousTask(this.wants, "申请的同步长时任务", this.listener)
      this.taskInfo = result
      this.longTermTaskModel.getLocation()
    })
  Button("是否有正在运行的任务")
    .width("100%")
    .onClick(async () => {
      const isBool = LongTimeTaskManage.isTaskRunning()
      AlertDialog.show({
        message: isBool ? "有" : "没有"
      })
    })
  Button("取消同步长时任务")
    .width("100%")
    .onClick(() => {
      if (this.taskInfo.taskId != -1) {
        LongTimeTaskManage.stopContinuousTask((id: number) => {
          this.longTermTaskModel
          AlertDialog.show({
            message: `取消的任务ID: ${id}`
          })
        })
      }
    })
  Button("开启异步长时任务")
    .width("100%")
    .onClick(() => {
      LongTimeTaskManage.startAsyncContinuousTask(this.wants)
      this.longTermTaskModel.getLocation()
    })
  Button("清除异步长时任务")
    .width("100%")
    .onClick(() => {
      LongTimeTaskManage.stopAllAsyncContinuousTask()
    })
}
```

## 短时任务工具 (ShortTimeTaskManage)
短时任务管理器(ShortTimeTaskManage)是一个用于管理 HarmonyOS 应用短时后台任务的单例工具类，负责短时任务的创建、跟踪、查询剩余时间和销毁等操作，确保应用在后台能够执行短期关键任务。

### 功能特点
- 单例模式设计，确保任务管理的一致性
- 支持创建、取消单个或所有短时任务
- 提供任务剩余时间查询功能
- 支持全局和任务级别的事件监听
- 任务数量限制机制（默认最大 3 个）
- 任务状态持久化管理（基于 TaskSubscribeModel）
### 主要使用方法
```extendtypescript
/**
 * 短时任务管理器 - 负责管理短时后台任务的创建、跟踪和销毁
 * 采用单例模式确保任务管理的一致性
 */
class ShortTimeTaskManage {
   /**
   * 设置全局任务监听器
   * @param listener 全局监听器对象
   */
  public setGlobalListener(listener: TaskListener): void;

  /**
   * 申请开启短时任务
   * @param reason 申请原因
   * @param listener 每个任务独立事件监听函数, 优先级比公共监听函数高
   * @param callback 申请成功的回调函数
   */
  public requestSuspendDelay(reason: string, taskListener?: TaskListener,
    callback?: (result: BackgroundTaskSuccessResult) => void): void;

  /**
   * 获取短时任务剩余时间
   * @param id 任务ID，不指定则使用最后一个任务ID
   * @returns 剩余时间，失败返回-1
   */
  public async getRemainingDelayTime(id?: number): Promise<number>;

  /**
   * 取消短时任务
   * @param id 任务id
   * @param callback 取消后的回调
   */
  public cancelSuspendDelay(id?: number): boolean ;

  /**
   * 取消所有活跃的短时任务
   */
  public cancelAllTasks(callback?: () => void): void;

  /**
   * 获取当前任务列表信息
   * @returns 任务列表数组
   */
  public getTaskListInfos();

  /**
   * 检查任务是否存在
   * @param id 任务ID
   * @returns 存在返回true，否则返回false
   */
  public hasTask(id: number): boolean;
}
```
### 使用示例
```extendtypescript
Column({ space: 20 }) {
  Button("开启短时任务(最多注册三个短时任务)")
    .width("100%")
    .onClick(() => {
      ShortTimeTaskManage.requestSuspendDelay("短时任务")
    })
  Button("获取应用程序进入挂起状态前的剩余时间")
    .width("100%")
    .onClick(async () => {
      if (this.taskId != -1) {
        AlertDialog.show({
          message: JSON.stringify(await ShortTimeTaskManage.getRemainingDelayTime(this.taskId))
        })
      }
    })

  Button("根据任务ID清除指定任务详情")
    .width("100%")
    .onClick(async () => {
      if (this.taskId != -1) {
        const isBool = ShortTimeTaskManage.cancelSuspendDelay(this.taskId)
        promptAction.showToast({
          message: `清除${isBool ? "成功" : "失败"}`
        })
        this.reflash()
      }
    })
  Button("清除所有短时任务")
    .width("100%")
    .onClick(() => {
      ShortTimeTaskManage.cancelAllTasks()
    })
}
```

## [鸿蒙相关工具仓库首页](https://gitee.com/Fie_Ryan)
```typescript
https://gitee.com/Fie_Ryan
```