WorkManager 使用入门

如需开始使用 WorkManager，请先将库导入您的 Android 项目中。

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

Groovy

dependencies {
    def work_version = "2.10.3"

    // (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.3"

    // (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 和代码示例可帮助您入门。

示例

  • Sunflower，一款演示版应用，演示包括 WorkManager 在内的各种架构组件的最佳做法。

Codelab

博客