نقل البيانات من الإصدار 5 إلى الإصدار 6 من Workbox

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

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

نواة إطار العمل

لن تُضاف الطريقة skipWaiting() في workbox-core إلى معالج install بعد الآن، وتعادل هذه الطريقة استدعاء self.skipWaiting() فقط.

من الآن فصاعدًا، يمكنك استخدام self.skipWaiting() بدلاً من ذلك، لأنّه من المحتمل إزالة skipWaiting() في الإصدار 7 من Workbox.

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

• لم يعُد من الممكن استخدام مستندات HTML من مصادر متعددة لعناوين URL التي تتوافق مع إعادة توجيه HTTP لاستيفاء طلب التنقّل باستخدام workbox-precaching. هذا السيناريو غير شائع بشكل عام.
• يتجاهل workbox-precaching الآن مَعلمة طلب البحث لعنوان URL fbclid عند البحث عن استجابة مخزَّنة مؤقتًا لطلب معيّن.
• تستخدم الدالة الإنشائية PrecacheController الآن كائنًا بخصائص معينة كمَعلمة، بدلاً من سلسلة. يتوافق هذا الكائن مع الخصائص التالية: cacheName (تخدم الغرض نفسه كسلسلة تم تمريرها إلى الدالة الإنشائية في الإصدار 5) وplugins (مع استبدال الطريقة addPlugins() من الإصدار 5) و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 v10 أو إصدار أعلى

لم تعُد إصدارات Node.js السابقة للإصدار 10 متوافقة مع workbox-webpack-plugin أو workbox-build أو workbox-cli. إذا كنت تستخدم إصدارًا من Node.js أقدم من الإصدار 8، يجب تحديث وقت التشغيل إلى إصدار متوافق.

التحسينات الجديدة

استراتيجيات-صندوق العمل

يقدّم الإصدار 6 من Workbox طريقة جديدة لمطوّري برامج الجهات الخارجية لتحديد استراتيجياتهم الخاصة في Workbox. ويضمن هذا الأمر أن مطوّري برامج الجهات الخارجية يمكنهم توسيع Workbox بطرق تلبي احتياجاتهم بشكل كامل.

فئة أساسية جديدة للاستراتيجيات

في الإصدار 6، يجب على جميع فئات استراتيجيات Workbox تمديد الفئة الأساسية الجديدة Strategy. وقد تمت إعادة كتابة جميع الاستراتيجيات المضمنة لتعزيز هذا الأمر.

تكون الفئة الأساسية Strategy مسؤولة عن أمرَين أساسيَين:

• استدعاء استدعاءات دورة حياة المكونات الإضافية الشائعة لكل معالِجات الاستراتيجية (على سبيل المثال، عند بدئها والرد وانتهائها).
• إنشاء مثيل "معالج" يمكنه إدارة حالة كل طلب فردي تعالجه الاستراتيجية.

فئة "المعالج" الجديدة

كانت لدينا في السابق وحدات داخلية تُسمى fetchWrapper وcacheWrapper، واللذين (كما يوحي اسمهما) يشملان واجهات برمجة تطبيقات للجلب والتخزين المؤقت المختلفة مع تضمين عناصر الجذب في مراحل نشاطها. هذه هي الآلية التي تسمح حاليًا للمكونات الإضافية بالعمل، ولكنها لا تظهر للمطورين.

ستعرض فئة "المعالج" الجديدة، StrategyHandler، هذه الطرق بحيث يمكن للاستراتيجيات المخصّصة استدعاء fetch() أو cacheMatch() والحصول على أي مكوّنات إضافية تمت إضافتها إلى مثيل الاستراتيجية تلقائيًا.

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

حالة دورة حياة المكوّن الإضافي الجديدة

في الإصدار 5 من Workbox، لا يتم إيقاف حالة المكوّنات الإضافية. وهذا يعني أنّه إذا أدى طلب استرداد البيانات إلى /index.html إلى ظهور كلّ من عمليتَي معاودة الاتصال requestWillFetch وcachedResponseWillBeUsed، لن يكون من الممكن لرد الاتصال هاتين الطريقتين التواصل مع بعضهما أو حتى معرفة أنّه تم تشغيلهما من خلال الطلب نفسه.

في الإصدار 6، يتم أيضًا تمرير جميع استدعاءات المكونات الإضافية مع كائن state جديد. سيكون كائن الحالة هذا فريدًا لكائن المكوِّن الإضافي المحدد هذا واستدعاء الإستراتيجية المحدد هذا (أي الاتصال بـ handle()). يتيح ذلك للمطورين كتابة مكونات إضافية حيث يمكن لرد اتصال واحد تنفيذ إجراء بشكل مشروط بناءً على ما فعله استدعاء آخر في المكوِّن الإضافي نفسه (على سبيل المثال، حساب دلتا الوقت بين تشغيل requestWillFetch وfetchDidSucceed أو fetchDidFail).

عمليات معاودة الاتصال خلال مراحل نشاط المكوّن الإضافي الجديد

تمّت إضافة استدعاءات مراحل نشاط المكوّن الإضافي الجديدة للسماح للمطوّرين بالاستفادة الكاملة من حالة دورة حياة المكوّن الإضافي:

