نقل البيانات من الإصدار 3 إلى الإصدار 4 من Workspace

يركّز هذا الدليل على تغيير التغييرات التي تم إجراؤها في الإصدار 4 من Workbox، مع أمثلة على التغييرات التي يجب إجراؤها عند الترقية من الإصدار 3 من Workbox.

قد يؤدي إلى عطل

الإعداد المسبق لصندوق العمل

تم تعديل اصطلاح تسمية الإدخالات المخزّنة مؤقتًا. وبالنسبة إلى الإدخالات التي تحتاج عناوين URL الخاصة بها إلى معلومات لمراجعة (أي الإدخالات التي تحتوي على حقل revision في بيان التخزين المؤقت)، سيتم تخزين معلومات تحديد الإصدارات كجزء من مفتاح ذاكرة التخزين المؤقت، في معلَمة طلب بحث خاصة بعنوان __WB_REVISION__ يتم إلحاقها بعنوان URL الأصلي. (في السابق، كانت هذه المعلومات تُخزن بشكل منفصل عن مفاتيح ذاكرة التخزين المؤقت باستخدام IndexedDB).

ولا يحتاج المطوّرون الذين يستفيدون من ميزة التخزين المؤقت من خلال workbox.precaching.precacheAndRoute()، وهي حالة الاستخدام الأكثر شيوعًا، إلى إجراء أي تغييرات على إعدادات مشغّل الخدمات، فعند الترقية إلى الإصدار 4 من Workbox، سيتم تلقائيًا نقل مواد العرض المخزّنة مؤقتًا للمستخدمين إلى التنسيق الجديد لمفتاح ذاكرة التخزين المؤقت. ومن الآن فصاعدًا، سيستمر عرض الموارد المخزّنة مؤقتًا بالطريقة نفسها كما في السابق.

استخدام مفاتيح ذاكرة التخزين المؤقت مباشرةً

قد يحتاج بعض المطوّرين إلى الوصول مباشرةً إلى إدخالات ميزة "التخزين المؤقت للصفحات" مباشرةً خارج سياق workbox.precaching.precacheAndRoute(). على سبيل المثال، قد يتم تخزين صورة بشكل مسبق باستخدامها في نهاية المطاف كاستجابة "احتياطية" عندما يتعذر جلب صورة فعلية من الشبكة.

وفي حال الاستفادة من مواد العرض المخزّنة مؤقتًا بهذه الطريقة، بدءًا من الإصدار 4 من Workbox، عليك اتّخاذ خطوة إضافية لترجمة عنوان 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...
  }
});

تنظيف البيانات القديمة المخزنة مؤقتًا

تعني التغييرات التي تم إجراؤها على ميزة التخزين المؤقت في الإصدار 4 من Workbox أن ذاكرة التخزين المؤقت القديمة التي تم إنشاؤها بواسطة الإصدارات السابقة من Workbox غير متوافقة. يتم تركها كما هي تلقائيًا، وفي حال الترقية من الإصدار 3 من Workbox إلى الإصدار 4 من Workbox، فسينتهي بك الأمر بنسختين من جميع الموارد المخزّنة مؤقتًا مسبقًا.

لتجنُّب حدوث ذلك، يمكنك إضافة عامل دعم إلى الرقم workbox.precaching.cleanupOutdatedCaches() مباشرةً، أو ضبط خيار cleanupOutdatedCaches: true الجديد في حال استخدام أداة إصدار في وضع GenerateSW. ولأنّ منطق تنظيف ذاكرة التخزين المؤقت يعمل على اصطلاحات تسمية ذاكرة التخزين المؤقت للعثور على النسخ المخزَّنة مؤقتًا بشكل مسبق، ولأنّ المطوّرين لديهم خيار إلغاء هذه الاصطلاحات، فقد أخطأنا في وضع الأمان ولم نفعِّل ذلك تلقائيًا.

وننصح المطوِّرين الذين يواجهون أيّ مشاكل في استخدام هذا الأسلوب، مثل ظهور النتائج الإيجابية الكاذبة حول الحذف، بإعلامنا بذلك.

الكتابة بالأحرف الكبيرة للمعلَمات

