開始使用 WorkManager

如要開始使用 WorkManager，請先將程式庫匯入 Android 專案。

在應用程式的 build.gradle 檔案中新增下列依附元件：

Groovy

dependencies {     def work_version = "2.10.2"      // (Java only)     implementation "androidx.work:work-runtime:$work_version"      // Kotlin + coroutines     implementation "androidx.work:work-runtime-ktx:$work_version"      // optional - RxJava2 support     implementation "androidx.work:work-rxjava2:$work_version"      // optional - GCMNetworkManager support     implementation "androidx.work:work-gcm:$work_version"      // optional - Test helpers     androidTestImplementation "androidx.work:work-testing:$work_version"      // optional - Multiprocess support     implementation "androidx.work:work-multiprocess:$work_version" }

Kotlin

dependencies {     val work_version = "2.10.2"      // (Java only)     implementation("androidx.work:work-runtime:$work_version")      // Kotlin + coroutines     implementation("androidx.work:work-runtime-ktx:$work_version")      // optional - RxJava2 support     implementation("androidx.work:work-rxjava2:$work_version")      // optional - GCMNetworkManager support     implementation("androidx.work:work-gcm:$work_version")      // optional - Test helpers     androidTestImplementation("androidx.work:work-testing:$work_version")      // optional - Multiprocess support     implementation("androidx.work:work-multiprocess:$work_version") }

新增依附元件並同步處理 Gradle 專案後，下一步為定義要執行的某些作業。

定義作業

請使用 Worker 類別定義作業。doWork() 方法會以非同步方式在 WorkManager 提供的背景執行緒上執行。

如要建立某些 WorkManager 執行的作業，請擴充 Worker 類別並覆寫 doWork() 方法。舉例來說，如要建立 Worker 來上傳圖片，您可以執行下列操作：

Kotlin

class UploadWorker(appContext: Context, workerParams: WorkerParameters):        Worker(appContext, workerParams) {    override fun doWork(): Result {         // Do the work here--in this case, upload the images.        uploadImages()         // Indicate whether the work finished successfully with the Result        return Result.success()    } }

Java

public class UploadWorker extends Worker {    public UploadWorker(        @NonNull Context context,        @NonNull WorkerParameters params) {        super(context, params);    }     @Override    public Result doWork() {       // Do the work here--in this case, upload the images.      uploadImages();       // Indicate whether the work finished successfully with the Result      return Result.success();    } }

從 doWork() 回傳的 Result 會通知 WorkManager 服務，說明作業是否成功，以及如果作業失敗，是否應重試作業。

  • Result.success()：作業順利完成。
  • Result.failure()：作業失敗。
  • Result.retry()：作業失敗，並會根據其重試政策在另一時間進行重試。

建立 WorkRequest

定義作業後，必須先透過 WorkManager 服務排定執行作業。WorkManager 為您安排作業進行的方式提供很大的彈性。您可以將其安排為定期執行，也可以將其安排為只執行一次。

無論您選擇如何安排作業，將一律使用 WorkRequest。雖然 Worker 定義了作業單位，但 WorkRequest (及其子類別) 則定義了應執行的方式和時間。在最簡單的情況下，您可以使用 OneTimeWorkRequest，如以下範例所示。

Kotlin

val uploadWorkRequest: WorkRequest =    OneTimeWorkRequestBuilder<UploadWorker>()        .build()

Java

WorkRequest uploadWorkRequest =    new OneTimeWorkRequest.Builder(UploadWorker.class)        .build();

將 WorkRequest 提交至系統

最後，您必須使用 enqueue() 方法將 WorkRequest 提交至 WorkManager。

Kotlin

WorkManager     .getInstance(myContext)     .enqueue(uploadWorkRequest)

Java

WorkManager     .getInstance(myContext)     .enqueue(uploadWorkRequest);

工作站執行的確切時間取決於 WorkRequest 及系統最佳化作業中使用的限制條件。WorkManager 的設計宗旨，就是要在這些限制下提供最佳行為。

後續步驟

本入門指南僅稍作淺談。WorkRequest 也可加入其他資訊，例如作業執行時的限制條件、作業的輸入內容、延遲和重試作業的輪詢政策。在下一節「定義作業要求」中，您將進一步瞭解這些選項，並瞭解如何安排專屬且重複發生的作業。

其他資源

除了指南文件以外，還有多種網誌、程式碼研究室和程式碼範例可協助您順利上手。

範例

  • Sunflower 是一個試用版應用程式，當中展示了各種架構元件 (包括 WorkManager) 的最佳做法。

Codelab

網誌