管理工作

定义了您的 Worker 和 您的 WorkRequest 后，最后一步就是将您的工作加入队列。最简单的方法是调用 WorkManager 的 enqueue() 方法，并传入您要运行的 WorkRequest。

Kotlin

val myWork: WorkRequest = // ... OneTime or PeriodicWork
WorkManager.getInstance(requireContext()).enqueue(myWork)

Java

WorkRequest myWork = // ... OneTime or PeriodicWork
WorkManager.getInstance(requireContext()).enqueue(myWork);

在将工作加入队列时请谨慎，以避免重复。例如，某个应用可能每 24 小时尝试将其日志上传到后端服务。如果您不小心，最终可能会多次将相同的任务加入队列，即使该作业只需要运行一次。为了实现此目标，您可以将工作安排为唯一工作。

唯一工作

唯一工作是一个强大的概念，它保证您在任何给定时间只有一个特定名称的工作实例。与 ID 不同，唯一名称是人类可读的，由开发者指定，而不是由 WorkManager 自动生成。与标签不同，唯一名称仅与单个工作实例关联。

唯一工作可以应用于一次性工作和周期性工作。您可以调用以下方法之一来创建唯一工作序列，具体取决于您是调度重复工作还是一次性工作。

这两种方法都接受 3 个参数

  • uniqueWorkName - 用于唯一标识工作请求的 String。
  • existingWorkPolicy - 一个 enum，它告诉 WorkManager 如果已存在具有该唯一名称的未完成工作链时该怎么做。有关更多信息，请参阅冲突解决策略。
  • work - 要调度的 WorkRequest。

使用唯一工作，我们可以解决前面提到的重复调度问题。

Kotlin

val sendLogsWorkRequest =
       PeriodicWorkRequestBuilder<SendLogsWorker>(24, TimeUnit.HOURS)
           .setConstraints(Constraints.Builder()
               .setRequiresCharging(true)
               .build()
            )
           .build()
WorkManager.getInstance(this).enqueueUniquePeriodicWork(
           "sendLogs",
           ExistingPeriodicWorkPolicy.KEEP,
           sendLogsWorkRequest
)

Java

PeriodicWorkRequest sendLogsWorkRequest = new
      PeriodicWorkRequest.Builder(SendLogsWorker.class, 24, TimeUnit.HOURS)
              .setConstraints(new Constraints.Builder()
              .setRequiresCharging(true)
          .build()
      )
     .build();
WorkManager.getInstance(this).enqueueUniquePeriodicWork(
     "sendLogs",
     ExistingPeriodicWorkPolicy.KEEP,
     sendLogsWorkRequest);

现在，如果代码在 sendLogs 作业已在队列中时运行，则会保留现有作业，并且不会添加新作业。

如果您需要逐步构建一个长任务链，唯一工作序列也可能很有用。例如，照片编辑应用可能允许用户撤消一长串操作。每个撤消操作可能需要一段时间，但它们必须按正确的顺序执行。在这种情况下，应用可以创建一个“撤消”链，并根据需要将每个撤消操作追加到该链中。有关更多详细信息，请参阅链式工作。

冲突解决策略

调度唯一工作时，您必须告诉 WorkManager 在发生冲突时要采取什么操作。您可以通过在将工作加入队列时传入一个枚举来实现此目的。

对于一次性工作，您提供一个 ExistingWorkPolicy，它支持 4 种处理冲突的选项。

  • 使用新工作替换现有工作。此选项会取消现有工作。
  • 保留现有工作并忽略新工作。
  • 将新工作追加到现有工作的末尾。此策略将使您的新工作链接到现有工作，并在现有工作完成后运行。

现有工作成为新工作的先决条件。如果现有工作变为 CANCELLED 或 FAILED，则新工作也会变为 CANCELLED 或 FAILED。如果您希望新工作无论现有工作状态如何都运行，请改用 APPEND_OR_REPLACE。

  • APPEND_OR_REPLACE 的功能类似于 APPEND，不同之处在于它不依赖于先决条件工作状态。如果现有工作是 CANCELLED 或 FAILED，新工作仍然会运行。

对于周期性工作，您提供一个 ExistingPeriodicWorkPolicy，它支持 REPLACE 和 KEEP 两种选项。这些选项的功能与其 ExistingWorkPolicy 对应项相同。

观察您的工作

在将工作加入队列后的任何时间点，您都可以通过查询 WorkManager 的 name、id 或与其关联的 tag 来检查其状态。

Kotlin

// by id
workManager.getWorkInfoById(syncWorker.id) // ListenableFuture<WorkInfo>

// by name
workManager.getWorkInfosForUniqueWork("sync") // ListenableFuture<List<WorkInfo>>

// by tag
workManager.getWorkInfosByTag("syncTag") // ListenableFuture<List<WorkInfo>>

Java

// by id
workManager.getWorkInfoById(syncWorker.id); // ListenableFuture<WorkInfo>

// by name
workManager.getWorkInfosForUniqueWork("sync"); // ListenableFuture<List<WorkInfo>>

// by tag
workManager.getWorkInfosByTag("syncTag"); // ListenableFuture<List<WorkInfo>>

