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

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

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

workbox-core

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

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

workbox-precaching

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

workbox-routing

تتطلّب طريقة setDefaultHandler() الآن مَعلمة ثانية اختيارية تتوافق مع طريقة HTTP التي تنطبق عليها، وتكون القيمة التلقائية هي 'GET'.

• إذا كنت تستخدم setDefaultHandler() وكانت جميع طلباتك GET، ليس عليك إجراء أي تغييرات.
• إذا كان لديك أي طلبات غير GET (POST أو PUT أو غير ذلك)، لن يؤدي "setDefaultHandler()" إلى مطابقة هذه الطلبات بعد الآن.

إعدادات التصميم

لم يكن من المفترض أن يتوفّر خيار mode لوضعَي getManifest وinjectManifest في workbox-build وworkbox-cli، وقد تمت إزالته. لا ينطبق ذلك على workbox-webpack-plugin، الذي يتيح استخدام mode في المكوّن الإضافي InjectManifest.

تتطلّب أدوات الإنشاء الإصدار 10 من Node.js أو إصدارًا أحدث

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

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

workbox-strategies

يقدّم Workbox v6 طريقة جديدة لمطوّري البرامج التابعين لجهات خارجية لتحديد استراتيجيات 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 ويكتبون الرموز البرمجية الخاصة بهم لتنفيذ المعالِجات أو استدعائها.

workbox-window

طريقة messageSkipWaiting() الجديدة

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

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

إزالة الأحداث "الخارجية" لصالح السمة isExternal

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

وصفة Cleaner "Offer a page reload for users"

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

// 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>

workbox-routing

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

يؤدي ذلك إلى تبسيط بعض الرموز النموذجية الشائعة:

// 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 في workbox-expiration

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

workbox-precaching

يستخدم استراتيجيات workbox

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

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

تم تعديل 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.