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

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

إذا كنت تستخدم حاليًا تركيبة sw-precache/sw-toolbox القديمة وكنت تريد الانتقال إلى Workbox لأول مرة، إليك دليل مختلف حول نقل البيانات سيساعدك في ذلك.

خلفية الإصدار 3

يمثّل الإصدار 3 من Workbox تحديثًا مهمًّا لقاعدة الترميز الحالية. الأهداف الرئيسية هي:

  • تقليل حجم "إطار العمل": تم تقليل مقدار رمز وقت تشغيل مشغّل الخدمات الذي تم تنزيله وتنفيذه. وبدلاً من تمكين الجميع من استخدام حزمة متجانسة، سيتم في وقت التشغيل استيراد رمز الميزات المحددة التي تستخدمها فقط.
  • يحتوي Workspace على شبكة توصيل محتوى (CDN). نوفّر شبكة توصيل محتوى متوافقة بالكامل ومستنِدة إلى Google Cloud Storage كخيار أساسي للوصول إلى مكتبات وقت تشغيل Workbox، ما يسهّل عليك بدء استخدام Workbox.
  • عملية تصحيح أخطاء وسجلات أفضل تم تحسين تجربة تصحيح الأخطاء والتسجيل إلى حد كبير. يتم تفعيل سجلات تصحيح الأخطاء تلقائيًا عندما يتم استخدام Workbox من مصدر localhost وتتم إزالة كل عمليات التسجيل وتأكيدات من إصدارات الإنتاج. مثال على تسجيل تصحيح الأخطاء المقدَّم من الإصدار 3 من Workbox.
  • مكوّن إضافي محسَّن لحزمة الويب. تتكامل workbox-webpack-plugin بشكل وثيق مع عملية إنشاء حزمة الويب، ما يسمح بحالة استخدام بدون ضبط عندما تريد التخزين المؤقت مسبقًا لجميع مواد العرض في مسار الإصدار.

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

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

إعدادات الإصدار

تؤثر التغييرات التالية في سلوك جميع أدوات الإصدار (workbox-build وworkbox-cli وworkbox-webpack-plugin)، التي تشترك في مجموعة شائعة من خيارات الضبط.

  • كان اسم معالج 'fastest' صالحًا في السابق وتم التعامل معه كاسم مستعار للعنصر 'staleWhileRevalidate' عند ضبط runtimeCaching. ولم يعُد الرمز صالحًا، وعلى مطوّري البرامج التبديل إلى استخدام 'staleWhileRevalidate' مباشرةً.
  • تم تعديل العديد من أسماء المواقع الإلكترونية على "runtimeCaching.options"، وأصبحت الإمكانية متاحة للتحقّق من معلَمات إضافية، ما سيؤدي إلى تعذُّر الإصدار في حال استخدام إعدادات غير صالحة. يمكنك الاطّلاع على مستندات runtimeCaching للحصول على قائمة بالخيارات المتاحة حاليًا.

مزامنة الخلفية في مربع العمل

  • يتم الآن تفسير معلمة الإعداد maxRetentionTime على أنها عدد من الدقائق، وليس كعدد من المللي ثانية.
  • هناك الآن سلسلة مطلوبة، تمثل اسم قائمة الانتظار، والتي يجب تمريرها كمعلمة أولى عند إنشاء المكوّن الإضافي أو فئة مستقلة. (سبق أن تم تمريرها كخاصية للخيارات). يمكنك الرجوع إلى المستندات المتعلّقة بالواجهة الجديدة لواجهة برمجة التطبيقات.

workbox-broadcast-cache-update

  • هناك الآن سلسلة مطلوبة، تمثل اسم القناة، والتي يجب تمريرها كمعلمة أولى عند إنشاء المكوّن الإضافي أو فئة مستقلة.

على سبيل المثال، في الإصدار 2، يمكنك تهيئة فئة Plugin على النحو التالي:

new workbox.broadcastCacheUpdate.BroadcastCacheUpdatePlugin({
  channelName: 'cache-updates',
  headersToCheck: ['etag'],
});

الاستخدام المكافئ في الإصدار 3 هو:

