این راهنما بر شکستن تغییرات ارائه شده در Workbox v4 متمرکز شده است، با نمونه هایی از تغییراتی که باید هنگام ارتقاء از Workbox v3 ایجاد کنید.
شکستن تغییرات
جعبه کار-پیش کش
قرارداد نامگذاری برای ورودی های پیش کش به روز شده است. اکنون، برای ورودی‌هایی که نشانی‌های اینترنتی آنها به اطلاعات بازبینی نیاز دارند (یعنی آن ورودی‌هایی که حاوی یک فیلد revision در مانیفست پیش کش هستند )، این اطلاعات نسخه‌سازی به‌عنوان بخشی از کلید حافظه پنهان، در یک پارامتر درخواست URL ویژه __WB_REVISION__ که به URL اصلی اضافه شده است، ذخیره می‌شود. (پیش از این، این اطلاعات جدا از کلیدهای حافظه پنهان با استفاده از IndexedDB ذخیره می شد.)
توسعه دهندگانی که از پیش کش کردن از طریق workbox.precaching.precacheAndRoute() که رایج ترین مورد استفاده است، استفاده می کنند، نیازی به ایجاد هیچ تغییری در پیکربندی Service Worker خود ندارند. پس از ارتقاء به Workbox v4، دارایی‌های ذخیره‌شده کاربران شما به‌طور خودکار به فرمت جدید کلید حافظه پنهان منتقل می‌شوند، و با حرکت رو به جلو، منابع از پیش ذخیره‌شده به همان روش قبلی ارائه می‌شوند.
استفاده مستقیم از کلیدهای کش
برخی از توسعه دهندگان ممکن است نیاز به دسترسی مستقیم به ورودی های پیش کش، خارج از زمینه workbox.precaching.precacheAndRoute() داشته باشند. به عنوان مثال، ممکن است تصویری را که در نهایت از آن به عنوان یک پاسخ "بازگشت" استفاده می کنید، زمانی که تصویر واقعی از شبکه قابل واکشی نیست، پیش کش کنید.
اگر به این روش از دارایی‌های از پیش ذخیره‌شده استفاده می‌کنید، از Workbox v4 شروع می‌کنید، باید یک گام دیگر را بردارید تا یک URL اصلی را به کلید حافظه پنهان مربوطه ترجمه کنید که می‌تواند برای خواندن ورودی ذخیره‌شده استفاده شود. این کار را با فراخوانی workbox.precaching.getCacheKeyForURL(originURL) انجام می‌دهید.
برای مثال، اگر می‌دانید که 'fallback.png' از پیش ذخیره شده است:
const imageFallbackCacheKey =
workbox.precaching.getCacheKeyForURL('fallback.png');
workbox.routing.setCatchHandler(({event}) => {
switch (event.request.destination) {
case 'image':
return caches.match(imageFallbackCacheKey);
break;
// ...other fallback logic goes here...
}
});
پاک کردن داده های قدیمی از پیش ذخیره شده
تغییرات ایجاد شده در پیش کش در Workbox v4 به این معنی است که پیش کش های قدیمی که توسط نسخه های قبلی Workbox ایجاد شده اند، سازگار نیستند. به‌طور پیش‌فرض، آنها همان‌طور که هستند باقی می‌مانند، و اگر از Workbox v3 به Workbox v4 ارتقا دهید، در نهایت دو نسخه از تمام منابع از پیش ذخیره‌شده خود خواهید داشت.
برای جلوگیری از این امر، می‌توانید تماس را به workbox.precaching.cleanupOutdatedCaches() مستقیماً به یک سرویس‌کار اضافه کنید، یا اگر از ابزار ساخت در حالت GenerateSW استفاده می‌کنید، گزینه جدید cleanupOutdatedCaches: true را تنظیم کنید. از آنجایی که منطق پاکسازی حافظه نهان بر روی قراردادهای نامگذاری حافظه پنهان برای یافتن پیش کش های قدیمی تر عمل می کند، و از آنجایی که توسعه دهندگان این گزینه را دارند که این قراردادها را نادیده بگیرند، ما در مورد ایمنی اشتباه کردیم و این را به طور پیش فرض فعال نکردیم.
از توسعه دهندگانی که در استفاده از این با مشکل مواجه می شوند -مانند موارد مثبت کاذب در مورد حذف- تشویق می کنیم که به ما اطلاع دهند .
حروف بزرگ پارامتر
دو پارامتر اختیاری که می‌توانند به workbox.precaching.precacheAndRoute() و workbox.precaching.addRoute() منتقل شوند، برای استاندارد کردن قرارداد کلی حروف بزرگ ما تغییر نام داده‌اند. ignoreUrlParametersMatching اکنون ignoreURLParametersMatching است و cleanUrls اکنون cleanURLs است.
جعبه کار - استراتژی ها
دو روش تقریباً معادل برای ایجاد یک نمونه از یک handler در workbox-strategies وجود دارد. ما روش کارخانه را منسوخ می‌کنیم، به نفع فراخوانی صریح سازنده استراتژی.
// This factory method syntax has been deprecated:
const networkFirstStrategy = workbox.strategies.networkFirst({...});
// Instead, use the constructor directly:
// (Note that the class name is Uppercase.)
const networkFirstStrategy = new workbox.strategies.NetworkFirst({...});
در حالی که سینتکس روش کارخانه در نسخه 4 به کار خود ادامه می دهد، استفاده از آن یک اخطار ثبت می کند و ما توسعه دهندگان را تشویق می کنیم که پیش از حذف پشتیبانی در نسخه بعدی نسخه 5 مهاجرت کنند.
جعبه کار-پس زمینه-همگام سازی
کلاس workbox.backgroundSync.Queue بازنویسی شده است تا به توسعه دهندگان انعطاف پذیری و کنترل بیشتری بر روی نحوه اضافه شدن درخواست ها به صف و پخش مجدد ارائه شود.
در نسخه 3، کلاس Queue یک راه برای اضافه کردن درخواست‌ها به صف داشت (روش addRequest() )، اما هیچ راهی برای اصلاح صف یا حذف درخواست‌ها نداشت.
در نسخه 4، متد addRequests() حذف شده و متدهای آرایه مانند زیر اضافه شده است:
-
pushRequest() -
popRequest() -
shiftRequest() -
unshiftRequest()
در نسخه 3، کلاس Queue چندین تماس را نیز پذیرفت که به شما امکان می‌داد زمان پخش مجدد درخواست‌ها را مشاهده کنید ( requestWillEnqueue ، requestWillReplay ، queueDidReplay )، اما بیشتر توسعه‌دهندگان دریافتند که علاوه بر مشاهده، می‌خواهند روی نحوه پخش مجدد صف نیز کنترل داشته باشند. توانایی تغییر پویا، سفارش مجدد، یا حتی لغو درخواست های فردی.
در نسخه 4، این تماس‌های برگشتی به نفع یک پاسخ به تماس onSync حذف شده‌اند که هر زمانی که مرورگر تلاشی برای پخش مجدد انجام می‌دهد، فراخوانی می‌شود. به‌طور پیش‌فرض، پاسخ به تماس onSync ، replayRequests() را فراخوانی می‌کند، اما اگر به کنترل بیشتری بر روند پخش نیاز دارید، می‌توانید از روش‌های آرایه‌مانند فهرست‌شده در بالا برای پخش مجدد صف به هر نحوی که دوست دارید استفاده کنید.
در اینجا یک مثال از منطق تکرار سفارشی آورده شده است:
const queue = new workbox.backgroundSync.Queue('my-queue-name', {
onSync: async ({queue}) => {
let entry;
while ((entry = await this.shiftRequest())) {
try {
await fetch(entry.request);
} catch (error) {
console.error('Replay failed for request', entry.request, error);
await this.unshiftRequest(entry);
return;
}
}
console.log('Replay complete!');
},
});
به طور مشابه، کلاس workbox.backgroundSync.Plugin همان آرگومان های کلاس Queue را می پذیرد (از آنجایی که یک نمونه Queue را در داخل ایجاد می کند)، بنابراین به همان روش تغییر کرده است.
جعبه کار - انقضا
بسته npm به workbox-expiration تغییر نام داده است که با قرارداد نامگذاری مورد استفاده برای سایر ماژول ها مطابقت دارد. این بسته از نظر عملکردی معادل بسته قدیمی workbox-cache-expiration است که اکنون منسوخ شده است.
جعبه کاری-پخش-به روز رسانی
بسته npm به workbox-broadcast-update تغییر نام داده است که با قرارداد نامگذاری مورد استفاده برای سایر ماژول ها مطابقت دارد. این بسته از نظر عملکردی معادل بسته قدیمی workbox-broadcast-cache-update است که اکنون منسوخ شده است.
جعبه کار
در Workbox v3، پرحرفی سطوح گزارش را می‌توان از طریق متد workbox.core.setLogLevel() کنترل کرد، که یکی از مقادیر را در workbox.core.LOG_LEVELS enum ارسال می‌کنید. همچنین می توانید سطح گزارش فعلی را از طریق workbox.core.logLevel بخوانید.
در Workbox v4، همه این‌ها حذف شده‌اند، زیرا همه ابزارهای توسعه‌دهنده مدرن اکنون با قابلیت‌های فیلتر کردن گزارش غنی عرضه می‌شوند (به فیلتر کردن خروجی کنسول برای ابزارهای توسعه‌دهنده Chrome مراجعه کنید).
جعبه کار-sw
دو روشی که قبلاً مستقیماً در فضای نام workbox (که با ماژول workbox-sw مطابقت دارد) در معرض دید قرار گرفته بودند به جای آن به workbox.core منتقل شدند. workbox.skipWaiting() تبدیل به workbox.core.skipWaiting() و به طور مشابه workbox.clientsClaim() تبدیل به workbox.core.clientsClaim() شد.
پیکربندی ابزار ساخت
نام برخی از گزینه هایی که می توانند به workbox-cli، workbox-build یا workbox-webpack-plugin منتقل شوند، تغییر کرده است. هر زمان که "URL" در نام یک گزینه استفاده شد، به نفع "URL" منسوخ شده است. این بدان معنی است که نام گزینه های زیر ترجیح داده می شود:
-
dontCacheBustURLsMatching -
ignoreURLParametersMatching -
modifyURLPrefix -
templatedURLs
تغییر "Url" نام این گزینه ها هنوز در نسخه 4 کار می کند، اما منجر به یک پیام هشدار می شود. ما توسعه دهندگان را تشویق می کنیم که قبل از انتشار نسخه 5 مهاجرت کنند.
عملکرد جدید
جعبه کار-پنجره
ماژول جدید workbox-window فرآیند ثبت نام و شناسایی به‌روزرسانی‌ها را ساده می‌کند و یک وسیله ارتباطی استاندارد بین کدهای در حال اجرا در سرویس‌کار و کدهای در حال اجرا در زمینه window برنامه وب شما فراهم می‌کند.
در حالی که استفاده از workbox-window اختیاری است، امیدواریم توسعه‌دهندگان آن را مفید بدانند و برخی از منطق دست‌نویس خود را برای استفاده از آن در صورت لزوم مهاجرت کنند. در راهنمای ماژول می‌توانید درباره استفاده از workbox-window اطلاعات بیشتری کسب کنید.
نمونه مهاجرت
نمونه ای از مهاجرت در دنیای واقعی از Workbox v3 به v4 را می توان در این درخواست کشش یافت.
کمک گرفتن
ما پیش‌بینی می‌کنیم که بیشتر مهاجرت‌ها ساده باشد. اگر با مشکلاتی مواجه شدید که در این راهنما پوشش داده نشده است، لطفاً با باز کردن مشکلی در GitHub به ما اطلاع دهید.