WorkManager 入门

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

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

Groovy

dependencies {
    def work_version = "2.9.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.9.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);

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

后续步骤

本入门指南仅触及表面。 WorkRequest 还可以包含其他信息，例如工作应运行的约束条件、工作输入、延迟以及重试工作的回退策略。在下一节“定义工作请求”中，您将更详细地了解这些选项，并了解如何计划唯一和重复的工作。

其他资源

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

示例

  • WorkManagerSample，一个简单的图像处理应用。
  • Sunflower，一个演示应用，展示了使用各种架构组件（包括 WorkManager）的最佳实践。

Codelab

博客