• handlerWillStart: يتم طلب الإجراء قبل بدء تشغيل أي منطق للمعالج. يمكن استخدام معاودة الاتصال هذه لضبط حالة المعالج الأولية (مثل تسجيل وقت البدء).
• handlerWillRespond: يتم استدعاءها قبل عرض طريقة handle() للاستجابة. يمكن استخدام معاودة الاتصال هذه لتعديل هذه الاستجابة قبل إعادتها إلى معالج مسار أو أي منطق مخصَّص آخر.
• handlerDidRespond: يتم طلبها بعد أن تعرض طريقة handle() للاستراتيجية استجابة. يمكن استخدام معاودة الاتصال هذه لتسجيل أي تفاصيل للاستجابة النهائية، على سبيل المثال بعد التغييرات التي أجرتها المكوّنات الإضافية الأخرى.
• handlerDidComplete: يتم طلب هذه الخطوة بعد تسوية كل الوعود الدائمة التي تمت إضافتها إلى الحدث بعد تنفيذ هذه الاستراتيجية. ويمكن استخدام معاودة الاتصال هذه لإعداد تقارير عن أي بيانات تحتاج إلى الانتظار حتى يتم الانتهاء من المعالج من أجل إجراء الحسابات (على سبيل المثال، حالة نتيجة ذاكرة التخزين المؤقت، ووقت استجابة ذاكرة التخزين المؤقت، ووقت استجابة الشبكة).
• handlerDidError: يتم استدعاءها إذا لم يتمكن المعالج من تقديم استجابة صالحة من أي مصدر. يمكن استخدام معاودة الاتصال هذه لتوفير محتوى "احتياطي" كبديل لخطأ في الشبكة.

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

أنواع TypeScript أكثر دقة للمعالجات

تم تسوية تعريفات TypeScript لطرق معاودة الاتصال المختلفة. ومن المفترض أن يؤدي ذلك إلى تقديم تجربة أفضل للمطوّرين الذين يستخدمون TypeScript ويكتبون شفرتهم الخاصة لتنفيذ المعالجات أو استدعاءها.

نافذة إطار العمل

الإجراء الجديد MessageSkipwaiting()

تمت إضافة طريقة جديدة، وهي messageSkipWaiting()، إلى الوحدة التنظيمية workbox-window لتبسيط عملية الطلب من عامل الخدمة"الانتظار" تفعيله. ويوفّر ذلك بعض التحسينات:

• يستدعي الأمر postMessage() مع نص الرسالة العادي الفعلي، {type: 'SKIP_WAITING'}، الذي يبحث عنه عامل الخدمات الذي أنشأه Workbox لتشغيل skipWaiting().
• يختار مشغّل الخدمات الصحيح "الانتظار" لنشر هذه الرسالة عليه، حتى إذا لم يكن هو مشغّل الخدمات نفسه الذي تم تسجيل workbox-window لديه.

إزالة الأحداث "الخارجية" لصالح موقع إلكتروني خارجي

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

وصفة للمنظّف "عرض إعادة تحميل الصفحة للمستخدمين"

بفضل كلا التغييرين السابقين، يمكن تبسيط وصفة "عرض إعادة تحميل الصفحة للمستخدمين":

MULTI_LINE_CODE_PLACEHOLDER_0

توجيه صندوق العمل

يتم تمرير معلَمة منطقية جديدة، sameOrigin، إلى الدالة matchCallback المستخدَمة في workbox-routing. يتم ضبطها على true إذا كان الطلب متعلّقًا بعنوان URL من المصدر نفسه، وتكون القيمة false في الحالات الأخرى.

وهذا من شأنه تبسيط بعض النصوص النموذجية الشائعة:

MULTI_LINE_CODE_PLACEHOLDER_1

خيارات التطابق في إطار العمل-انتهاء صلاحية مربع العمل

يمكنك الآن ضبط matchOptions في workbox-expiration، والتي سيتم تمريرها بعد ذلك بصفتها CacheQueryOptions إلى مكالمة cache.delete() الأساسية. (لن يحتاج معظم مطوّري البرامج إلى إجراء ذلك).

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

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

تمت إعادة كتابة workbox-precaching لاستخدام workbox-strategies كقاعدة. ومن المفترض ألا يؤدي ذلك إلى حدوث أي تغييرات قد تؤدي إلى أعطال، ويجب أن يؤدي إلى الاتساق على المدى الطويل في كيفية وصول الوحدتين إلى الشبكة وذاكرة التخزين المؤقت.

إنّ عملية التخزين المؤقت تُعالج الآن الإدخالات واحدًا تلو الآخر، وليس بشكل مجمّع.

تم تحديث workbox-precaching بحيث لا يتم طلب أكثر من إدخال واحد في بيان التخزين المؤقت المسبق ويتم تخزينه مؤقتًا في كل مرة، بدلاً من محاولة طلب كل منها وتخزينها مؤقتًا في وقت واحد (تركها إلى المتصفح لمعرفة كيفية تقييدها).

من المفترض أن يحدّ هذا من احتمال حدوث أخطاء net::ERR_INSUFFICIENT_RESOURCES أثناء التخزين المؤقّت، وأن يحدّ أيضًا من تزايد معدل نقل البيانات بين التخزين المؤقّت والطلبات المتزامنة التي يجريها تطبيق الويب.

يتيح لك PrecacheFallbackPlugin إجراء احتياطي أسهل بلا اتصال بالإنترنت

تتضمّن "workbox-precaching" الآن طريقة PrecacheFallbackPlugin التي تنفِّذ طريقة مراحل النشاط "handlerDidError" الجديدة التي تمت إضافتها في الإصدار 6.

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

إليك نموذج لاستخدامه للردّ باستخدام /offline.html مخزن مؤقّتًا مسبقًا عندما يتعذّر على استراتيجية NetworkOnly إنشاء ردّ على طلب تنقّل، أي عرض صفحة HTML مخصّصة بلا اتصال بالإنترنت:

MULTI_LINE_CODE_PLACEHOLDER_2

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.