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

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

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

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

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

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

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

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

إنشاء الإعدادات

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

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

workbox-background-sync

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

workbox-broadcast-cache-update

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

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

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

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

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

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

workbox-build

• سيتم الآن تنفيذ مطابقة النمط 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 manifestArray;، يجب استخدام return {manifest: manifestArray};). mThis يسمح للمكوّن الإضافي بتضمين سمة 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;
  });
};

له الإصدار 3 مكافئ لما يلي:

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

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

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

ويعني مجملها أنه في الإصدار 2:

$ workbox inject:manifest

سيشغل "injection" باستخدام إعداد تمت قراءته من 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([...]);

له الإصدار 3 مكافئ لما يلي:

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()
);

له الإصدار 3 مكافئ لما يلي:

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

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

إستراتيجيات صندوق العمل (المعروفة سابقًا باسم التخزين المؤقت في وقت التشغيل)

• أصبحت وحدة 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],
  },
});

له الإصدار 3 مكافئ لما يلي:

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 الذي كان متاحًا في السابق في الدالة الإنشائية للإصدار 2 متاحًا في الإصدار 3. يمكن للمطوّرين استخدام "تجاوز للشبكة" إذا كانوا بحاجة إلى وظائف مشابهة لاختبار مشغّل الخدمات بدون استدعاء أيّ معالِجات جلب. المتاح في أدوات مطوّري برامج Chrome.

workbox-webpack-plugin

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

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

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

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