تمت إعادة تسمية معلَمتين اختياريتين يمكن تمريرهما إلى workbox.precaching.precacheAndRoute() وworkbox.precaching.addRoute()، وذلك لتوحيد اصطلاح الكتابة بالأحرف الكبيرة بشكل عام. أصبح ignoreUrlParametersMatching الآن ignoreURLParametersMatching، وcleanUrls الآن cleanURLs.

استراتيجيات إطار العمل

هناك طريقتان مكافئتان تقريبًا لإنشاء مثيل لمعالج في 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 لمنح المطوّرين المزيد من المرونة والتحكّم في كيفية إضافة الطلبات إلى قائمة الانتظار وإعادة تشغيلها.

في الإصدار الثالث، كانت الفئة Queue طريقة واحدة لإضافة الطلبات إلى قائمة الانتظار (طريقة addRequest())، لكن لم يكن بإمكان الفئة تعديل قائمة الانتظار أو إزالة الطلبات أي طريقة.

في الإصدار 4، تمت إزالة الطريقة addRequests() وإضافة الطرق التالية التي تشبه المصفوفة:

  • pushRequest()
  • popRequest()
  • shiftRequest()
  • unshiftRequest()

في الإصدار الثالث، قبلت الصف 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 القديمة، والتي تم إيقافها نهائيًا.

إطار صندوق العمل

في الإصدار 3 من Workbox، يمكن التحكم في إسهاب مستويات السجل من خلال طريقة workbox.core.setLogLevel()، والتي ستمرر إحدى القيم الموجودة في تعداد workbox.core.LOG_LEVELS. يمكنك أيضًا قراءة مستوى السجلّ الحالي من خلال workbox.core.logLevel.

تمت إزالة جميع هذه الأخطاء في الإصدار 4 من Workbox، حيث إن جميع أدوات المطوّرين الحديثة تأتي الآن مع إمكانيات فلترة السجلات الغنية (يمكنك الاطّلاع على فلترة نتائج وحدة التحكّم الخاصة بـ "أدوات مطوّري البرامج في Chrome").

Workbox-sw

تم نقل طريقتين تم عرضهما مباشرةً في السابق على مساحة الاسم workbox (التي تتوافق مع الوحدة النمطية workbox-sw) إلى workbox.core بدلاً من ذلك. أصبح workbox.skipWaiting() workbox.core.skipWaiting() وكذلك workbox.clientsClaim()، workbox.core.clientsClaim().

إعداد أداة الإنشاء

تم تغيير تسمية بعض الخيارات التي يمكن تمريرها إلى Workbox-cli أو Workbox-build أو workbox-webpack- أين تعمل. كلما تم استخدام "عنوان URL" في اسم خيار، تم إيقافه لصالح "عنوان URL". وهذا يعني أنه من الأفضل استخدام أسماء الخيارات التالية:

  • dontCacheBustURLsMatching
  • ignoreURLParametersMatching
  • modifyURLPrefix
  • templatedURLs

لا تزال صيغة "عنوان URL" لأسماء الخيارات هذه تعمل في الإصدار 4، ولكنها ستؤدي إلى ظهور رسالة تحذير. ونحن نشجّع المطوِّرين على نقل البيانات قبل إطلاق الإصدار 5.

وظائف جديدة

نافذة مربّع العمل

تعمل الوحدة workbox-window الجديدة على تبسيط عملية تسجيل مشغّلي الخدمات واكتشاف التحديثات، كما توفّر وسيلة عادية للتواصل بين الرموز التي يتم تشغيلها في مشغّل الخدمات والرموز التي يتم تشغيلها في سياق window لتطبيق الويب الخاص بك.

وعلى الرغم من أنّ استخدام workbox-window هو أمر اختياري، نأمل أن يستفيد منه المطوّرون، كما نأمل أن يستفيدوا من استخدام بعض الإرشادات المكتوبة بخط اليد عند اللزوم. يمكنك الاطّلاع على مزيد من المعلومات حول استخدام "workbox-window" في دليل الوحدة.

مثال على نقل البيانات

يمكن العثور على مثال لعملية نقل بيانات حقيقية من الإصدار 3 إلى الإصدار 4 من Workbox في طلب السحب هذا.

الحصول على المساعدة

ونتوقّع أن تكون معظم عمليات نقل البيانات مباشرة. إذا واجهت مشاكل غير مذكورة في هذا الدليل، يُرجى إعلامنا بها من خلال فتح مشكلة على GitHub.