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

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

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

تمت إعادة تسمية فئات المكون الإضافي

يتضمّن عدد من حزم الإصدار 4 من Workbox فئات باسم Plugin. في الإصدار 5، تمت إعادة تسمية هذه الفئات لاتّباع معرّف حزمة النمط + Plugin:

  • BackgroundSyncPlugin
  • BroadcastUpdatePlugin
  • CacheableResponsePlugin
  • ExpirationPlugin
  • RangeRequestsPlugin

تنطبق إعادة التسمية هذه سواء كنت تستخدم الفئات من خلال عمليات استيراد الوحدات أو من خلال مساحات الاسم workbox.*.

نقطة الاستبدال التلقائية لبيان ذاكرة التخزين المؤقت المسبق

في السابق، عند استخدام إحدى أدوات الإصدار في وضع "إدخال البيان"، كان يتم التحقّق من ملف مشغّل خدمات المصدر للتأكّد من توفُّر precacheAndRoute([])، مع استخدام ذلك المصفوفة الفارغة [] كعنصر نائب للنقطة التي تم فيها إدخال بيان ذاكرة التخزين المؤقت.

في الإصدار 5 من Workbox، تم تغيير منطق الاستبدال ويتم الآن استخدام self.__WB_MANIFEST تلقائيًا كنقطة إدخال.

// v4:
precacheAndRoute([]);

// v5:
precacheAndRoute(self.__WB_MANIFEST);

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

هناك خياران كانا متاحين سابقًا لمسارات التنقل، وهما blacklist وwhitelist تمت إعادة تسميتهما denylist وallowlist.

كان workbox-routing يدعم في السابق طريقة registerNavigationRoute() التي أدّت إلى تنفيذ أمرين:

  1. تم رصد ما إذا كان حدث fetch معيّن يحتوي على mode من 'navigate' أم لا.
  2. إذا كان الأمر كذلك، يتم الرد على هذا الطلب باستخدام محتوى عنوان URL تم تخزينه مؤقتًا وقد تم ترميزه بشكل ثابت، بغض النظر عن عنوان URL الذي يتم الانتقال إليه.

وهذا نمط شائع للاستخدام عند تنفيذ بنية App Shell.

إنّ الخطوة الثانية التي يترتب على استخدامها بالقراءة من ذاكرة التخزين المؤقت تقع خارج نطاق المسؤوليات التي تقع على عاتق workbox-routing. بدلاً من ذلك، نعتبرها وظيفة يجب أن تكون جزءًا من workbox-precaching، باستخدام طريقة جديدة، وهي createHandlerBoundToURL(). يمكن أن تعمل هذه الطريقة الجديدة بشكل وثيق مع صف NavigationRoute الحالي في workbox-routing لتنفيذ المنطق نفسه.

إذا كنت تستخدم الخيار navigateFallback في أحد وضع "إنشاء البرامج اللاسلكية" (SW) في أداة الإنشاء، سيتم التبديل تلقائيًا. إذا سبق لك ضبط الخيارَين navigateFallbackBlacklist أو navigateFallbackWhitelist، يُرجى تغييرهما إلى navigateFallbackDenylist أو navigateFallbackAllowlist على التوالي.

إذا كنت تستخدم وضع "إدخال البيان" أو كنت تكتب مشغّل الخدمات بنفسك، واستدعى عامل الخدمة الإصدار 4 من Workbox registerNavigationRoute() مباشرةً، عليك إجراء تغيير على الرمز للحصول على السلوك المكافئ له.

// v4:
import {getCacheKeyForURL} from 'workbox-precaching';
import {registerNavigationRoute} from 'workbox-routing';

const appShellCacheKey = getCacheKeyForURL('/app-shell.html');
registerNavigationRoute(appShellCacheKey, {
  whitelist: [...],
  blacklist: [...],
});

// v5:
import {createHandlerBoundToURL} from 'workbox-precaching';
import {NavigationRoute, registerRoute} from 'workbox-routing';

const handler = createHandlerBoundToURL('/app-shell.html');
const navigationRoute = new NavigationRoute(handler, {
  allowlist: [...],
  denylist: [...],
});
registerRoute(navigationRoute);

لم تعُد بحاجة إلى الاتصال بـ getCacheKeyForURL()، لأنّ createHandlerBoundToURL() سيتولى هذه المهمة بالنيابة عنك.

إزالة makeRequest() من استراتيجيات إطار العمل