new workbox.broadcastUpdate.Plugin('cache-updates', {headersToCheck: ['etag']});

يمكنك الرجوع إلى المستندات المتعلّقة بالواجهة الجديدة لواجهة برمجة التطبيقات.

إطار العمل

  • سيتم الآن إجراء مطابقة نمط glob تلقائيًا باستخدام الخيارات follow: true (التي ستتبع الروابط الرمزية) وstrict: true (وهو أقل تقبلاً للأخطاء "غير المعتادة"). يمكنك إيقاف أي منهما والرجوع إلى السلوك السابق من خلال ضبط globFollow: false و/أو globStrict: false في إعدادات الإصدار.
  • تعرض كل الدوال في workbox-build سمة إضافية، warnings، في الردود التي تعرضها. يُسمح الآن ببعض السيناريوهات التي تم التعامل معها على أنّها أخطاء فادحة في الإصدار 2، ولكن يتم الإبلاغ عنها من خلال warnings، وهي مصفوفة من السلاسل.

في الإصدار 2، يمكنك الاتصال بـ generateSW مثل:

const workboxBuild = require('workbox-build');

workboxBuild.generateSW({...})
  .then(({count, size}) => console.log(`Precached ${count} files, totaling ${size} bytes.`))
  .catch((error) => console.error(`Something went wrong: ${error}`));

ومع أنّه يمكنك استخدام الرمز البرمجي نفسه في الإصدار 3، ننصحك بالتحقق من وجود warnings وتسجيلها:

const workboxBuild = require('workbox-build');

workboxBuild.generateSW({...})
  .then(({count, size, warnings}) => {
    for (const warning of warnings) {
      console.warn(warning);
    }
    console.log(`Precached ${count} files, totalling ${size} bytes.`);
  })
  .catch((error) => console.error(`Something went wrong: ${error}`));
  • على المطوّرين الذين كتبوا دوال ManifestTransform المخصّصة في الإصدار 2 عرض صفيف البيان في كائن (مثلاً، يجب استخدام return {manifest: manifestArray}; بدلاً من return manifestArray;). سيسمح هذا للمكوّن الإضافي بتضمين سمة warnings اختيارية، والتي يجب أن تكون مصفوفة من سلاسل تحتوي على معلومات تحذير غير فادحة.

إذا كنت تكتب ManifestTransform مخصّصًا في الإصدار 2، عليك استخدام رمز مثل:

const cdnTransform = manifestEntries => {
  return manifestEntries.map(entry => {
    const cdnOrigin = 'https://example.com';
    if (entry.url.startsWith('/assets/')) {
      entry.url = cdnOrigin + entry.url;
    }
    return entry;
  });
};

على نسخة v3 المكافئة لـ:

const cdnTransform = manifestEntries => {
  const manifest = manifestEntries.map(entry => {
    const cdnOrigin = 'https://example.com';
    if (entry.url.startsWith('/assets/')) {
      entry.url = cdnOrigin + entry.url;
    }
    return entry;
  });
  return {manifest, warnings: []};
};
  • تمّت إعادة تسمية الدالة getFileManifestEntries() لتصبح getManifest()، ويعرض الوعد الآن معلومات إضافية حول عناوين URL المخزّنة مؤقتًا.

التعليمة البرمجية على النحو التالي في الإصدار 2:

const manifestEntries = await workboxBuild.getFileManifestEntries({...});

يمكن إعادة كتابته في الإصدار 3 على النحو التالي:

const {manifestEntries, count, size, warnings} = await workboxBuild.getManifest({...});

// Use manifestEntries like before.
// Optionally, log the new info returned in count, size, warnings.
  • تمت إزالة الدالة generateFileManifest(). ننصح المطوّرين بالاتصال بالرمز getManifest() بدلاً من ذلك واستخدام استجابته لكتابة البيانات على القرص بالتنسيق المناسب.

