WorkManager 允许您在将 WorkRequest 加入队列后对其进行更新。这在大型应用中通常是必要的,因为这些应用会频繁更改约束条件或需要实时更新其 worker。从 WorkManager 2.8.0 版开始,updateWork() API 是实现此目的的方法。
借助 updateWork() 方法,您可以动态更改 WorkRequest 的某些方面,而无需手动取消并使新作业入队。这大大简化了开发流程。
避免取消工作
通常,您应避免取消现有 WorkRequest 并将新 WorkRequest 加入队列。这样做可能会导致应用重复执行某些任务,并且可能需要您编写大量额外的代码。
请考虑以下示例,了解取消 WorkRequest 可能会导致哪些问题:
- 后端请求:如果您在
Worker计算要发送到服务器的载荷时取消该请求,则新的Worker需要重新开始并重新计算可能开销很大的载荷。 - 调度:如果您取消了
PeriodicWorkRequest,并且希望新的PeriodicWorkRequest按相同的时间表执行,则需要计算时间偏移值,以确保新的执行时间与之前的工作请求保持一致。
借助 updateWork() API,您可以更新工作请求的约束条件和其他参数,而无需取消和将新请求加入队列。
何时取消工作
在某些情况下,您应该直接取消 WorkRequest,而不是调用 updateWork()。如果您想更改已加入队列的工作的基本性质,则应执行此操作。
何时更新工作
假设有一款照片应用,每天都会备份用户的照片。它已将 PeriodicWorkRequest 加入队列来执行此操作。WorkRequest 具有一些限制,要求设备处于充电状态并连接到 Wi-Fi。
不过,该用户每天只使用快充为设备充电 20 分钟。在这种情况下,应用可能需要更新 WorkRequest 以放宽充电限制,以便即使设备未充满电,也能上传照片。
在这种情况下,您可以使用 updateWork() 方法更新工作请求的约束条件。
如何更新作业
updateWork() 方法提供了一种更新现有
WorkRequest 的简单方法,而无需取消现有 并将新 加入队列。
如需使用更新已加入队列的工作,请按以下步骤操作:
- 获取已加入队列的工作的现有 ID:获取您要更新的 WorkRequest 的 ID。您可以使用任何
getWorkInfoAPI 检索此 ID,也可以在将初始 WorkRequest 加入队列之前,通过手动保留该 ID 以便日后使用公共属性WorkRequest.id进行检索。 - 创建新的 WorkRequest:创建新的
WorkRequest,并使用WorkRequest.Builder.setID()将其 ID 设置为与现有WorkRequest的 ID 匹配。 - 设置约束条件:使用
WorkRequest.Builder.setConstraints()传递 WorkManager 新约束条件。 - 调用 updateWork:将新的 WorkRequest 传递给
updateWork()。
更新工作示例
以下是 Kotlin 中的示例代码段,演示了如何使用 updateWork() 方法更改用于上传照片的 WorkRequest 的电池约束条件:
suspend fun updatePhotoUploadWork() {
// Get instance of WorkManager.
val workManager = WorkManager.getInstance(context)
// Retrieve the work request ID. In this example, the work being updated is unique
// work so we can retrieve the ID using the unique work name.
val photoUploadWorkInfoList = workManager.getWorkInfosForUniqueWork(
PHOTO_UPLOAD_WORK_NAME
).await()
val existingWorkRequestId = photoUploadWorkInfoList.firstOrNull()?.id ?: return
// Update the constraints of the WorkRequest to not require a charging device.
val newConstraints = Constraints.Builder()
// Add other constraints as required here.
.setRequiresCharging(false)
.build()
// Create new WorkRequest from existing Worker, new constraints, and the id of the old WorkRequest.
val updatedWorkRequest: WorkRequest =
OneTimeWorkRequestBuilder<MyWorker>()
.setConstraints(newConstraints)
.setId(existingWorkRequestId)
.build()
// Pass the new WorkRequest to updateWork().
workManager.updateWork(updatedWorkRequest)
}
处理结果
updateWork() 会返回 ListenableFuture<UpdateResult>。给定的 UpdateResult 可以具有多个值中的一个,这些值概述了 WorkManager 是否能够应用您的更改。它还会指明何时能够应用更改。
如需了解详情,请参阅 updateWork()和 UpdateResult参考文档。
使用代次跟踪工作
每次更新 WorkRequest 时,其代都会递增 1。这样,您就可以准确跟踪当前已加入队列的 WorkRequest。
在观察、跟踪和测试工作请求时,代次可为您提供更多控制。
如需获取 WorkRequest 的世代,请按以下步骤操作:
- WorkInfo:调用
WorkManager.getWorkInfoById()以检索与您的WorkRequest对应的WorkInfo实例。- 您可以调用多个返回
WorkInfo的方法之一。如需了解详情,请参阅 WorkManager 参考文档。
- 您可以调用多个返回
- getGeneration:对
WorkInfo的实例调用getGeneration()。返回的Int对应于WorkRequest的代。- 请注意,没有代次字段或属性,只有
WorkInfo.getGeneration()方法。
- 请注意,没有代次字段或属性,只有
曲目生成示例
以下是上述工作流的示例实现,用于检索 WorkRequest 的生成。
// Get instance of WorkManager.
val workManager = WorkManager.getInstance(context)
// Retrieve WorkInfo instance.
val workInfo = workManager.getWorkInfoById(oldWorkRequestId)
// Call getGeneration to retrieve the generation.
val generation = workInfo.getGeneration()
更新作品的政策
以前,更新定期工作的推荐解决方案是使用政策 ExistingPeriodicWorkPolicy.REPLACE 将 PeriodicWorkRequest 加入队列。如果存在具有相同唯一 id 的待处理 PeriodicWorkRequest,新的工作请求会取消并删除该待处理工作。此政策现已弃用,取而代之的是使用 ExistingPeriodicWorkPolicy.UPDATE 的工作流。
例如,将 enqueueUniquePeriodicWork 与 PeriodicWorkRequest 搭配使用时,您可以使用 ExistingPeriodicWorkPolicy.UPDATE 政策初始化新的 PeriodicWorkRequest。如果存在具有相同唯一名称的待处理 PeriodicWorkRequest,WorkManager 会将其更新为新规范。按照此工作流,无需使用 updateWork()。