WorkManager 入门

要开始使用 WorkManager，首先需要将库导入您的 Android 项目。

将以下依赖项添加到您应用的 build.gradle 文件中

Groovy

dependencies {
    def work_version = "2.10.1"

    // (Java only)
    implementation "androidx.work:work-runtime:$work_version"

    // Kotlin + coroutines
    implementation "androidx.work:work-runtime-ktx:$work_version"

    // optional - RxJava2 support
    implementation "androidx.work:work-rxjava2:$work_version"

    // optional - GCMNetworkManager support
    implementation "androidx.work:work-gcm:$work_version"

    // optional - Test helpers
    androidTestImplementation "androidx.work:work-testing:$work_version"

    // optional - Multiprocess support
    implementation "androidx.work:work-multiprocess:$work_version"
}

Kotlin

dependencies {
    val work_version = "2.10.1"

    // (Java only)
    implementation("androidx.work:work-runtime:$work_version")

    // Kotlin + coroutines
    implementation("androidx.work:work-runtime-ktx:$work_version")

    // optional - RxJava2 support
    implementation("androidx.work:work-rxjava2:$work_version")

    // optional - GCMNetworkManager support
    implementation("androidx.work:work-gcm:$work_version")

    // optional - Test helpers
    androidTestImplementation("androidx.work:work-testing:$work_version")

    // optional - Multiprocess support
    implementation("androidx.work:work-multiprocess:$work_version")
}

添加依赖项并同步您的 Gradle 项目后，下一步是定义要运行的工作。

定义工作

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

要为 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 work 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 work finished successfully with the Result
     return Result.success();
   }
}

从 doWork() 返回的 Result 会通知 WorkManager 服务工作是否成功，如果失败，是否应重试。

  • Result.success()：工作成功完成。
  • Result.failure()：工作失败。
  • Result.retry()：工作失败，应根据其重试策略在其他时间重试。

创建 WorkRequest

一旦您的工作定义完成，它必须通过 WorkManager 服务调度才能运行。WorkManager 在如何调度工作方面提供了很大的灵活性。您可以将其定期调度，也可以将其只运行一次。

无论您选择如何调度工作，您总是会使用 WorkRequest。虽然 Worker 定义了工作单元，但 WorkRequest（及其子类）定义了如何以及何时运行。在最简单的情况下，您可以使用 OneTimeWorkRequest，如以下示例所示。

Kotlin

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

Java

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

将 WorkRequest 提交到系统

最后，您需要使用 enqueue() 方法将您的 WorkRequest 提交到 WorkManager。

Kotlin

WorkManager
    .getInstance(myContext)
    .enqueue(uploadWorkRequest)

Java

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

Worker 的确切执行时间取决于您的 WorkRequest 中使用的限制以及系统优化。WorkManager 旨在在这些限制下提供最佳行为。

后续步骤

本入门指南只是触及皮毛。WorkRequest 还可以包含其他信息，例如工作应在什么限制下运行、工作的输入、延迟以及重试工作的退避策略。在下一节中，定义您的工作请求，您将更详细地了解这些选项，并了解如何调度唯一和重复的工作。

其他资源

除了指南文档，还有一些博客、Codelab 和代码示例可帮助您入门。

示例

  • Sunflower，一个演示各种架构组件（包括 WorkManager）最佳实践的演示应用。

Codelab

博客