如要開始使用 WorkManager,請先將程式庫匯入 Android 專案。
在應用程式的 build.gradle
檔案中新增下列依附元件:
Groovy
dependencies { def work_version = "2.9.1" // (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.9.1" // (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
也可加入其他資訊,例如作業執行時的限制條件、作業的輸入內容、延遲和重試作業的輪詢政策。在下一節「定義作業要求」中,您將進一步瞭解這些選項,並瞭解如何安排專屬且重複發生的作業。
其他資源
除了指南文件以外,還有多種網誌、程式碼研究室和程式碼範例可協助您順利上手。
範例
- WorkManagerSample,簡單的圖片處理應用程式。
- Sunflower 是一個試用版應用程式,當中展示了各種架構元件 (包括 WorkManager) 的最佳做法。
Codelab
- 使用 WorkManager (Kotlin) 和 (Java)
- 進階 WorkManager (Kotlin)
網誌
- 隆重推出 WorkManager
- WorkManager 基本概念
- WorkManager 與 Kotlin
- WorkManager 作業週期
- 自訂 WorkManager - 基礎知識
- 使用 Dagger 自訂 WorkManager