Workbox-cache-expiration

  • لم يطرأ أي تغيير على واجهة برمجة تطبيقات المكونات الإضافية، وهو الوضع الذي سيستخدمه معظم المطورين في نهاية المطاف. ومع ذلك، هناك تغييرات كبيرة في واجهة برمجة التطبيقات تؤثر على المطورين الذين يستخدمونها كصف مستقل. يمكنك الرجوع إلى المستندات المتعلّقة بالواجهة الجديدة لواجهة برمجة التطبيقات.

workbox-cli

يمكن للمطوّرين تشغيل واجهة سطر الأوامر (CLI) مع العلامة --help لمجموعة كاملة من المعلَمات المتوافقة.

  • تمت إزالة دعم الاسم المستعار workbox-cli للنص البرمجي الثنائي. يمكن الآن الوصول إلى البرنامج الثنائي باسم workbox فقط.
  • تمت إعادة تسمية الأمرَين generate:sw وinject:manifest إلى generateSW وinjectManifest في الإصدار 3.
  • في الإصدار 2، كان من المفترض أن يكون ملف الإعداد التلقائي (الذي يتم استخدامه عندما لا يتم توفير ملف بشكل صريح) هو workbox-cli-config.js في الدليل الحالي. في الإصدار 3، تبلغ workbox-config.js.

بشكل عام، يعني ذلك أنه في الإصدار 2:

$ workbox inject:manifest

تشغيل عملية الإصدار "إدخال البيان" باستخدام إعداد قراءة من workbox-cli-config.js، وفي الإصدار 3:

$ workbox injectManifest

سيفعل الشيء نفسه، ولكن اقرأ الإعدادات من workbox-config.js.

التخزين المؤقت لإطار العمل

  • أجرت الطريقة precache() في السابق تعديلات ذاكرة التخزين المؤقت وإعداد التوجيه لعرض الإدخالات المخزنة مؤقتًا. والآن، يعدّل precache() إدخالات ذاكرة التخزين المؤقت فقط، وقد تم الكشف عن طريقة جديدة، وهي addRoute()، لتسجيل مسار لعرض هذه الردود المخزّنة مؤقتًا. يستطيع المطوّرون الذين يريدون الحصول على الوظيفة الثنائية السابقة التبديل إلى ميزة الاتصال بـ precacheAndRoute().
  • العديد من الخيارات التي كان يتم ضبطها سابقًا باستخدام الدالة الإنشائية WorkboxSW يتم تمريرها الآن كمَعلمة options في workbox.precaching.precacheAndRoute([...], options). ويتم إدراج الإعدادات التلقائية لهذه الخيارات في المستندات المرجعية، إذا لم يتم ضبطها.
  • بشكل تلقائي، سيتم تلقائيًا التحقّق تلقائيًا من تطابق عناوين URL التي لا تتضمن أي امتدادات ملفات مع إدخال ذاكرة التخزين المؤقت الذي يحتوي على الإضافة .html. على سبيل المثال، في حال تقديم طلب لـ /path/to/index (لم يتم تخزينه مؤقتًا بشكل مسبق) وكان هناك إدخال مخزَّن مؤقتًا بشكل مسبق لـ /path/to/index.html، سيتم استخدام هذا الإدخال المخزّن مؤقتًا بشكل مسبق. ويمكن للمطوّرين إيقاف هذا السلوك الجديد من خلال ضبط {cleanUrls: false} عند تمرير الخيارات إلى workbox.precaching.precacheAndRoute().
  • لن يتم ضبط workbox-broadcast-update تلقائيًا للإعلان عن تحديثات ذاكرة التخزين المؤقت لمواد العرض المخزنة مؤقتًا بشكل مسبق.

التعليمة البرمجية التالية في الإصدار 2:

const workboxSW = new self.WorkboxSW({
  directoryIndex: 'index.html',
  ignoreUrlParametersMatching: [/^utm_/],
  precacheChannelName: 'precache-updates',
});
workboxSW.precache([...]);

على نسخة v3 المكافئة لـ:

workbox.precaching.addPlugins([
    new workbox.broadcastUpdate.Plugin('precache-updates')
]);