إنّ الاتصال برقم makeRequest() يعادل غالبًا طلب الرقم handle() في إحدى صفوف workbox-strategy. كانت الاختلافات بين الطريقتين طفيفة جدًا لدرجة أن الاحتفاظ بكليهما لم يكن منطقيًا. من المفترض أن يتمكّن المطوّرون الذين اتصلوا بـ makeRequest() من التبديل إلى استخدام handle() بدون أي تغيير آخر:

// v4:
const strategy = new StaleWhileRevalidate({...});
const response = await strategy.makeRequest({event, request});

// v5:
const strategy = new StaleWhileRevalidate({...});
const response = await strategy.handle({event, request});

في الإصدار 5، تتعامل handle() مع request كمَعلمة مطلوبة، ولن تعود إلى استخدام event.request. تأكد من تمرير طلب صالح عند الاتصال برقم handle().

يتم استخدام "تحديث البث" لمربع العمل postMessage() دائمًا.

في الإصدار 4، سيتم تلقائيًا استخدام Broadcast Channel API في مكتبة workbox-broadcast-update لإرسال الرسائل عندما تكون متاحة، وعدم استخدام postMessage() إلا عندما لم تكن ميزة البث متاحة.

أدركنا أن الحاجة إلى الاستماع إلى مصدرين محتملين للرسائل الواردة جعل كتابة التعليمات البرمجية من جهة العميل أمرًا معقدًا للغاية. بالإضافة إلى ذلك، في بعض المتصفِّحات، يتم تلقائيًا التخزين المؤقت لاستدعاءات postMessage() من مشغّل الخدمات الذي تم إرساله إلى صفحات العميل إلى أن يتم إعداد أداة معالجة حدث message. ليس هناك تخزين مؤقت مع واجهة برمجة تطبيقات قناة البث، ويتم تجاهل الرسائل التي تم بثها فقط إذا تم إرسالها قبل أن تصبح صفحة العميل جاهزة لتلقيها.

لهذه الأسباب، غيّرنا workbox-broadcast-update بحيث يتم استخدام postMessage() دائمًا في الإصدار 5. يتم إرسال الرسائل واحدًا تلو الآخر إلى جميع صفحات العميل ضمن نطاق مشغّل الخدمات الحالي.

لاستيعاب هذا السلوك الجديد، يمكنك إزالة أي رمز كان لديك في صفحات العملاء التي أنشأت BroadcastChannel مثيل، وبدلاً من ذلك، إعداد أداة معالجة حدث message على navigator.serviceWorker:

// v4:
const updatesChannel = new BroadcastChannel('api-updates');
updatesChannel.addEventListener('message', event => {
  const {cacheName, updatedUrl} = event.data.payload;
  // ... your code here ...
});

// v5:
// This listener should be added as early as possible in your page's lifespan
// to ensure that messages are properly buffered.
navigator.serviceWorker.addEventListener('message', event => {
  // Optional: ensure the message came from workbox-broadcast-update
  if (event.meta === 'workbox-broadcast-update') {
    const {cacheName, updatedUrl} = event.data.payload;
    // ... your code here ...
  }
});

يجب ألا يحتاج مستخدمو workbox-window إلى إجراء أي تغييرات، حيث تم تعديل منطقها الداخلي للاستماع إلى مكالمات postMessage().

تتطلب أدوات الإصدار Node.js v8 أو إصدار أعلى

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

يتطلب Workbox-webpack-extension الإصدار 4 أو إصدار أحدث من webpack.

إذا كنت تستخدم workbox-webpack-plugin، يمكنك تحديث إعداد حزمة الويب لاستخدام الإصدار 4 من حزمة الويب على الأقل.

مراجعة كاملة لخيارات أداة الإنشاء

لم يعد عدد من مَعلمات الإعداد workbox-build وworkbox-cli وworkbox-webpack-plugin متاحًا. على سبيل المثال، سينشئ لك generateSW دائمًا حزمة وقت تشغيل محلية لتطبيق Workbox، لذلك لم يعُد خيار importWorkboxFrom مفيدًا.

راجِع وثائق الأداة المعنية للاطّلاع على قوائم الخيارات المتاحة.

إزالة generateSWString من إصدار إطار العمل

تمت إزالة الوضع generateSWString من workbox-build. نتوقع أن يكون تأثير ذلك بسيطًا، لأنّه تم استخدامه داخليًا بشكل أساسي من قِبل "workbox-webpack-plugin".

تغييرات اختيارية

استخدام عمليات استيراد الوحدة

