إطار العمل-sw

توفّر الوحدة "workbox-sw" طريقة سهلة للغاية لبدء استخدام وحدات Workbox، كما تبسّط تحميل وحدات Workbox وتوفّر بعض الأساليب المساعدة البسيطة.

يمكنك استخدام workbox-sw عبر شبكة توصيل المحتوى (CDN) الخاصة بنا أو يمكنك استخدامه مع مجموعة من ملفات مربع العمل على الخادم الخاص بك.

استخدام Workbox SW من خلال شبكة توصيل المحتوى (CDN)

أسهل طريقة لبدء استخدام هذه الوحدة هي عبر شبكة توصيل المحتوى (CDN). تحتاج فقط إلى إضافة ما يلي إلى عامل الخدمة لديك:

importScripts(
  'https://storage.googleapis.com/workbox-cdn/releases/6.4.1/workbox-sw.js'
);

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

workbox.precaching.*
workbox.routing.*
etc

ستحدث هذه الميزة بعض الشيء عند البدء في استخدام الوحدات الإضافية.

وعند الرجوع إلى وحدة معيّنة للمرة الأولى، يرصد workbox-sw ذلك ويحمّل الوحدة قبل إتاحتها. يمكنك أن تلاحظ حدوث ذلك في علامة تبويب "الشبكة" في "أدوات مطوري البرامج".

سيتم تخزين هذه الملفات مؤقتًا بواسطة المتصفح لاستخدامها في المستقبل بلا اتصال بالإنترنت.

استخدام ملفات مربع العمل المحلي بدلاً من شبكة توصيل المحتوى (CDN)

إذا كنت لا تريد استخدام شبكة توصيل المحتوى (CDN)، فمن السهل التبديل إلى ملفات Workbox المستضافة على نطاقك الخاص.

إنّ أبسط طريقة هي الحصول على الملفات باستخدام الأمر copyLibraries في workbox-cli، ثم تحديد workbox-sw مكان هذه الملفات من خلال خيار الإعداد modulePathPrefix.

إذا وضعت الملفات ضِمن /third_party/workbox-vX.Y.Z/، ستستخدمها على النحو التالي:

importScripts('/third_party/workbox-vX.Y.Z/workbox-sw.js');

workbox.setConfig({
  modulePathPrefix: '/third_party/workbox-vX.Y.Z/',
});

تجنُّب عمليات الاستيراد غير المتزامنة

يشمل ذلك تحميل وحدات جديدة للمرة الأولى استدعاء importScripts() باستخدام المسار إلى ملف JavaScript المقابل (إما تمت استضافته على شبكة توصيل المحتوى (CDN) أو عبر عنوان URL محلي). وفي كلتا الحالتين، يتم فرض قيود مهمة: لا يمكن أن تحدث الطلبات الضمنية إلى importScripts() إلا داخل معالِج install الخاص بمشغّل الخدمة أو أثناء التنفيذ الأولي للنص البرمجي الخاص بمشغِّل الخدمة.

لتجنّب مخالفة هذه القيود، من أفضل الممارسات الإشارة إلى مساحات workbox.* المختلفة خارج أي معالِجات أحداث أو وظائف غير متزامنة.

على سبيل المثال، يمكن استخدام رمز مشغّل الخدمات ذي المستوى الأعلى التالي:

importScripts(
  'https://storage.googleapis.com/workbox-cdn/releases/6.4.1/workbox-sw.js'
);

// This will work!
workbox.routing.registerRoute(
  ({request}) => request.destination === 'image',
  new workbox.strategies.CacheFirst()
);

ولكن قد يكون هناك مشكلة في الرمز أدناه إذا لم تتم الإشارة إلى workbox.strategies في مكان آخر في مشغّل الخدمات:

importScripts(
  'https://storage.googleapis.com/workbox-cdn/releases/6.4.1/workbox-sw.js'
);

self.addEventListener('fetch', event => {
  if (event.request.url.endsWith('.png')) {
    // Oops! This causes workbox-strategies.js to be imported inside a fetch handler,
    // outside of the initial, synchronous service worker execution.
    const cacheFirst = new workbox.strategies.CacheFirst();
    event.respondWith(cacheFirst.handle({request: event.request}));
  }
});

إذا كنت بحاجة إلى كتابة رمز برمجي يخالف هذا القيد، يمكنك بشكل صريح تشغيل طلب importScripts() خارج معالج الأحداث باستخدام الإجراء workbox.loadModule():

importScripts(
  'https://storage.googleapis.com/workbox-cdn/releases/6.4.1/workbox-sw.js'
);

