開始使用 WorkManager

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

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

Groovy

dependencies {
    def work_version = "2.10.3"

    // (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.3"

    // (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

網誌