WorkManager 入门指南

通过 WorkManager,您可以轻松设置任务并提交给系统,以在您指定的条件下运行。如需进一步了解 WorkManager 是不是适合您任务的解决方案,请参阅后台处理指南

在本指南中,您将了解到如何执行以下操作:

  • 将 WorkManager 添加到您的 Android 项目中
  • 创建后台任务
  • 配置运行任务的方式和时间
  • 将任务提交给系统

要了解 WorkManager 功能(例如处理周期性工作、创建工作链以及取消工作),请参阅方法指南

将 WorkManager 添加到您的 Android 项目中

按照 WorkManager 版本说明中的说明,使用 Java 或 Kotlin 语言将 WorkManager 依赖项添加到您的 Android 项目中。

创建后台任务

任务是使用 Worker 类定义的。doWork() 方法在 WorkManager 提供的后台线程上同步运行。

要创建后台任务,请扩展 Worker 类并替换 doWork() 方法。例如,要创建上传图像的 Worker,您可以执行以下操作:

Kotlin

    class UploadWorker(appContext: Context, workerParams: WorkerParameters)
        : Worker(appContext, workerParams) {

        override fun doWork(): Result {
            // Do the work here--in this case, upload the images.

            uploadImages()

            // Indicate whether the task finished successfully with the Result
            return Result.success()
        }
    }
    

Java

    public class UploadWorker extends Worker {

        public UploadWorker(
            @NonNull Context context,
            @NonNull WorkerParameters params) {
            super(context, params);
        }

        @Override
        public Result doWork() {
          // Do the work here--in this case, upload the images.

          uploadImages()

          // Indicate whether the task finished successfully with the Result
          return Result.success()
        }
    }
    

doWork() 返回的 Result 会通知 WorkManager 任务是否:

  • 已成功完成:Result.success()
  • 已失败:Result.failure()
  • 需要稍后重试:Result.retry()

配置运行任务的方式和时间

Worker 定义工作单元,WorkRequest 则定义工作的运行方式和时间。任务可以是一次性的,也可以是周期性的。对于一次性 WorkRequest,请使用 OneTimeWorkRequest,对于周期性工作,请使用 PeriodicWorkRequest。要详细了解如何调度周期性工作,请参阅周期性工作文档

在本例中,为 UploadWorker 构建 WorkRequest 最简单的示例为:

Kotlin

    val uploadWorkRequest = OneTimeWorkRequestBuilder<UploadWorker>()
            .build()
    

Java

    OneTimeWorkRequest uploadWorkRequest = new OneTimeWorkRequest.Builder(UploadWorker.class)
            .build()
    

WorkRequest 中还可以包含其他信息,例如任务在运行时应遵循的约束、工作输入、延迟,以及重试工作的退避时间政策。关于这些选项,在定义工作指南中有更详细的说明。

将您的任务提交给系统

定义 WorkRequest 之后,您现在可以通过 WorkManager 使用 enqueue() 方法来调度它。

Kotlin

    WorkManager.getInstance(myContext).enqueue(uploadWorkRequest)
    

Java

    WorkManager.getInstance(myContext).enqueue(uploadWorkRequest);
    

执行 Worker 的确切时间取决于 WorkRequest 中使用的约束以及系统优化。WorkManager 的设计目的就是要在这些限制下提供尽可能好的表现。

后续步骤