查询会返回一个 ListenableFuture 的 WorkInfo 对象，其中包含工作的 id、其标签、其当前状态以及通过 Result.success(outputData) 设置的任何输出数据。

每种方法的 LiveData 变体允许您通过注册监听器来观察 WorkInfo 的变化。例如，如果您想在某些工作成功完成后向用户显示一条消息，您可以按如下方式设置：

Kotlin

workManager.getWorkInfoByIdLiveData(syncWorker.id)
               .observe(viewLifecycleOwner) { workInfo ->
   if(workInfo?.state == WorkInfo.State.SUCCEEDED) {
       Snackbar.make(requireView(), 
      R.string.work_completed, Snackbar.LENGTH_SHORT)
           .show()
   }
}

Java

workManager.getWorkInfoByIdLiveData(syncWorker.id)
        .observe(getViewLifecycleOwner(), workInfo -> {
    if (workInfo.getState() != null &&
            workInfo.getState() == WorkInfo.State.SUCCEEDED) {
        Snackbar.make(requireView(),
                    R.string.work_completed, Snackbar.LENGTH_SHORT)
                .show();
   }
});

复杂的工作查询

WorkManager 2.4.0 及更高版本支持使用 WorkQuery 对象进行复杂的排队作业查询。WorkQuery 支持通过其标签、状态和唯一工作名称的组合来查询工作。

以下示例展示了如何查找所有带有标签 “syncTag”、处于 FAILED 或 CANCELLED 状态且唯一工作名称为 “preProcess” 或 “sync” 的工作。

Kotlin

val workQuery = WorkQuery.Builder
       .fromTags(listOf("syncTag"))
       .addStates(listOf(WorkInfo.State.FAILED, WorkInfo.State.CANCELLED))
       .addUniqueWorkNames(listOf("preProcess", "sync")
    )
   .build()

val workInfos: ListenableFuture<List<WorkInfo>> = workManager.getWorkInfos(workQuery)

Java

WorkQuery workQuery = WorkQuery.Builder
       .fromTags(Arrays.asList("syncTag"))
       .addStates(Arrays.asList(WorkInfo.State.FAILED, WorkInfo.State.CANCELLED))
       .addUniqueWorkNames(Arrays.asList("preProcess", "sync")
     )
    .build();

ListenableFuture<List<WorkInfo>> workInfos = workManager.getWorkInfos(workQuery);

WorkQuery 中的每个组件（标签、状态或名称）都与其他组件进行 AND 运算。组件中的每个值都进行 OR 运算。例如：(name1 OR name2 OR ...) AND (tag1 OR tag2 OR ...) AND (state1 OR state2 OR ...)。

WorkQuery 也适用于 LiveData 等效项 getWorkInfosLiveData()。

取消和停止工作

如果您不再需要运行先前已加入队列的工作，您可以请求取消它。可以通过工作的 name、id 或与其关联的 tag 来取消工作。

Kotlin

// by id
workManager.cancelWorkById(syncWorker.id)

// by name
workManager.cancelUniqueWork("sync")

// by tag
workManager.cancelAllWorkByTag("syncTag")

Java

// by id
workManager.cancelWorkById(syncWorker.id);

// by name
workManager.cancelUniqueWork("sync");

// by tag
workManager.cancelAllWorkByTag("syncTag");

在内部，WorkManager 会检查工作的状态。如果工作已完成，则不执行任何操作。否则，工作的状态将更改为CANCELLED，并且该工作将来不会运行。任何WorkRequest 作业（依赖于此工作）也将被 CANCELLED。

当前正在运行的工作会收到对 ListenableWorker.onStopped() 的调用。重写此方法以处理任何可能的清理。有关更多信息，请参阅停止正在运行的 Worker。

停止正在运行的 Worker

WorkManager 停止正在运行的 Worker 的原因有以下几种：

  • 您明确请求取消它（例如，通过调用 WorkManager.cancelWorkById(UUID)）。
  • 在唯一工作的情况下，您明确地将一个新的 WorkRequest 加入队列，并将其 ExistingWorkPolicy 设置为 REPLACE。旧的 WorkRequest 会立即被视为已取消。
  • 您的工作约束不再满足。
  • 系统因某种原因指示您的应用停止您的工作。如果您超过 10 分钟的执行期限，可能会发生这种情况。该工作会安排在稍后重试。

在这些条件下，您的 Worker 将被停止。

您应该主动中止任何正在进行的工作，并释放您的 Worker 占用的任何资源。例如，此时您应该关闭对数据库和文件的打开句柄。您可以使用两种机制来了解 Worker 何时停止。

onStopped() 回调

一旦您的 Worker 被停止，WorkManager 就会调用 ListenableWorker.onStopped()。重写此方法以关闭您可能持有的任何资源。

isStopped() 属性

您可以调用 ListenableWorker.isStopped() 方法来检查您的 Worker 是否已停止。如果您在 Worker 中执行长时间运行或重复的操作，您应该经常检查此属性，并将其作为尽快停止工作的信号。

注意： WorkManager 会忽略已收到 onStop 信号的 Worker 设置的 Result，因为该 Worker 已被视为已停止。