workbox.precaching.precacheAndRoute([...], {
  cleanUrls: false,
  directoryIndex: 'index.html',
  ignoreUrlParametersMatching: [/^utm_/],
});

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

  • على المطوّرين الذين سبق لهم استخدام workbox-routing من خلال مساحة الاسم workbox.router.* لكائن WorkboxSW التبديل إلى مساحة الاسم الجديدة workbox.routing.*.
  • يتم الآن تقييم المسارات بترتيب النتائج المسجّلة الأولى. هذا هو الترتيب المقابل للتقييم Route الذي تم استخدامه في الإصدار 2، حيث سيتم إعطاء الأولوية لآخر Route تم تسجيله.
  • تمت إزالة الفئة ExpressRoute وإتاحة استخدام أحرف البدل "السريع". يقل حجم workbox-routing إلى حد كبير. سيتم التعامل الآن مع السلاسل المستخدَمة كمَعلمة أولى للدالة workbox.routing.registerRoute() على أنّها مطابقات تامة. يجب التعامل مع أحرف البدل أو المطابقات الجزئية من خلال RegExp، ويمكن أن يؤدي استخدام أي RegExp يتطابق مع جزء من عنوان URL للطلب أو كله إلى تشغيل مسار.
  • تمت إزالة طريقة المساعدة "addFetchListener()" للصف "Router". يمكن للمطوّرين إما إضافة معالج fetch الخاص بهم بشكل صريح أو استخدام الواجهة التي يوفّرها workbox.routing، ما سيؤدي ضمنيًا إلى إنشاء معالج fetch لهم.
  • تمّت إزالة الطريقتَين registerRoutes() وunregisterRoutes(). ولم يتم تغيير إصدارات تلك الطرق التي تعمل على Route واحد، وعلى المطوّرين الذين يحتاجون إلى تسجيل مسارات متعددة أو إلغاء تسجيلها في آنٍ واحد إجراء سلسلة من المكالمات إلى registerRoute() أو unregisterRoute() بدلاً من ذلك.

التعليمة البرمجية التالية في الإصدار 2:

const workboxSW = new self.WorkboxSW();

workboxSW.router.registerRoute(
  '/path/with/.*/wildcard/',
  workboxSW.strategies.staleWhileRevalidate()
);

workboxSW.router.registerRoute(
  new RegExp('^https://example.com/'),
  workboxSW.strategies.networkFirst()
);

على نسخة v3 المكافئة لـ:

workbox.routing.registerRoute(
  new RegExp('^https://example.com/'),
  workbox.strategies.networkFirst()
);

workbox.routing.registerRoute(
  new RegExp('^/path/with/.*/wildcard'),
  workbox.strategies.staleWhileRevalidate()
);

Workbox-rategies (المعروفة سابقًا باسم Workbox-runtime-التخزين المؤقت)

  • الوحدة "workbox-runtime-caching" تُعرف رسميًا الآن باسم "workbox-strategies"، وتم نشرها في npm باسمها الجديد.
  • لم يعد استخدام تاريخ انتهاء صلاحية ذاكرة التخزين المؤقت في استراتيجية بدون توفير اسم ذاكرة تخزين مؤقت صالحًا بعد الآن. في الإصدار 2، كان ذلك ممكنًا:
workboxSW.strategies.staleWhileRevalidate({
  cacheExpiration: {maxEntries: 50},
});

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

workboxSW.strategies.staleWhileRevalidate({
  cacheName: 'my-cache',
  plugins: [new workbox.expiration.Plugin({maxEntries: 50})],
});
  • تمت إعادة تسمية طريقة مراحل نشاط cacheWillMatch إلى cachedResponseWillBeUsed. لن يكون هذا التغيير مرئيًا للمطوِّرين إلا إذا كتبوا مكوّنات إضافية خاصة بهم تتفاعل مع cacheWillMatch.
  • تم تغيير بنية تحديد المكوّنات الإضافية عند تهيئة استراتيجية. يجب إدراج كل مكوّن إضافي بشكل صريح في السمة plugins الخاصة بإعداد الاستراتيجية.

التعليمة البرمجية التالية في الإصدار 2:

const workboxSW = new self.WorkboxSW();

