WorkManager 内置了对长时间运行的 worker 的支持。在这种情况下,WorkManager 可以向操作系统提供一个信号,指示在此项工作执行期间应尽可能让进程保持活跃状态。这些 worker 可以运行超过 10 分钟。这一新功能的示例用例包括批量上传或下载(不可分块)、在本地进行的机器学习模型处理,或者对应用的用户很重要的任务。
在后台,WorkManager 会代表您管理和运行前台服务以执行 WorkRequest
,同时还会显示可配置的通知。
ListenableWorker
现在支持 setForegroundAsync()
API,而 CoroutineWorker
则支持挂起 setForeground()
API。这些 API 允许开发者指定此 WorkRequest
是“重要的”(从用户的角度来看)或“长时间运行的”任务。
从 2.3.0-alpha03
开始,WorkManager 还允许您创建 PendingIntent
,此 Intent 可用于取消 worker,而不必使用 createCancelPendingIntent()
API 注册新的 Android 组件。此方法与 setForegroundAsync()
或 setForeground()
API 一起使用时特别有用,可用于添加一个取消 Worker
的通知操作。
创建和管理长时间运行的 worker
使用 Kotlin 和 Java 进行编码时所用的方法稍有不同。
Kotlin
Kotlin 开发者应使用 CoroutineWorker
。您可以不使用 setForegroundAsync()
,而使用该方法的挂起版本 setForeground()
。
class DownloadWorker(context: Context, parameters: WorkerParameters) :
CoroutineWorker(context, parameters) {
private val notificationManager =
context.getSystemService(Context.NOTIFICATION_SERVICE) as
NotificationManager
override suspend fun doWork(): Result {
val inputUrl = inputData.getString(KEY_INPUT_URL)
?: return Result.failure()
val outputFile = inputData.getString(KEY_OUTPUT_FILE_NAME)
?: return Result.failure()
// Mark the Worker as important
val progress = "Starting Download"
setForeground(createForegroundInfo(progress))
download(inputUrl, outputFile)
return Result.success()
}
private fun download(inputUrl: String, outputFile: String) {
// Downloads a file and updates bytes read
// Calls setForeground() periodically when it needs to update
// the ongoing Notification
}
// Creates an instance of ForegroundInfo which can be used to update the
// ongoing notification.
private fun createForegroundInfo(progress: String): ForegroundInfo {
val id = applicationContext.getString(R.string.notification_channel_id)
val title = applicationContext.getString(R.string.notification_title)
val cancel = applicationContext.getString(R.string.cancel_download)
// This PendingIntent can be used to cancel the worker
val intent = WorkManager.getInstance(applicationContext)
.createCancelPendingIntent(getId())
// Create a Notification channel if necessary
if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
createChannel()
}
val notification = NotificationCompat.Builder(applicationContext, id)
.setContentTitle(title)
.setTicker(title)
.setContentText(progress)
.setSmallIcon(R.drawable.ic_work_notification)
.setOngoing(true)
// Add the cancel action to the notification which can
// be used to cancel the worker
.addAction(android.R.drawable.ic_delete, cancel, intent)
.build()
return ForegroundInfo(notificationId, notification)
}
@RequiresApi(Build.VERSION_CODES.O)
private fun createChannel() {
// Create a Notification channel
}
companion object {
const val KEY_INPUT_URL = "KEY_INPUT_URL"
const val KEY_OUTPUT_FILE_NAME = "KEY_OUTPUT_FILE_NAME"
}
}
Java
使用 ListenableWorker
或 Worker
的开发者可以调用 setForegroundAsync()
API,该 API 会返回 ListenableFuture<Void>
。您还可以调用 setForegroundAsync()
以更新持续运行的 Notification
。
下面是一个简单的示例,说明了一个下载文件的长时间运行 worker。此 worker 会跟踪进度,以更新持续显示下载进度的 Notification
。
public class DownloadWorker extends Worker {
private static final String KEY_INPUT_URL = "KEY_INPUT_URL";
private static final String KEY_OUTPUT_FILE_NAME = "KEY_OUTPUT_FILE_NAME";
private NotificationManager notificationManager;
public DownloadWorker(
@NonNull Context context,
@NonNull WorkerParameters parameters) {
super(context, parameters);
notificationManager = (NotificationManager)
context.getSystemService(NOTIFICATION_SERVICE);
}
@NonNull
@Override
public Result doWork() {
Data inputData = getInputData();
String inputUrl = inputData.getString(KEY_INPUT_URL);
String outputFile = inputData.getString(KEY_OUTPUT_FILE_NAME);
// Mark the Worker as important
String progress = "Starting Download";
setForegroundAsync(createForegroundInfo(progress));
download(inputUrl, outputFile);
return Result.success();
}
private void download(String inputUrl, String outputFile) {
// Downloads a file and updates bytes read
// Calls setForegroundAsync(createForegroundInfo(myProgress))
// periodically when it needs to update the ongoing Notification.
}
@NonNull
private ForegroundInfo createForegroundInfo(@NonNull String progress) {
// Build a notification using bytesRead and contentLength
Context context = getApplicationContext();
String id = context.getString(R.string.notification_channel_id);
String title = context.getString(R.string.notification_title);
String cancel = context.getString(R.string.cancel_download);
// This PendingIntent can be used to cancel the worker
PendingIntent intent = WorkManager.getInstance(context)
.createCancelPendingIntent(getId());
if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
createChannel();
}
Notification notification = new NotificationCompat.Builder(context, id)
.setContentTitle(title)
.setTicker(title)
.setSmallIcon(R.drawable.ic_work_notification)
.setOngoing(true)
// Add the cancel action to the notification which can
// be used to cancel the worker
.addAction(android.R.drawable.ic_delete, cancel, intent)
.build();
return new ForegroundInfo(notificationId, notification);
}
@RequiresApi(Build.VERSION_CODES.O)
private void createChannel() {
// Create a Notification channel
}
}
将前台服务类型添加到长时间运行的 worker
如果您的应用以 Android 14(API 级别 34)或更高版本为目标平台,则必须指定
前台服务类型。
如果您的应用以 Android 10(API 级别 29)或更高版本为目标平台,并且包含
需要访问位置信息的长时间运行的 worker,指明该 worker
使用前台服务类型 location
。
如果您的应用以 Android 11(API 级别 30)或更高版本为目标平台
并包含一个需要访问摄像头或麦克风的长时间运行的 worker,
声明 camera
或 microphone
前台
服务类型。
如需添加这些前台服务类型,请完成以下各部分中介绍的步骤。
在应用清单中声明前台服务类型
在应用的清单中声明 worker 的前台服务类型。在以下示例中,worker 需要位置信息和麦克风访问权限:
AndroidManifest.xml
<service android:name="androidx.work.impl.foreground.SystemForegroundService" android:foregroundServiceType="location|microphone" tools:node="merge" />
在运行时指定前台服务类型
当您调用 setForeground()
或 setForegroundAsync()
时,请务必指定
前台服务类型。
MyLocationAndMicrophoneWorker
Kotlin
private fun createForegroundInfo(progress: String): ForegroundInfo { // ... return ForegroundInfo(NOTIFICATION_ID, notification, FOREGROUND_SERVICE_TYPE_LOCATION or FOREGROUND_SERVICE_TYPE_MICROPHONE) }
Java
@NonNull private ForegroundInfo createForegroundInfo(@NonNull String progress) { // Build a notification... Notification notification = ...; return new ForegroundInfo(NOTIFICATION_ID, notification, FOREGROUND_SERVICE_TYPE_LOCATION | FOREGROUND_SERVICE_TYPE_MICROPHONE); }