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

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

التغييرات التي قد تؤدي إلى أعطال

التحضير المسبق لصندوق العمل

تم تعديل اصطلاح التسمية للإدخالات المخزّنة مسبقًا. بالنسبة إلى الإدخالات التي تحتاج عناوين URL الخاصة بها إلى معلومات عن المراجعة (أي الإدخالات التي تحتوي على حقل revision في بيان التخزين المؤقت المُسبَق)، سيتم تخزين معلومات الإصدار هذه كجزء من مفتاح ذاكرة التخزين المؤقت، في مَعلمة طلب بحث خاصة لعنوان URL‏ __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.precaching.cleanupOutdatedCaches() إلى أحد موظّفي الخدمة مباشرةً، أو ضبط خيار cleanupOutdatedCaches: true الجديد في حال استخدام أداة إنشاء في وضع GenerateSW. بما أنّ منطق تنظيف ذاكرة التخزين المؤقت يعمل على اتّباع اصطلاحات تسمية ذاكرة التخزين المؤقت للعثور على ذاكرات التخزين المؤقت الأقدم، وبما أنّ المطوّرين لديهم خيار إلغاء هذه الاصطلاحات، اخترنا اتّباع نهج الأمان ولم نفعّل هذه الميزة تلقائيًا.

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

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

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

workbox-strategies

هناك طريقتان متكافئتان تقريبًا لإنشاء مثيل لمعالج في 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-background-sync

تمت إعادة كتابة فئة workbox.backgroundSync.Queue لمنح المطوّرين مزيدًا من المرونة والتحكّم في كيفية إضافة الطلبات إلى "قائمة الانتظار" وإعادة تشغيلها.

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

workbox-broadcast-update

تمت إعادة تسمية الحزمة npm إلى workbox-broadcast-update، بما يتوافق مع اصطلاح التسمية المستخدَم في الوحدات الأخرى. هذه الحزمة مكافئة وظيفيًا لحزمة workbox-broadcast-cache-update القديمة التي تم إيقافها نهائيًا.

workbox-core

في الإصدار 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-plugin. عند استخدام "Url" في اسم خيار، تم إيقافه نهائيًا واستبداله بـ "URL". ويعني ذلك أنّ أسماء الخيارات التالية مفضّلة:

• dontCacheBustURLsMatching
• ignoreURLParametersMatching
• modifyURLPrefix
• templatedURLs

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

وظائف جديدة

workbox-window

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

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

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

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

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

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