وعلى الرغم من أنّ هذا التغيير أ) اختياري وب) كان ممكنًا من الناحية الفنية عند استخدام الإصدار 4 من Workbox، فإنّ أكبر تغيير نتوقّعه عند الانتقال إلى الإصدار 5 هو نموذج يمكنك فيه إنشاء مشغّل الخدمات المجمّع الخاص بك من خلال استيراد وحدات Workbox. وتُعدّ هذه الطريقة بديلة لاستدعاء importScripts('/path/to/workbox-sw.js') في الجزء العلوي من مشغّل الخدمات، واستخدام Workbox من خلال مساحة الاسم workbox.*.

إذا كنت تستخدم إحدى أدوات الإصدار (workbox-webpack-plugin أو workbox-build أو workbox-cli) في وضع "إنشاء واجهة برمجة التطبيقات (SW)"، سيتم تطبيق هذا التغيير تلقائيًا. وستُخرج كل هذه الأدوات حزمة محلية مخصصة من وقت تشغيل Workbox إلى جانب الرمز الفعلي اللازم لتنفيذ منطق عامل الخدمة. في هذا السيناريو، لم يعد هناك أي اعتمادية على workbox-sw أو نسخة شبكة توصيل المحتوى من Workbox. استنادًا إلى قيمة إعدادات inlineWorkboxRuntime، سيتم تقسيم وقت تشغيل Workbox إلى ملف منفصل يجب نشره مع مشغّل الخدمات (عند الضبط على false، وهو الإعداد التلقائي)، أو سيتم تضمينه مع منطق عامل الخدمة (عند الضبط على true).

إذا كنت تستخدم أدوات الإصدار في وضع "إدخال البيان"، أو إذا كنت لا تستخدم أدوات إصدار Workbox على الإطلاق، يمكنك الاطّلاع على المزيد من المعلومات حول إنشاء حزمة وقت تشغيل Workbox في دليل استخدام الحزم (حزمة الويب/التجميع) مع Workbox الحالي.

تتم كتابة الوثائق والأمثلة الخاصة بالإصدار 5 على افتراض أنّ الوحدة تستورد بنية الوحدة، على الرغم من أنّ مساحة الاسم workbox.* ستظل متاحة في الإصدار 5 من Workbox.

قراءة الردود المخزنة مؤقتًا بشكل مسبق

يحتاج بعض المطوّرين إلى قراءة الردود المخزّنة مؤقتًا بشكل مسبق من ذاكرة التخزين المؤقت مباشرةً، بدلاً من استخدامها ضمنيًا من خلال طريقة precacheAndRoute(). النمط الشائع في الإصدار 4 هو الحصول أولاً على مفتاح ذاكرة التخزين المؤقت الخاص بالإصدار الحالي من مورد تم تخزينه مؤقتًا، ثم تمرير هذا المفتاح مع اسم ذاكرة التخزين المؤقت المسبق إلى caches.match() للحصول على Response.

لتبسيط هذه العملية، يتيح workbox-precaching في الإصدار 5 طريقة جديدة مكافئة، وهي matchPrecache():

// v4:
import {cacheNames} from 'workbox-core';
import {getCacheKeyForURL} from 'workbox-precaching';

const cachedResponse = await caches.match(
  getCacheKeyForURL(`/somethingPrecached`),
  {
    cacheName: cacheNames.precache,
  }
);

// v5:
import {matchPrecache} from 'workbox-precaching';

const cachedResponse = await matchPrecache(`/somethingPrecached`);

استخدام TypeScript

في الإصدار 5، تتم كتابة مكتبات وقت تشغيل Workbox بلغة TypeScript. وبينما سنستمر في نشر وحدات وحِزم JavaScript التي تم نقلها لتلائم المطورين الذين لم يستخدموا TypeScript، إذا كنت تستخدم TypeScript، يُفترض أن تستفيد من معلومات النوع الدقيقة والحديثة دائمًا مباشرةً من مشروع Workbox.

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

توضّح عملية تنفيذ الالتزام هذه عملية نقل بيانات شاملة إلى حد ما، وتتضمّن تعليقات مضمَّنة. وهو يستخدم التجميع لتضمين وقت تشغيل مخصّص لصندوق العمل في مشغّل الخدمات النهائي بدلاً من تحميل وقت التشغيل من شبكة توصيل المحتوى (CDN).

على الرغم من عدم تغطية كل تغيير قد يؤدي إلى أعطال، إليك قبل وبعد ترقية ملف عامل خدمات واحد من الإصدار 4 إلى الإصدار 5، بما في ذلك التبديل إلى النوع TypeScript.

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

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