مهاجرت از Workbox v5 به v6، مهاجرت از Workbox v5 به v6

این راهنما بر شکستن تغییرات ارائه شده در Workbox v6 متمرکز شده است، با نمونه هایی از تغییراتی که باید هنگام ارتقاء از Workbox v5 ایجاد کنید.

شکستن تغییرات

جعبه کار

متد skipWaiting() در workbox-core دیگر به یک کنترل کننده install اضافه نمی‌کند و معادل فراخوانی self.skipWaiting() است.

از این پس، به جای آن از self.skipWaiting() استفاده کنید زیرا skipWaiting() احتمالاً در Workbox v7 حذف خواهد شد.

جعبه کار-پیش کش

• اسناد HTML متقاطع برای نشانی‌های اینترنتی که با تغییر مسیر HTTP مطابقت دارند، دیگر نمی‌توانند برای برآورده کردن درخواست پیمایش با workbox-precaching استفاده شوند. این سناریو به طور کلی غیر معمول است.
• پارامتر query URL fbclid اکنون توسط workbox-precaching هنگام جستجوی یک پاسخ از پیش ذخیره‌شده برای یک درخواست معین نادیده گرفته می‌شود.
• سازنده PrecacheController اکنون به جای یک رشته، یک شی با ویژگی های خاص را به عنوان پارامتر خود می گیرد. این شی از ویژگی های زیر پشتیبانی می کند: cacheName (همان هدف رشته ای که در v5 به سازنده داده شده است)، plugins (جایگزین متد addPlugins() از v5) و fallbackToNetwork (جایگزینی گزینه مشابهی است که به آن ارسال شده است. createHandler() و `createHandlerBoundToURL() در نسخه 5).
• متدهای install() و activate() PrecacheController اکنون دقیقاً یک پارامتر دارند که باید به ترتیب روی InstallEvent یا ActivateEvent مربوطه تنظیم شود.
• متد addRoute() از PrecacheController حذف شده است. در جای خود، کلاس جدید PrecacheRoute می تواند برای ایجاد مسیری استفاده شود که سپس می توانید آن را ثبت کنید.
• متد precacheAndRoute() از PrecacheController حذف شده است. (این روش هنوز به عنوان یک روش کمکی ثابت صادر شده توسط ماژول workbox-precaching وجود دارد.) به دلیل اینکه می توان از PrecacheRoute به جای آن استفاده کرد، حذف شد.
• متد createMatchCalback() از PrecacheController حذف شده است. به جای آن می توان از PrecacheRoute جدید استفاده کرد.
• متد createHandler() از PrecacheController حذف شده است. ویژگی strategy شی PrecacheController می تواند به جای آن برای رسیدگی به درخواست ها استفاده شود.
• صادرات استاتیک createHandler() قبلاً از ماژول workbox-precaching حذف شده است. به جای آن، توسعه دهندگان باید یک نمونه PrecacheController بسازند و از ویژگی strategy آن استفاده کنند.
• مسیر ثبت شده با precacheAndRoute() اکنون یک مسیر واقعی است که از کلاس Router workbox-routing در زیر هود استفاده می کند. اگر تماس‌ها را با registerRoute() و precacheAndRoute() بیندازید، ممکن است به ترتیب ارزیابی متفاوت مسیرهای شما منجر شود.

مسیریابی جعبه کاری

متد setDefaultHandler() اکنون یک پارامتر دوم اختیاری را مطابق با روش HTTP که روی آن اعمال می‌شود، دریافت می‌کند و به‌طور پیش‌فرض 'GET' است.

• اگر از setDefaultHandler() استفاده می‌کنید و تمام درخواست‌های شما GET هستند، نیازی به تغییر نیست.
• اگر درخواست‌هایی دارید که GET نیستند ( POST ، PUT ، و غیره...)، setDefaultHandler() دیگر باعث تطبیق آن درخواست‌ها نمی‌شود.

پیکربندی ساخت

گزینه mode برای حالت‌های getManifest و injectManifest در workbox-build و workbox-cli قرار نبود پشتیبانی شود و حذف شده است. این برای workbox-webpack-plugin صدق نمی کند، که mode در افزونه InjectManifest خود پشتیبانی می کند.

ابزارهای ساخت به Node.js نسخه 10 یا بالاتر نیاز دارند

نسخه‌های Node.js قبل از نسخه ۱۰ دیگر برای workbox-webpack-plugin ، workbox-build یا workbox-cli پشتیبانی نمی‌شوند. اگر نسخه‌ای از Node.js را زودتر از نسخه ۸ اجرا می‌کنید، زمان اجرا خود را به نسخه پشتیبانی‌شده به‌روزرسانی کنید.

بهبودهای جدید

جعبه کار - استراتژی ها

Workbox v6 روش جدیدی را برای توسعه دهندگان شخص ثالث معرفی می کند تا استراتژی های Workbox خود را تعریف کنند. این تضمین می‌کند که توسعه‌دهندگان شخص ثالث توانایی گسترش Workbox را به روش‌هایی دارند که به طور کامل نیازهای آنها را برآورده کند.

کلاس پایه استراتژی جدید

در نسخه 6، تمام کلاس های استراتژی Workbox باید کلاس پایه Strategy جدید را گسترش دهند. همه استراتژی های داخلی برای پشتیبانی از این بازنویسی شده اند.

کلاس پایه Strategy مسئول دو چیز اصلی است:

• فراخوانی فراخوانی چرخه عمر افزونه مشترک برای همه گردانندگان استراتژی (مثلاً زمانی که شروع می شوند، پاسخ می دهند و پایان می یابند).
• ایجاد یک نمونه "هندلر" که می تواند وضعیت را برای هر درخواست فردی که یک استراتژی مدیریت می کند، مدیریت کند.

کلاس "هندلر" جدید

ما قبلاً ماژول‌های داخلی به نام‌های fetchWrapper و cacheWrapper داشتیم که (همانطور که از نامشان پیداست) API‌های مختلف واکشی و کش را با قلاب‌ها در چرخه عمر خود قرار می‌دهند. این مکانیزمی است که در حال حاضر به پلاگین ها اجازه کار می دهد، اما در معرض توسعه دهندگان نیست.

کلاس جدید «handler»، StrategyHandler ، این روش‌ها را نشان می‌دهد تا استراتژی‌های سفارشی بتوانند fetch() یا cacheMatch() را فراخوانی کنند و هر پلاگینی که به نمونه استراتژی اضافه شده است به طور خودکار فراخوانی شود.

این کلاس همچنین به توسعه‌دهندگان امکان می‌دهد تا تماس‌های سفارشی و چرخه عمر خود را که ممکن است مختص استراتژی‌هایشان باشد، اضافه کنند و آنها فقط با رابط پلاگین موجود «کار کنند».

وضعیت چرخه عمر افزونه جدید

در Workbox v5، افزونه ها بدون حالت هستند. این بدان معناست که اگر درخواستی برای /index.html هر دو تماس‌های requestWillFetch و cachedResponseWillBeUsed را راه‌اندازی کند، این دو callback هیچ راهی برای برقراری ارتباط با یکدیگر یا حتی دانستن اینکه توسط یک درخواست راه‌اندازی شده‌اند ندارند.

در نسخه 6، تمام فراخوان‌های پلاگین نیز یک شی state جدید ارسال می‌شوند. این شیء حالت برای این شیء پلاگین خاص و این فراخوانی استراتژی خاص (یعنی فراخوانی برای handle() ) منحصر به فرد خواهد بود. این به توسعه‌دهندگان اجازه می‌دهد تا پلاگین‌هایی بنویسند که در آن یک callback می‌تواند به‌صورت مشروط کاری را بر اساس آنچه پاسخ تماس دیگری در همان افزونه انجام داده است انجام دهد (مثلاً زمان دلتای بین اجرای requestWillFetch و fetchDidSucceed یا fetchDidFail را محاسبه کند).

تماس‌های چرخه حیات افزونه جدید

تماس‌های چرخه حیات افزونه جدید اضافه شده‌اند تا به توسعه‌دهندگان اجازه دهد تا از وضعیت چرخه عمر افزونه به طور کامل استفاده کنند:

• handlerWillStart : قبل از شروع هر منطق کنترل کننده، فراخوانی می شود. از این تماس برگشتی می توان برای تنظیم وضعیت کنترل کننده اولیه (مثلاً ضبط زمان شروع) استفاده کرد.
• handlerWillRespond : قبل از اینکه متد استراتژی ها handle() یک پاسخ را برگرداند فراخوانی می شود. این پاسخ تماس را می توان برای اصلاح آن پاسخ قبل از بازگرداندن آن به یک هدایت کننده مسیر یا دیگر منطق سفارشی استفاده کرد.
• handlerDidRespond : پس از اینکه متد handle() استراتژی پاسخی را برمی گرداند فراخوانی می شود. از این تماس برگشتی می توان برای ضبط هرگونه جزئیات پاسخ نهایی استفاده کرد، به عنوان مثال پس از تغییرات ایجاد شده توسط پلاگین های دیگر.
• handlerDidComplete : فراخوانی شده بعد از همه افزایش طول عمر وعده های اضافه شده به رویداد از فراخوانی این استراتژی حل و فصل شده است. از این تماس برگشتی می توان برای گزارش در مورد هر داده ای استفاده کرد که باید منتظر بمانید تا کنترل کننده برای محاسبه انجام شود (مثلاً وضعیت ضربه حافظه پنهان، تأخیر حافظه پنهان، تأخیر شبکه).
• handlerDidError : اگر کنترل کننده قادر به ارائه پاسخ معتبر از هر منبعی نباشد، فراخوانی می شود. از این تماس برگشتی می توان برای ارائه محتوای «بازگشت» به عنوان جایگزینی برای خطای شبکه استفاده کرد.

توسعه‌دهندگانی که استراتژی‌های سفارشی خود را پیاده‌سازی می‌کنند، لازم نیست نگران فراخوانی این تماس‌ها باشند. همه اینها توسط یک کلاس پایه Strategy جدید اداره می شود.

انواع TypeScript دقیق تر برای کنترل کننده ها

تعاریف تایپ اسکریپت برای روش های مختلف پاسخ به تماس عادی شده است. این باید منجر به تجربه بهتری برای توسعه دهندگانی شود که از TypeScript استفاده می کنند و کد خود را برای پیاده سازی یا فراخوانی کنترل کننده ها می نویسند.

جعبه کار-پنجره

متد جدید messageSkipWaiting().

یک روش جدید messageSkipWaiting() به ماژول workbox-window اضافه شده است تا فرآیند گفتن فعال کردن سرویس‌کار «در انتظار» را ساده‌تر کند. این بهبودهایی را ارائه می دهد:

• این postMessage() با بدنه پیام استاندارد، {type: 'SKIP_WAITING'} فراخوانی می‌کند، که یک سرویس‌گر تولید شده توسط Workbox آن را برای راه‌اندازی skipWaiting() بررسی می‌کند.
• سرویس‌کار «در انتظار» صحیح را برای ارسال این پیام انتخاب می‌کند، حتی اگر همان سرویس‌دهنده‌ای نباشد که workbox-window با آن ثبت شده است.

حذف رویدادهای "خارجی" به نفع یک ویژگی isExternal

همه رویدادهای "خارجی" در workbox-window به جای رویدادهای "عادی" با ویژگی isExternal که روی true تنظیم شده است حذف شده اند. این به توسعه دهندگانی که به تمایز اهمیت می دهند اجازه می دهد تا همچنان آن را شناسایی کنند و توسعه دهندگانی که نیازی به دانستن ندارند می توانند ویژگی را نادیده بگیرند.

دستور العمل پاک کننده "پیشنهاد بارگذاری مجدد صفحه برای کاربران".

به لطف هر دو تغییر فوق، دستور العمل "پیشنهاد بارگذاری مجدد صفحه برای کاربران" را می توان ساده کرد:

// v6:
<script type="module">
  import {Workbox} from 'https://storage.googleapis.com/workbox-cdn/releases/6.0.0-alpha.1/workbox-window.prod.mjs';

  if ('serviceWorker' in navigator) {
    const wb = new Workbox('/sw.js');

    const showSkipWaitingPrompt = () => {
      // This assumes a hypothetical createUIPrompt() method with
      // onAccept and onReject callbacks:
      const prompt = createUIPrompt({
        onAccept: () => {
          wb.addEventListener('controlling', () => {
            window.location.reload();
          });

          // This will postMessage() to the waiting service worker.
          wb.messageSkipWaiting();
        },

        onReject: () => {
          prompt.dismiss();
        },
      });
    };

    // Listening for externalwaiting is no longer needed.
    wb.addEventListener('waiting', showSkipWaitingPrompt);
    wb.register();
  }
</script>

مسیریابی جعبه کار

یک پارامتر بولی جدید، sameOrigin ، به تابع matchCallback مورد استفاده در workbox-routing ارسال می شود. اگر درخواست برای یک URL با مبدأ یکسان باشد، روی true و در غیر این صورت false تنظیم می شود.

این کار برخی از دیگ های بخار رایج را ساده می کند:

// In v5:
registerRoute(
  ({url}) =>
    url.origin === self.location.origin && url.pathname.endsWith('.png'),
  new StaleWhileRevalidate({cacheName: 'local-png'})
);

// In v6:
registerRoute(
  ({sameOrigin, url}) => sameOrigin && url.pathname.endsWith('.png'),
  new StaleWhileRevalidate({cacheName: 'local-png'})
);

matchOptions در جعبه کاری-انقضا

اکنون می‌توانید matchOptions در workbox-expiration تنظیم کنید، که سپس به‌عنوان CacheQueryOptions به فراخوانی cache.delete() زیر ارسال می‌شود. (بیشتر توسعه دهندگان نیازی به انجام این کار ندارند.)

جعبه کار-پیش کش

از workbox-strategies استفاده می کند

workbox-precaching برای استفاده از workbox-strategies به عنوان پایه بازنویسی شده است. این نباید منجر به تغییرات قطعی شود و باید منجر به سازگاری طولانی مدت بهتری در نحوه دسترسی دو ماژول به شبکه و حافظه پنهان شود.

Precaching now ورودی ها را یک به یک پردازش می کند، نه به صورت انبوه

workbox-precaching به‌روزرسانی شده است، به‌طوری‌که تنها یک ورودی در مانیفست پیش کش درخواست می‌شود و در آن واحد ذخیره می‌شود، به‌جای تلاش برای درخواست و ذخیره همه آن‌ها به‌صورت هم‌زمان (به مرورگر واگذار می‌کنیم تا نحوه دریچه گاز را بفهمد).

این باید احتمال خطاهای net::ERR_INSUFFICIENT_RESOURCES را در حین پیش کش کاهش دهد و همچنین باید اختلاف پهنای باند بین پیش کش و درخواست های همزمان ارائه شده توسط برنامه وب را کاهش دهد.

PrecacheFallbackPlugin امکان بازگشت آسانتر به حالت آفلاین را فراهم می کند

workbox-precaching اکنون شامل یک PrecacheFallbackPlugin است که متد جدید چرخه حیات handlerDidError اضافه شده در نسخه 6 را پیاده سازی می کند.

این امر تعیین یک URL از پیش کش شده را به عنوان یک "بازگشت" برای یک استراتژی مشخص می کند، در صورتی که در غیر این صورت پاسخی در دسترس نبود. این افزونه از ساخت صحیح کلید حافظه پنهان برای URL از پیش ذخیره شده، از جمله هر پارامتر ویرایشی که لازم است، مراقبت می کند.

در اینجا نمونه ای از استفاده از آن برای پاسخ دادن با یک /offline.html از پیش کش شده است، زمانی که استراتژی NetworkOnly نمی تواند پاسخی برای درخواست ناوبری ایجاد کند - به عبارت دیگر، نمایش یک صفحه HTML آفلاین سفارشی:

import {PrecacheFallbackPlugin, precacheAndRoute} from 'workbox-precaching';
import {registerRoute} from 'workbox-routing';
import {NetworkOnly} from 'workbox-strategies';

// Ensure that /offline.html is part of your precache manifest!
precacheAndRoute(self.__WB_MANIFEST);

registerRoute(
  ({request}) => request.mode === 'navigate',
  new NetworkOnly({
    plugins: [
      new PrecacheFallbackPlugin({
        fallbackURL: '/offline.html',
      }),
    ],
  })
);

precacheFallback در کش در زمان اجرا

اگر از generateSW استفاده می‌کنید تا به‌جای نوشتن دستی سرویس‌گر برای شما یک سرویس‌کار ایجاد کند، می‌توانید از گزینه پیکربندی جدید precacheFallback در runtimeCaching برای انجام همین کار استفاده کنید:

{
  // ... other generateSW config options...
  runtimeCaching: [{
    urlPattern: ({request}) => request.mode === 'navigate',
    handler: 'NetworkOnly',
    options: {
      precacheFallback: {
        // This URL needs to be included in your precache manifest.
        fallbackURL: '/offline.html',
      },
    },
  }],
}

دریافت کمک

ما پیش‌بینی می‌کنیم که بیشتر مهاجرت‌ها ساده باشد. اگر با مشکلاتی مواجه شدید که در این راهنما پوشش داده نشده است، لطفاً با باز کردن مشکلی در GitHub به ما اطلاع دهید.