يركّز هذا الدليل على التغييرات الجديدة التي تم إدخالها في الإصدار 6 من Workbox، مع أمثلة عن التغييرات التي عليك إجراؤها عند الترقية من الإصدار 5 من Workbox.
تغييرات قد تؤدي إلى أعطال
نواة إطار العمل
لن تُضاف الطريقة skipWaiting()
في workbox-core
إلى معالج install
بعد الآن، وتعادل هذه الطريقة استدعاء self.skipWaiting()
فقط.
من الآن فصاعدًا، يمكنك استخدام self.skipWaiting()
بدلاً من ذلك، لأنّه من المحتمل إزالة skipWaiting()
في الإصدار 7 من Workbox.
العمل بصندوق العمل
- لم يعُد من الممكن استخدام مستندات HTML من مصادر متعددة لعناوين URL التي تتوافق مع إعادة توجيه HTTP لاستيفاء طلب التنقّل باستخدام
workbox-precaching
. هذا السيناريو غير شائع بشكل عام. - يتجاهل
workbox-precaching
الآن مَعلمة طلب البحث لعنوان URLfbclid
عند البحث عن استجابة مخزَّنة مؤقتًا لطلب معيّن. - تستخدم الدالة الإنشائية
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.