يركّز هذا الدليل على التغييرات العاجلة التي تم إدخالها على الإصدار 3 من Workbox، مع أمثلة على التغييرات التي عليك إجراؤها عند الترقية من إصدار Workbox v2.
إذا كنت تستخدم حاليًا تركيبة sw-precache
/sw-toolbox
القديمة وكنت تريد الانتقال إلى Workbox لأول مرة، إليك دليل مختلف حول نقل البيانات سيساعدك في ذلك.
خلفية الإصدار 3
يمثّل الإصدار 3 من Workbox تحديثًا مهمًّا لقاعدة الترميز الحالية. الأهداف الرئيسية هي:
- تقليل حجم "إطار العمل": تم تقليل مقدار رمز وقت تشغيل مشغّل الخدمات الذي تم تنزيله وتنفيذه. وبدلاً من تمكين الجميع من استخدام حزمة متجانسة، سيتم في وقت التشغيل استيراد رمز الميزات المحددة التي تستخدمها فقط.
- يحتوي Workspace على شبكة توصيل محتوى (CDN). نوفّر شبكة توصيل محتوى متوافقة بالكامل ومستنِدة إلى Google Cloud Storage كخيار أساسي للوصول إلى مكتبات وقت تشغيل Workbox، ما يسهّل عليك بدء استخدام Workbox.
- عملية تصحيح أخطاء وسجلات أفضل تم تحسين تجربة تصحيح الأخطاء والتسجيل إلى حد كبير. يتم تفعيل سجلات تصحيح الأخطاء تلقائيًا عندما يتم استخدام Workbox من مصدر
localhost
وتتم إزالة كل عمليات التسجيل وتأكيدات من إصدارات الإنتاج. - مكوّن إضافي محسَّن لحزمة الويب. تتكامل
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.
Workbox-webpack-extension
تمت إعادة كتابة المكوّن الإضافي بدرجة كبيرة، وفي كثير من الحالات، يمكن استخدامه في وضع "الضبط الصفري". يمكنك الرجوع إلى المستندات المتعلّقة بالواجهة الجديدة لواجهة برمجة التطبيقات.
- تعرض واجهة برمجة التطبيقات الآن فئتَين، وهما
GenerateSW
وInjectManifest
. ويجعل هذا التبديل بين الأوضاع واضحًا مقارنةً بسلوك الإصدار 2 الذي تغيّر السلوك فيه استنادًا إلى توفُّرswSrc
. - يتم تلقائيًا تخزين مواد العرض في مسار تجميع حزمة الويب بشكل مسبق ولن يكون من الضروري إعداد
globPatterns
بعد الآن. السبب الوحيد لمواصلة استخدامglobPatterns
هو الحاجة إلى التخزين المؤقت المسبق لمواد العرض غير المضمّنة في إصدار حزمة الويب. بوجه عام، عند الانتقال إلى المكوّن الإضافي الإصدار 3، يجب أن تبدأ بإزالة جميع الإعدادات السابقة المستندة إلىglob
، ثم إعادة إضافتها إذا احتجت إليها تحديدًا.
الحصول على المساعدة
نتوقّع أن تكون معظم عمليات نقل البيانات مباشرة. إذا واجهت مشاكل غير مذكورة في هذا الدليل، يُرجى إعلامنا من خلال فتح مشكلة على GitHub.