WorkManager به شما امکان میدهد WorkRequest را پساز اینکه آن را در صف قرار دادید بهروز کنید. این کار اغلب در برنامههای بزرگتر که مکرراً محدودیتها را تغییر میدهند یا نیاز دارند کارگران خود را درحال اجرا بهروز کنند، ضروری است. از WorkManager
نسخه ۲.۸.۰، میانای برنامهسازی کاربردی updateWork() ابزار انجام این کار است.
روش updateWork() به شما امکان میدهد جنبههای خاصی از WorkRequest را درحین اجرا تغییر دهید، بدون اینکه لازم باشد فرایند لغو دستی و صفبندی مورد جدید را طی کنید. این کار فرایند توسعه را بسیار ساده میکند.
اجتناب از لغو کار
بهطور کلی باید از لغو WorkRequest موجود و صفبندی WorkRequest جدید اجتناب کنید. این کار میتواند باعث شود برنامه برخیاز تکالیف را تکرار کند و ممکن است لازم باشد مقدار قابلتوجهی کد اضافی بنویسید.
نمونههای زیر را درنظر بگیرید که در آنها لغو WorkRequest میتواند باعث بروز مشکل شود:
- درخواست پسنهایی: اگر
Workerرا درحالیکه درحال محاسبه بارداده برای ارسال به سرور است لغو کنید،Workerجدید باید از ابتدا شروع کند و بارداده احتمالاً پرهزینه را دوباره محاسبه کند. - زمانبندی: اگر
PeriodicWorkRequestرا لغو کنید و بخواهیدPeriodicWorkRequestجدید طبق همان زمانبندی اجرا شود، باید انحراف زمانی را محاسبه کنید تا مطمئن شوید زمان اجرای جدید با درخواست کار قبلی مطابقت دارد.
updateWork() API به شما امکان میدهد محدودیتها و سایر پارامترهای درخواست کار را بدون دردسر لغو کردن و صفبندی درخواست جدید بهروز کنید.
زمان لغو کار
مواردی وجود دارد که باید مستقیماً WorkRequest را لغو کنید و با updateWork() تماس نگیرید. این کاری است که باید انجام دهید وقتی میخواهید ماهیت اساسی کاری را که در صف قرار دادهاید تغییر دهید.
زمان بهروزرسانی کار
برنامه عکسی را تصور کنید که روزانه از عکسهای کاربر پشتیبانگیری میکند. برای انجام این کار،
PeriodicWorkRequest را در صف قرار داده است. WorkRequest محدودیتهایی دارد
که مستلزم آن است که دستگاه درحال شارژ و به Wi-Fi متصل باشد.
اما کاربر فقط ۲۰ دقیقه در روز دستگاهش را با شارژر سریع شارژ میکند. در این حالت، ممکن است برنامه بخواهد WorkRequest را بهروز کند تا محدودیت شارژ را کاهش دهد، بهطوریکه همچنان بتواند عکسها را بارگذاری کند حتی اگر دستگاه کاملاً شارژ نشده باشد.
در این شرایط، میتوانید از روش updateWork() برای بهروزرسانی محدودیتهای درخواست کار استفاده کنید.
نحوه بهروزرسانی محل کار
روش updateWork() ابزار سادهای برای بهروزرسانی WorkRequest موجود ارائه میدهد، بدون اینکه لازم باشد آن را لغو کنید و در صف جدیدی قرار دهید.
برای استفاده از بهروزرسانی کار در صف، این مراحل را دنبال کنید:
- دریافت شناسه موجود برای کار در صف: شناسه WorkRequest را که میخواهید بهروز کنید دریافت کنید. میتوانید این شناسه را با هریک از
getWorkInfoAPIها بازیابی کنید، یا با حفظ دستی شناسه از WorkRequest اولیه برای بازیابی بعدی با ویژگی عمومیWorkRequest.id، قبلاز قرار دادن آن در صف. - ایجاد WorkRequest جدید:
WorkRequestجدیدی ایجاد کنید و ازWorkRequest.Builder.setID()استفاده کنید تا شناسه آن را با شناسهWorkRequestموجود مطابقت دهید. - تنظیم محدودیتها: از
WorkRequest.Builder.setConstraints()برای ارسال محدودیتهای جدید WorkManager استفاده کنید. - فراخوانی updateWork: WorkRequest جدید را به
updateWork()ارسال کنید.
بهروزرسانی نمونه کار
در اینجا نمونه تکهکدی در Kotlin آورده شده است که نحوه استفاده از روش
updateWork() را برای تغییر محدودیتهای باتری WorkRequest مورداستفاده
برای بارگذاری عکسها نشان میدهد:
suspend fun updatePhotoUploadWork() {
// Get instance of WorkManager.
val workManager = WorkManager.getInstance(context)
// Retrieve the work request ID. In this example, the work being updated is unique
// work so we can retrieve the ID using the unique work name.
val photoUploadWorkInfoList = workManager.getWorkInfosForUniqueWork(
PHOTO_UPLOAD_WORK_NAME
).await()
val existingWorkRequestId = photoUploadWorkInfoList.firstOrNull()?.id ?: return
// Update the constraints of the WorkRequest to not require a charging device.
val newConstraints = Constraints.Builder()
// Add other constraints as required here.
.setRequiresCharging(false)
.build()
// Create new WorkRequest from existing Worker, new constraints, and the id of the old WorkRequest.
val updatedWorkRequest: WorkRequest =
OneTimeWorkRequestBuilder<MyWorker>()
.setConstraints(newConstraints)
.setId(existingWorkRequestId)
.build()
// Pass the new WorkRequest to updateWork().
workManager.updateWork(updatedWorkRequest)
}
مدیریت نتیجه
updateWork() ListenableFuture<UpdateResult> را برمیگرداند. UpdateResult ارائهشده میتواند یکی از چندین مقداری باشد که نشان میدهد آیا WorkManager توانسته است تغییرات شما را اعمال کند یا نه. همچنین نشان میدهد که چه زمانی توانسته است
تغییر را اعمال کند.
برای اطلاعات بیشتر، به مرجع updateWork() و UpdateResult
مراجعه کنید.
پیگیری کار با محتوای تولیدشده
هربار که WorkRequest را بهروز میکنید، نسل آن یک عدد افزایش مییابد. این
به شما امکان میدهد دقیقاً ردیابی کنید که کدام WorkRequest درحالحاضر در صف قرار دارد.
نسلها به شما امکان میدهند کنترل بیشتری بر مشاهده، ردیابی، و آزمایش درخواستهای کاری داشته باشید.
برای دریافت نسل WorkRequest، این مراحل را دنبال کنید:
- WorkInfo: برای بازیابی نمونهای از
WorkInfoکه باWorkRequestشما مطابقت دارد،WorkManager.getWorkInfoById()را فراخوانی کنید.- میتوانید یکی از چندین روشی را که
WorkInfoبرمیگرداند فراخوانی کنید. برای اطلاعات بیشتر، مرجع WorkManager را ببینید.
- میتوانید یکی از چندین روشی را که
- getGeneration:
getGeneration()را در نمونهWorkInfoفراخوانی کنید. Intبرگرداندهشده با تولیدWorkRequestمطابقت دارد.- توجه داشته باشید که فیلد یا ویژگی تولید وجود ندارد، فقط
روش
WorkInfo.getGeneration()وجود دارد.
- توجه داشته باشید که فیلد یا ویژگی تولید وجود ندارد، فقط
روش
نمونه تولید قطعه موسیقی
در زیر نمونهای از پیادهسازی گردش کار شرحدادهشده در بالا برای بازیابی نسل WorkRequest آورده شده است.
// Get instance of WorkManager.
val workManager = WorkManager.getInstance(context)
// Retrieve WorkInfo instance.
val workInfo = workManager.getWorkInfoById(oldWorkRequestId)
// Call getGeneration to retrieve the generation.
val generation = workInfo.getGeneration()
خطمشیهای بهروزرسانی کار
قبلاً، راهحل توصیهشده برای بهروزرسانی کار دورهای این بود که
PeriodicWorkRequest با خطمشی ExistingPeriodicWorkPolicy.REPLACE در صف قرار داده شود.
اگر PeriodicWorkRequest معلقی با همان id غیرتکراری وجود داشته باشد، درخواست کار جدید آن را لغو و حذف میکند. این خطمشی اکنون منسوخ شده است و
بهجای آن از گردش کار بااستفاده از ExistingPeriodicWorkPolicy.UPDATE استفاده میشود.
برای مثال، هنگام استفاده از enqueueUniquePeriodicWork با
PeriodicWorkRequest، میتوانید PeriodicWorkRequest جدید را با خطمشی
ExistingPeriodicWorkPolicy.UPDATE مقداردهی اولیه کنید. اگر
PeriodicWorkRequest معلقی با همان نام غیرتکراری وجود داشته باشد، WorkManager آن را به
مشخصات جدید بهروز میکند. با دنبال کردن این گردش کار، نیازی به استفاده از
updateWork() نیست.