const networkFirstStrategy = workboxSW.strategies.networkFirst({
  cacheName: 'my-cache',
  networkTimeoutSeconds: 5,
  cacheExpiration: {
    maxEntries: 50,
  },
  cacheableResponse: {
    statuses: [0, 200],
  },
});

على نسخة v3 المكافئة لـ:

const networkFirstStrategy = workbox.strategies.networkFirst({
  cacheName: 'my-cache',
  networkTimeoutSeconds: 5,
  plugins: [
    new workbox.expiration.Plugin({maxEntries: 50}),
    new workbox.cacheableResponse.Plugin({statuses: [0, 200]}),
  ],
});

يمكنك الاطّلاع على المزيد من المعلومات في دليل "استخدام المكوّنات الإضافية".

Workbox-sw

  • في التفاصيل الداخلية، تمت إعادة كتابة workbox-sw لتصبح واجهة "أداة تحميل" خفيفة الوزن، وتتطلّب بعض الإعدادات الأساسية، كما أنّها مسؤولة عن تجميع الوحدات الأخرى المطلوبة في وقت التشغيل. بدلاً من إنشاء مثيل جديد من الفئة WorkboxSW، سيتفاعل مطوّرو البرامج مع مثيل حالي يتم عرضه تلقائيًا في مساحة الاسم العامة.

سابقًا في الإصدار 2:

importScripts('<path to workbox-sw>/importScripts/workbox-sw.prod.v2.1.3.js');

const workbox = new WorkboxSW({
  skipWaiting: true,
  clientsClaim: true,
  // etc.
});

workbox.router.registerRoute(...);

في الإصدار 3، ما عليك سوى استيراد النص البرمجي workbox-sw.js، وسيكون المثيل الجاهز للاستخدام متاحًا تلقائيًا في مساحة الاسم العامة باسم workbox:

importScripts('<path to workbox-sw>/3.0.0/workbox-sw.js');

// workbox is implicitly created and ready for use.
workbox.routing.registerRoute(...);
  • لم تعُد skipWaiting وclientsClaim ضمن الخيارات التي يتم تمريرها إلى الدالة الإنشائية WorkboxSW. بدلاً من ذلك، تم تغييرها إلى الطريقتين workbox.clientsClaim() وworkbox.skipWaiting().
  • لم يعُد خيار handleFetch الذي كان متوفّرًا سابقًا في الدالة الإنشائية v2 متاحًا في الإصدار 3. ويمكن للمطوّرين الذين يحتاجون إلى وظائف مشابهة لاختبار مشغّل الخدمات بدون استدعاء أي معالِجات جلب، استخدام خيار تجاوز الشبكة المتاح في "أدوات المطوّرين" في Chrome.
خيار &quot;تجاوز الشبكة&quot; في &quot;أدوات مطوري البرامج في Chrome&quot;

Workbox-webpack-extension

تمت إعادة كتابة المكوّن الإضافي بدرجة كبيرة، وفي كثير من الحالات، يمكن استخدامه في وضع "الضبط الصفري". يمكنك الرجوع إلى المستندات المتعلّقة بالواجهة الجديدة لواجهة برمجة التطبيقات.

  • تعرض واجهة برمجة التطبيقات الآن فئتَين، وهما GenerateSW وInjectManifest. ويجعل هذا التبديل بين الأوضاع واضحًا مقارنةً بسلوك الإصدار 2 الذي تغيّر السلوك فيه استنادًا إلى توفُّر swSrc.
  • يتم تلقائيًا تخزين مواد العرض في مسار تجميع حزمة الويب بشكل مسبق ولن يكون من الضروري إعداد globPatterns بعد الآن. السبب الوحيد لمواصلة استخدام globPatterns هو الحاجة إلى التخزين المؤقت المسبق لمواد العرض غير المضمّنة في إصدار حزمة الويب. بوجه عام، عند الانتقال إلى المكوّن الإضافي الإصدار 3، يجب أن تبدأ بإزالة جميع الإعدادات السابقة المستندة إلى glob، ثم إعادة إضافتها إذا احتجت إليها تحديدًا.

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

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