// This will trigger the importScripts() for workbox.strategies and its dependencies:
workbox.loadModule('workbox-strategies');

self.addEventListener('fetch', event => {
  if (event.request.url.endsWith('.png')) {
    // Referencing workbox.strategies will now work as expected.
    const cacheFirst = new workbox.strategies.CacheFirst();
    event.respondWith(cacheFirst.handle({request: event.request}));
  }
});

بدلاً من ذلك، يمكنك إنشاء مرجع إلى مساحات الاسم ذات الصلة خارج معالِجات الأحداث، ثم استخدام هذا المرجع لاحقًا:

importScripts(
  'https://storage.googleapis.com/workbox-cdn/releases/6.4.1/workbox-sw.js'
);

// This will trigger the importScripts() for workbox.strategies and its dependencies:
const {strategies} = workbox;

self.addEventListener('fetch', event => {
  if (event.request.url.endsWith('.png')) {
    // Using the previously-initialized strategies will work as expected.
    const cacheFirst = new strategies.CacheFirst();
    event.respondWith(cacheFirst.handle({request: event.request}));
  }
});

ملاحظة:لا تلتزم بعض إصدارات Chrome بهذا الحظر، كما أنّ الطلبات غير المتزامنة إلى importScripts() لا تؤدي إلى ظهور الخطأ المتوقّع. وننصح المطوّرين بعدم الاعتماد على هذا السلوك المعطّل. يخطط Chrome لإجراء تغيير بهدف منع هذا الاستخدام، ما يجعله متوافقًا مع ما تفعله المتصفحات الأخرى حاليًا.

فرض استخدام تصحيح الأخطاء أو إصدارات الإنتاج

تأتي جميع وحدات Workbox مع إصدارَين، إصدار تصحيح أخطاء يحتوي على التسجيل والتحقّق الإضافي من الأنواع، وإصدار إنتاج يزيل التسجيل والتحقّق من النوع.

سيستخدم workbox-sw تلقائيًا إصدار تصحيح الأخطاء للمواقع الإلكترونية على المضيف المحلي، ولكن سيتم استخدام إصدار الإنتاج في أي مصدر آخر.

إذا أردت فرض إصدارات تصحيح الأخطاء أو الإنتاج، يمكنك ضبط خيار الإعدادات debug:

workbox.setConfig({
  debug: true,
});

تحويل الرمز باستخدام عبارات الاستيراد لاستخدام workbox-sw

عند تحميل Workbox باستخدام workbox-sw، يتم الوصول إلى جميع حِزم Workbox من خلال مساحة الاسم workbox.* العامة.

إذا كان لديك نموذج رمز يتضمّن عبارات import وتريد تحويله لاستخدام workbox-sw، ما عليك سوى تحميل workbox-sw واستبدال كل عبارات import بمتغيرات محلية تشير إلى تلك الوحدات في مساحة الاسم العامة.

تعمل هذه الطريقة لأنّ كل حزمة مشغّل خدمات Workbox تم نشرها على npm تتوفر أيضًا على مساحة الاسم workbox العالمية من خلال إصدار camelCase من الاسم (مثلاً، يمكن العثور على جميع الوحدات التي تم تصديرها من حزمة workbox-precaching npm على workbox.precaching.*. وجميع الوحدات التي تم تصديرها من حزمة workbox-background-sync npm يمكن العثور عليها على workbox.backgroundSync.*).

على سبيل المثال، إليك بعض الرموز التي تستخدم عبارات import التي تشير إلى وحدات Workspace:

import {registerRoute} from 'workbox-routing';
import {CacheFirst} from 'workbox-strategies';
import {CacheableResponse} from 'workbox-cacheable-response';

registerRoute(
  ({request}) => request.destination === 'image',
  new CacheFirst({
    plugins: [new CacheableResponsePlugin({statuses: [0, 200]})],
  })
);

وإليك الرمز البرمجي نفسه الذي تمت إعادة كتابته لاستخدام workbox-sw (لاحظ أنه تم تغيير عبارات الاستيراد فقط، ولم يتم التأثير على المنطق):

importScripts(
  'https://storage.googleapis.com/workbox-cdn/releases/6.4.1/workbox-sw.js'
);

const {registerRoute} = workbox.routing;
const {CacheFirst} = workbox.strategies;
const {CacheableResponse} = workbox.cacheableResponse;

registerRoute(
  ({request}) => request.destination === 'image',
  new CacheFirst({
    plugins: [new CacheableResponsePlugin({statuses: [0, 200]})],
  })
);