支持长时间运行的 Worker

WorkManager 对长时间运行的 Worker 具有内置支持。在这种情况下，WorkManager 可以向操作系统发出信号，指示进程在工作执行期间应尽可能保持活动状态。这些 Worker 可以运行超过 10 分钟。此新功能的用例示例包括批量上传或下载（无法分块）、在本地处理 ML 模型或对应用用户而言重要的任务。

在后台，WorkManager 代表您管理并运行前台服务以执行 WorkRequest，同时还显示可配置的通知。

ListenableWorker 现在支持 setForegroundAsync() API，而 CoroutineWorker 支持挂起 setForeground() API。这些 API 允许开发者指定此 WorkRequest 是重要（从用户角度）的还是长时间运行的。

从 2.3.0-alpha03 开始，WorkManager 还允许您创建 PendingIntent，可以使用 createCancelPendingIntent() API 取消 Worker，而无需注册新的 Android 组件。此方法在与 setForegroundAsync() 或 setForeground() API 结合使用时特别有用，这些 API 可用于添加通知操作以取消 Worker。

创建和管理长时间运行的 Worker

根据您使用 Kotlin 还是 Java 编码，您将采用稍微不同的方法。

Kotlin

Kotlin 开发者应使用 CoroutineWorker。您可以使用该方法的挂起版本 setForeground()，而不是使用 setForegroundAsync()。

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）或更高版本，则必须为所有长时间运行的 Worker 指定前台服务类型。如果您的应用目标是 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);
}