入门指南介绍了如何创建简单的 WorkRequest
并将其加入队列。
在本指南中,您将了解如何定义和自定义 WorkRequest
对象来处理常见用例,例如:
- 调度一次性工作和重复性工作
- 设置工作约束条件,例如要求连接到 Wi-Fi 网络或正在充电
- 确保至少延迟一定时间再执行工作
- 设置重试和退避策略
- 将输入数据传递给工作
- 使用标记将相关工作分组在一起
概览
工作通过 WorkRequest
在 WorkManager 中进行定义。为了使用 WorkManager 调度任何工作,您必须先创建一个 WorkRequest
对象,然后将其加入队列。
Kotlin
val myWorkRequest = ... WorkManager.getInstance(myContext).enqueue(myWorkRequest)
Java
WorkRequest myWorkRequest = ... WorkManager.getInstance(myContext).enqueue(myWorkRequest);
WorkRequest 对象包含 WorkManager 调度和运行工作所需的所有信息。其中包括运行工作必须满足的约束、调度信息(例如延迟或重复间隔)、重试配置,并且可能包含输入数据(如果工作需要)。
WorkRequest
本身是抽象基类。该类有两个派生实现,可用于创建 OneTimeWorkRequest
和 PeriodicWorkRequest
请求。顾名思义,OneTimeWorkRequest
适用于调度非重复性工作,而 PeriodicWorkRequest
则更适合调度以一定间隔重复执行的工作。
调度一次性工作
对于无需额外配置的简单工作,请使用静态方法 from
:
Kotlin
val myWorkRequest = OneTimeWorkRequest.from(MyWork::class.java)
Java
WorkRequest myWorkRequest = OneTimeWorkRequest.from(MyWork.class);
对于更复杂的工作,可以使用构建器:
Kotlin
val uploadWorkRequest: WorkRequest = OneTimeWorkRequestBuilder<MyWork>() // Additional configuration .build()
Java
WorkRequest uploadWorkRequest = new OneTimeWorkRequest.Builder(MyWork.class) // Additional configuration .build();
调度加急工作
WorkManager 2.7.0 引入了加急工作的概念。这使 WorkManager 能够执行重要工作,同时使系统能够更好地控制对资源的访问权限。
加急工作具有以下特征:
- 重要性:加急工作适用于对用户很重要或由用户启动的任务。
- 速度:加急工作最适合那些立即启动并在几分钟内完成的简短任务。
- 配额:限制前台执行时间的系统级配额决定了加急作业是否可以启动。
- 电源管理:电源管理限制(如省电模式和低电耗模式)不太可能影响加急工作。
- 延迟时间:系统立即执行加急工作,前提是系统的当前工作负载允许执行此操作。这意味着这些工作对延迟时间较为敏感,不能安排到以后执行。
在用户想要发送消息或附加的图片时,可能会在聊天应用内使用加急工作。同样,处理付款或订阅流程的应用也可能需要使用加急工作。这是 因为这些任务对用户很重要,所以在 需要立即开始,并且即使 用户关闭应用
配额
系统必须先为加急作业分配执行时间, 运行。执行时间并非无限制,每个应用都会获得一个配额 执行时间的长短。当您的应用使用其执行时间并达到 已分配的配额,则在达到配额之前,您将无法执行加急工作 刷新。这样,Android 就能更有效地 应用。
应用可用的执行时间取决于 备用存储分区和进程重要性。
您可以确定在执行配额不允许立即运行加急作业时会出现什么情况。如需了解详情,请参阅以下代码段。
执行加急工作
从 WorkManager 2.7 开始,您的应用可以调用 setExpedited()
来声明 WorkRequest
应该使用加急作业,以尽可能快的速度运行。以下代码段展示了关于如何使用 setExpedited()
的示例:
Kotlin
val request = OneTimeWorkRequestBuilder<SyncWorker>() .setExpedited(OutOfQuotaPolicy.RUN_AS_NON_EXPEDITED_WORK_REQUEST) .build() WorkManager.getInstance(context) .enqueue(request)
Java
OneTimeWorkRequest request = new OneTimeWorkRequestBuilder<T>() .setInputData(inputData) .setExpedited(OutOfQuotaPolicy.RUN_AS_NON_EXPEDITED_WORK_REQUEST) .build();
在此示例中,我们初始化 OneTimeWorkRequest
的实例并对其调用 setExpedited()
。然后,此请求就会变成加急工作。如果配额
允许时,它会立即开始在后台运行。如果配额
OutOfQuotaPolicy
参数表明相应请求应
可以照常运行,非加急工作。
向后兼容性和前台服务
为了保持加急作业的向后兼容性,WorkManager 可能会在 Android 12 之前版本的平台上运行前台服务。前台服务可以向用户显示通知。
在 Android 12 之前,工作器中的 getForegroundInfoAsync()
和 getForegroundInfo()
方法可让 WorkManager 在您调用 setExpedited()
时显示通知。
在以下情况下,任何 ListenableWorker
都必须实现 getForegroundInfo
方法:
请求将任务作为加急作业运行。
以 Android 12 或更高版本为目标平台时,前台服务仍然可供
相应的 setForeground
方法。
工作器
工作器不知道自身所执行的工作是否已加急。不过,在某些版本的 Android 上,如果 WorkRequest
被加急,工作器可以显示通知。
为此,WorkManager 提供了 getForegroundInfoAsync()
方法,您必须实现该方法,让 WorkManager 在必要时显示通知,以便启动 ForegroundService
。
CoroutineWorker
如果您使用 CoroutineWorker
,则必须实现 getForegroundInfo()
。然后,在 doWork()
内将其传递给 setForeground()
。这样做会在 Android 12 之前的版本中创建通知。
请参考以下示例:
class ExpeditedWorker(appContext: Context, workerParams: WorkerParameters):
CoroutineWorker(appContext, workerParams) {
override suspend fun getForegroundInfo(): ForegroundInfo {
return ForegroundInfo(
NOTIFICATION_ID, createNotification()
)
}
override suspend fun doWork(): Result {
TODO()
}
private fun createNotification() : Notification {
TODO()
}
}
配额政策
您可以控制当应用达到其执行配额时加急工作会发生什么情况。如需继续,您可以传递 setExpedited()
:
OutOfQuotaPolicy.RUN_AS_NON_EXPEDITED_WORK_REQUEST
,这会导致作业作为普通工作请求运行。上述代码段演示了此操作。OutOfQuotaPolicy.DROP_WORK_REQUEST
,这会在配额不足时导致请求取消。
示例应用
如需查看关于 WorkManager 2.7.0 如何使用加急工作的完整示例,请查看 GitHub 上的 WorkManagerSample。
延迟加急工作
系统会尝试在调用指定的加急作业后,尽快执行该作业。不过,与其他类型的作业一样,系统可能会延迟启动新的加急工作,如在以下情况下:
- 负载:系统负载过高,当有过多作业已在运行或者当系统内存不足时,就会发生这种情况。
- 配额:已超出加急作业配额限制。加急工作使用基于应用待机存储分区的配额系统,并限制滚动时间窗口中的最大执行时间。配额用于 加急工作比用于其他类型的评估工作的 后台作业。
调度定期工作
您的应用有时可能需要定期运行某些工作。例如,您可能要定期备份数据、定期下载应用中的新鲜内容或者定期上传日志到服务器。
使用 PeriodicWorkRequest
创建定期执行的 WorkRequest
对象的方法如下:
Kotlin
val saveRequest = PeriodicWorkRequestBuilder<SaveImageToFileWorker>(1, TimeUnit.HOURS) // Additional configuration .build()
Java
PeriodicWorkRequest saveRequest = new PeriodicWorkRequest.Builder(SaveImageToFileWorker.class, 1, TimeUnit.HOURS) // Constraints .build();
在此示例中,工作的运行时间间隔定为一小时。
时间间隔定义为两次重复执行之间的最短时间。工作器的确切执行时间取决于您在 WorkRequest 对象中设置的约束以及系统执行的优化。
灵活的运行间隔
如果您的工作的性质致使其对运行时间敏感,您可以将 PeriodicWorkRequest
配置为在每个时间间隔的灵活时间段内运行,如图 1 所示。
图 1. 此图显示了可在灵活时间段内运行工作的的重复间隔。
如需定义具有灵活时间段的定期工作,请在创建 PeriodicWorkRequest
时传递 flexInterval
以及 repeatInterval
。灵活时间段从 repeatInterval - flexInterval
开始,一直到间隔结束。
以下是可在每小时的最后 15 分钟内运行的定期工作的示例。
Kotlin
val myUploadWork = PeriodicWorkRequestBuilder<SaveImageToFileWorker>( 1, TimeUnit.HOURS, // repeatInterval (the period cycle) 15, TimeUnit.MINUTES) // flexInterval .build()
Java
WorkRequest saveRequest = new PeriodicWorkRequest.Builder(SaveImageToFileWorker.class, 1, TimeUnit.HOURS, 15, TimeUnit.MINUTES) .build();
重复间隔必须大于或等于 PeriodicWorkRequest.MIN_PERIODIC_INTERVAL_MILLIS
,而灵活间隔必须大于或等于 PeriodicWorkRequest.MIN_PERIODIC_FLEX_MILLIS
。
约束对定期工作的影响
您可以对定期工作设置约束。例如,您可以为工作请求添加约束,以便工作仅在用户设备充电时运行。在这种情况下,除非满足约束条件,否则即使过了定义的重复间隔,PeriodicWorkRequest
也不会运行。这可能会导致工作在某次运行时出现延迟,甚至会因在相应间隔内未满足条件而被跳过。
工作约束
约束可确保将工作延迟到满足最佳条件时运行。以下约束适用于 WorkManager。
NetworkType | 约束运行工作所需的网络类型。例如 Wi-Fi (UNMETERED )。
|
BatteryNotLow | 如果设置为 true,那么当设备处于“电量不足模式”时,工作不会运行。 |
RequiresCharging | 如果设置为 true,那么工作只能在设备充电时运行。 |
DeviceIdle | 如果设置为 true,则要求用户的设备必须处于空闲状态,才能运行工作。在运行批量操作时,此约束会非常有用;若是不用此约束,批量操作可能会降低用户设备上正在积极运行的其他应用的性能。 |
StorageNotLow | 如果设置为 true,那么当用户设备上的存储空间不足时,工作不会运行。 |
如需创建一组约束并将其与某项工作相关联,请使用一个 Contraints.Builder()
创建 Constraints
实例,并将该实例分配给 WorkRequest.Builder()
。
例如,以下代码会构建了一个工作请求,该工作请求仅在用户设备正在充电且连接到 Wi-Fi 网络时才会运行:
Kotlin
val constraints = Constraints.Builder() .setRequiredNetworkType(NetworkType.UNMETERED) .setRequiresCharging(true) .build() val myWorkRequest: WorkRequest = OneTimeWorkRequestBuilder<MyWork>() .setConstraints(constraints) .build()
Java
Constraints constraints = new Constraints.Builder() .setRequiredNetworkType(NetworkType.UNMETERED) .setRequiresCharging(true) .build(); WorkRequest myWorkRequest = new OneTimeWorkRequest.Builder(MyWork.class) .setConstraints(constraints) .build();
如果指定了多个约束,工作将仅在满足所有约束时才会运行。
如果在工作运行时不再满足某个约束,WorkManager 将停止工作器。系统将在满足所有约束后重试工作。
延迟工作
如果工作没有约束,或者当工作加入队列时所有约束都得到了满足,那么系统可能会选择立即运行该工作。如果您不希望工作立即运行,可以将工作指定为在经过一段最短初始延迟时间后再启动。
下面举例说明了如何将工作设置为在加入队列后至少经过 10 分钟后再运行。
Kotlin
val myWorkRequest = OneTimeWorkRequestBuilder<MyWork>() .setInitialDelay(10, TimeUnit.MINUTES) .build()
Java
WorkRequest myWorkRequest = new OneTimeWorkRequest.Builder(MyWork.class) .setInitialDelay(10, TimeUnit.MINUTES) .build();
该示例说明了如何为 OneTimeWorkRequest
设置初始延迟时间,您也可以为 PeriodicWorkRequest
设置初始延迟时间。在这种情况下,定期工作只有首次运行时会延迟。
重试和退避政策
如果您需要让 WorkManager 重试工作,可以从工作器返回 Result.retry()
。然后,系统将根据退避延迟时间和退避政策重新调度工作。
退避延迟时间指定了首次尝试后重试工作前的最短等待时间。此值不能超过 10 秒(或 MIN_BACKOFF_MILLIS)。
退避政策定义了在后续重试过程中,退避延迟时间随时间以怎样的方式增长。WorkManager 支持 2 个退避政策,即
LINEAR
和EXPONENTIAL
。
每个工作请求都有退避政策和退避延迟时间。默认政策
为 EXPONENTIAL
,延迟时间为 30 秒,但您可以在
工作请求配置。
以下是自定义退避延迟时间和政策的示例。
Kotlin
val myWorkRequest = OneTimeWorkRequestBuilder<MyWork>() .setBackoffCriteria( BackoffPolicy.LINEAR, OneTimeWorkRequest.MIN_BACKOFF_MILLIS, TimeUnit.MILLISECONDS) .build()
Java
WorkRequest myWorkRequest = new OneTimeWorkRequest.Builder(MyWork.class) .setBackoffCriteria( BackoffPolicy.LINEAR, OneTimeWorkRequest.MIN_BACKOFF_MILLIS, TimeUnit.MILLISECONDS) .build();
在本示例中,最短退避延迟时间设置为允许的最小值,即 10 秒。由于政策为 LINEAR
,每次尝试重试时,重试间隔都会增加约 10 秒。例如,第一次运行以 Result.retry()
结束并在 10 秒后重试;然后,如果工作在后续尝试后继续返回 Result.retry()
,那么接下来会在 20 秒、30 秒、40 秒后重试,以此类推。如果退避政策设置为 EXPONENTIAL
,那么重试时长序列将接近 20、40、80 秒,以此类推。
标记工作
每个工作请求都有一个唯一标识符,该标识符可用于在以后标识该工作,以便取消工作或观察其进度。
如果有一组在逻辑上相关的工作,对这些工作项进行标记可能也会很有帮助。通过标记,您一起处理一组工作请求。
例如,WorkManager.cancelAllWorkByTag(String)
会取消带有特定标记的所有工作请求,WorkManager.getWorkInfosByTag(String)
会返回一个 WorkInfo 对象列表,该列表可用于确定当前工作状态。
以下代码展示了如何向工作添加“cleanup”标记:
Kotlin
val myWorkRequest = OneTimeWorkRequestBuilder<MyWork>() .addTag("cleanup") .build()
Java
WorkRequest myWorkRequest = new OneTimeWorkRequest.Builder(MyWork.class) .addTag("cleanup") .build();
最后,可以向单个工作请求添加多个标记。这些标记在内部以一组字符串的形式进行存储。您可以使用 WorkInfo.getTags() 获取与 WorkRequest
关联的标记集。
从 Worker
类中,您可以通过 ListenableWorker.getTags() 检索其标记集。
分配输入数据
您的工作可能需要输入数据才能正常运行。例如,处理图片上传的工作可能需要使用待上传图片的 URI 作为输入数据。
输入值以键值对的形式存储在 Data
对象中,并且可以在工作请求中设置。WorkManager 会在执行工作时将输入 Data
传递给工作。Worker
类可通过调用 Worker.getInputData()
访问输入参数。以下代码展示了如何创建需要输入数据的 Worker
实例,以及如何在工作请求中发送该实例。
Kotlin
// Define the Worker requiring input class UploadWork(appContext: Context, workerParams: WorkerParameters) : Worker(appContext, workerParams) { override fun doWork(): Result { val imageUriInput = inputData.getString("IMAGE_URI") ?: return Result.failure() uploadFile(imageUriInput) return Result.success() } ... } // Create a WorkRequest for your Worker and sending it input val myUploadWork = OneTimeWorkRequestBuilder<UploadWork>() .setInputData(workDataOf( "IMAGE_URI" to "http://..." )) .build()
Java
// Define the Worker requiring input public class UploadWork extends Worker { public UploadWork(Context appContext, WorkerParameters workerParams) { super(appContext, workerParams); } @NonNull @Override public Result doWork() { String imageUriInput = getInputData().getString("IMAGE_URI"); if(imageUriInput == null) { return Result.failure(); } uploadFile(imageUriInput); return Result.success(); } ... } // Create a WorkRequest for your Worker and sending it input WorkRequest myUploadWork = new OneTimeWorkRequest.Builder(UploadWork.class) .setInputData( new Data.Builder() .putString("IMAGE_URI", "http://...") .build() ) .build();
同样,可使用 Data
类输出返回值。如需详细了解输入和输出数据,请参阅输入参数和返回值部分。
后续步骤
在状态和观察页面中,您将详细了解工作状态以及如何监控工作的进度。