بدء استخدام WorkManager

لبدء استخدام WorkManager، عليك أولاً استيراد المكتبة إلى مشروع Android.

أضِف التبعيات التالية إلى ملف build.gradle في تطبيقك:

أنيق

dependencies {
    def work_version = "2.12.0"

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

    // (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();
   }
}

تُعلم القيمة Result التي تم عرضها من doWork() خدمة 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 إلى النظام

أخيرًا، عليك إرسال WorkRequest إلى WorkManager باستخدام طريقة enqueue().

Kotlin

WorkManager
    .getInstance(myContext)
    .enqueue(uploadWorkRequest)

Java

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

يعتمد الوقت المحدّد لتنفيذ العامل على القيود المستخدَمة في WorkRequest وعلى عمليات تحسين النظام. تم تصميم WorkManager لتقديم أفضل أداء في ظل هذه القيود.

الخطوات التالية

هذا الدليل هو مجرد بداية. يمكن أن يتضمّن WorkRequest أيضًا معلومات إضافية، مثل القيود التي يجب تشغيل العمل في ظلها، والمدخلات إلى العمل، والتأخير، وسياسة التراجع لإعادة محاولة العمل. في القسم التالي، تحديد طلبات العمل، ستتعرّف على مزيد من المعلومات حول هذه الخيارات بمزيد من التفصيل، بالإضافة إلى فهم كيفية جدولة العمل الفريد والمتكرر.

مراجع إضافية

بالإضافة إلى مستندات الدليل، تتوفّر عدة مدوّنات ودروس تطبيقية حول الترميز لمساعدتك في البدء.

اختبارات الرموز

المدوّنات