استراتيجيات-صندوق العمل

عند طرح مهام الخدمة لأول مرة، ظهرت مجموعة من استراتيجيات التخزين المؤقت الشائعة. استراتيجية التخزين المؤقت هي نمط يحدّد كيفية إنشاء عامل الخدمة للردّ بعد تلقّي حدث جلب.

يوفّر workbox-strategies استراتيجيات التخزين المؤقت الأكثر شيوعًا لتسهيل تطبيقها في الخدمة العاملة.

لن نتطرق إلى الكثير من التفاصيل خارج الاستراتيجيات المتوافقة مع Workbox، ويمكنك الاطّلاع على مزيد من المعلومات في "كتاب الوصفات بلا إنترنت".

استخدام الاستراتيجيات

في الأمثلة التالية، سنوضّح لك كيفية استخدام استراتيجية ملفّات التخزين المؤقت في Workbox مع workbox-routing. هناك بعض الخيارات التي يمكنك تحديدها باستخدام كل استراتيجية مُدرَجة في قسم "ضبط الاستراتيجيات" من هذا المستند.

في قسم "الاستخدام المتقدّم"، سنتناول كيفية استخدام استراتيجيات التخزين المؤقت مباشرةً بدون workbox-routing.

Stale-While-Revalidate

الرسم البياني لحالة "البيانات القديمة أثناء إعادة التحقّق"

يتيح لك النمط stale-while-revalidate الردّ على الطلب في أسرع وقت ممكن باستخدام استجابة محفوظة في ذاكرة التخزين المؤقت إذا كانت متاحة، مع الرجوع إلى طلب الشبكة إذا لم يكن محفوظًا في ذاكرة التخزين المؤقت. بعد ذلك، يتم استخدام طلب الشبكة لتعديل ذاكرة التخزين المؤقت. على عكس بعض عمليات التنفيذ لميزة "إعادة التحقّق من صحة البيانات أثناء استخدامها"، ستقدّم هذه الاستراتيجية دائمًا طلبًا لإعادة التحقّق من الصحة، بغض النظر عن عمر الردّ المخزّن مؤقتًا.

هذه استراتيجية شائعة إلى حدٍ ما، حيث لا يكون توفُّر أحدث مرجع ضروريًا للتطبيق.

import {registerRoute} from 'workbox-routing';
import {StaleWhileRevalidate} from 'workbox-strategies';

registerRoute(
  ({url}) => url.pathname.startsWith('/images/avatars/'),
  new StaleWhileRevalidate()
);

ذاكرة التخزين المؤقت أولاً (استخدام ذاكرة التخزين المؤقت أولاً ثم الشبكة)

مخطّط "الذاكرة المؤقتة أولاً"

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

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

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

registerRoute(({request}) => request.destination === 'style', new CacheFirst());

الشبكة أولاً (الشبكة تعود إلى ذاكرة التخزين المؤقت)

الرسم البياني الأول للشبكة

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

import {registerRoute} from 'workbox-routing';
import {NetworkFirst} from 'workbox-strategies';

registerRoute(
  ({url}) => url.pathname.startsWith('/social-timeline/'),
  new NetworkFirst()
);

الشبكة فقط

الرسم البياني للشبكة فقط

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

import {registerRoute} from 'workbox-routing';
import {NetworkOnly} from 'workbox-strategies';

registerRoute(({url}) => url.pathname.startsWith('/admin/'), new NetworkOnly());

ذاكرة التخزين المؤقت فقط

مخطّط بياني لذاكرة التخزين المؤقت فقط

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

import {registerRoute} from 'workbox-routing';
import {CacheOnly} from 'workbox-strategies';

registerRoute(({url}) => url.pathname.startsWith('/app/v2/'), new CacheOnly());

ضبط الاستراتيجيات

تتيح لك جميع الاستراتيجيات ضبط ما يلي:

  • اسم ذاكرة التخزين المؤقت المطلوب استخدامها في الاستراتيجية.
  • قيود انتهاء صلاحية ذاكرة التخزين المؤقت لاستخدامها في الاستراتيجية
  • صفيف من المكوّنات الإضافية التي سيتم استدعاء طرق دورة حياتها عند جلب طلب وتخزينه مؤقتًا

تغيير ذاكرة التخزين المؤقت المستخدَمة في إحدى الاستراتيجيات

يمكنك تغيير استراتيجية ذاكرة التخزين المؤقت المستخدَمة من خلال تقديم اسم ذاكرة تخزين مؤقت. يكون ذلك مفعّلاً إذا كنت تريد فصل مواد العرض للمساعدة في تصحيح الأخطاء.

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

registerRoute(
  ({request}) => request.destination === 'image',
  new CacheFirst({
    cacheName: 'image-cache',
  })
);

استخدام المكوّنات الإضافية

تأتي Workbox مع مجموعة من الإضافات التي يمكن استخدامها مع هذه الاستراتيجيات.

لاستخدام أيّ من هذه المكوّنات الإضافية (أو مكوّن إضافي مخصّص)، ما عليك سوى إدخال العناصر إلى الخيار plugins.

import {registerRoute} from 'workbox-routing';
import {CacheFirst} from 'workbox-strategies';
import {ExpirationPlugin} from 'workbox-expiration';

registerRoute(
  ({request}) => request.destination === 'image',
  new CacheFirst({
    cacheName: 'image-cache',
    plugins: [
      new ExpirationPlugin({
        // Only cache requests for a week
        maxAgeSeconds: 7 * 24 * 60 * 60,
        // Only cache 10 requests.
        maxEntries: 10,
      }),
    ],
  })
);

الاستراتيجيات المخصّصة

بالإضافة إلى ضبط الاستراتيجيات، تتيح لك أداة Workbox إنشاء استراتيجياتك المخصّصة. يمكن إجراء ذلك من خلال استيراد فئة Strategy الأساسية وتوسيع نطاقها من workbox-strategies:

import {Strategy} from 'workbox-strategies';

class NewStrategy extends Strategy {
  _handle(request, handler) {
    // Define handling logic here
  }
}

في هذا المثال، يتم استخدام handle() كاستراتيجية طلب لتحديد منطق معالجة محدّد. هناك استراتيجيتَان للطلبات يمكن استخدامهما:

  • handle(): تنفيذ استراتيجية طلب وإرجاع Promise سيتم حلّه باستخدام Response، مع استدعاء جميع عمليات معاودة الاتصال ذات الصلة بالمكونات الإضافية
  • ‫handleAll(): تشبه handle()، ولكنها تعرض شيئَين من النوع Promise. القيمة الأولى هي القيمة نفسها التي تعرضها handle()، وسيتمّ حلّ القيمة الثانية عند اكتمال الوعود التي تمت إضافتها إلى event.waitUntil() ضمن الاستراتيجية.

يتمّ استدعاء كلتا استراتيجيتَي الطلبات باستخدام مَعلمتَين:

  • request: Request الذي ستُعرِض الاستراتيجية ردًا عليه.
  • handler: مثيل StrategyHandler تم إنشاؤه تلقائيًا للاستراتيجية الحالية.

إنشاء استراتيجية جديدة

في ما يلي مثال على استراتيجية جديدة تعيد تنفيذ سلوك NetworkOnly:

class NewNetworkOnlyStrategy extends Strategy {
  _handle(request, handler) {
    return handler.fetch(request);
  }
}

لاحِظ كيفية استدعاء handler.fetch() بدلاً من الطريقة الأصلية fetch. توفّر فئة StrategyHandler عددًا من إجراءات الجلب والتخزين المؤقت التي يمكن استخدامها عند استخدام handle() أو handleAll():

  • fetch: تُستخدَم هذه الطريقة لجلب طلب معيّن، وتنشيط طرق requestWillFetch() وfetchDidSucceed() و fetchDidFail() لدورة حياة المكوّن الإضافي.
  • cacheMatch: تطابق طلبًا من ذاكرة التخزين المؤقت، وتستدعي طريقتَي cacheKeyWillBeUsed() و cachedResponseWillBeUsed() لمراحل نشاط المكوّن الإضافي
  • cachePut: تضع زوج طلب/استجابة في ذاكرة التخزين المؤقت، وتستدعي طرق دورة حياة المكوّن الإضافي cacheKeyWillBeUsed() و cacheWillUpdate() وcacheDidUpdate()
  • fetchAndCachePut: يتصل بـ fetch() ويشغّل cachePut() في الخلفية استجابةً لما ينشئه fetch().
  • ‫hasCallback: تأخذ دالة ردّ اتصال كإدخال وتُعرِض القيمة "صحيح" إذا كانت الاستراتيجية تتضمّن مكوّنًا إضافيًا واحدًا على الأقل مع دالة ردّ الاتصال المحدّدة.
  • runCallbacks: لتشغيل جميع عمليات استدعاء المكوّن الإضافي التي تتطابق مع اسم معيّن، بالترتيب، مع تمرير param object معيّن (مدمَج مع حالة المكوّن الإضافي الحالية) كوسيطة فقط.
  • ‫iterateCallbacks: تقبل دالة معاودة الاتصال وتُعرِض مجموعة قابلة للتكرار من دوال معاودة الاتصال المطابقة للمكونات الإضافية، حيث يتم لف كل دالة معاودة اتصال بحالة معالِج الأحداث الحالية (أي عند استدعاء كل دالة معاودة اتصال، سيتم دمج أي مَعلمة عنصر يتم تمريرها مع الحالة الحالية للإضافة).
  • waitUntil: تُضيف وعدًا إلى تعهدات تمديد مدة صلاحية الحدث المرتبط بالملف الشخصي الذي تتم معالجته (عادةً FetchEvent).
  • doneWaiting: تعرِض وعدًا يتم حلّه بعد اكتمال كل الوعود التي تم تمريرها إلى waitUntil().
  • destroy: يوقف تنفيذ الاستراتيجية ويحلّ على الفور أيّ تعهدات waitUntil() معلّقة.
.

استراتيجية "شبكة ذاكرة التخزين المؤقت المخصّصة"

يستند المثال التالي إلى cache-network-race من "Offline Cookbook" (الذي لا يوفّره Workbox)، ولكنه يتخطّى ذلك ويحدّث دائمًا ملف الادّخار بعد نجاح طلب الشبكة. هذا مثال على استراتيجية أكثر تعقيدًا تستخدِم إجراءات متعدّدة.

import {Strategy} from 'workbox-strategies';

class CacheNetworkRace extends Strategy {
  _handle(request, handler) {
    const fetchAndCachePutDone = handler.fetchAndCachePut(request);
    const cacheMatchDone = handler.cacheMatch(request);

    return new Promise((resolve, reject) => {
      fetchAndCachePutDone.then(resolve);
      cacheMatchDone.then(response => response && resolve(response));

      // Reject if both network and cache error or find no response.
      Promise.allSettled([fetchAndCachePutDone, cacheMatchDone]).then(
        results => {
          const [fetchAndCachePutResult, cacheMatchResult] = results;
          if (
            fetchAndCachePutResult.status === 'rejected' &&
            !cacheMatchResult.value
          ) {
            reject(fetchAndCachePutResult.reason);
          }
        }
      );
    });
  }
}

الاستخدام المتقدّم

إذا كنت تريد استخدام الاستراتيجيات في منطق حدث الجلب الخاص بك، يمكنك استخدام فئات الاستراتيجيات لتنفيذ طلب من خلال استراتيجية معيّنة.

على سبيل المثال، لاستخدام استراتيجية "البيانات القديمة أثناء إعادة التحقّق"، يمكنك إجراء ما يلي:

self.addEventListener('fetch', event => {
  const {request} = event;
  const url = new URL(request.url);

  if (url.origin === location.origin && url.pathname === '/') {
    event.respondWith(new StaleWhileRevalidate().handle({event, request}));
  }
});

يمكنك العثور على قائمة الصفوف المتاحة في مستندات مرجعية حول استراتيجيات workbox.

الأنواع

CacheFirst

تنفيذ استراتيجية طلبات الاستناد إلى ذاكرة التخزين المؤقت أولاً

تكون استراتيجية "التخزين المؤقت أولاً" مفيدة لمواد العرض التي تم إجراء مراجعات عليها، مثل عناوين URL مثل /styles/example.a8f5f1.css، لأنّه يمكن تخزينها مؤقتًا لفترات طويلة.

إذا تعذّر طلب الشبكة ولم يتم العثور على مطابقة في ذاكرة التخزين المؤقت، سيؤدي ذلك إلى طرح استثناء WorkboxError.

أماكن إقامة

  • constructor

    غير صالح

    تُنشئ مثيلًا جديدًا للاستراتيجية وتضبط جميع ملفّات خيار الموثَّقة على أنّها ملفّات مثيل علنية.

    ملاحظة: إذا كانت فئة استراتيجية مخصّصة تمدّد فئة Strategy الأساسية ولا تحتاج إلى أكثر من هذه السمات، لن تحتاج إلى تحديد ملف سازنده خاص بها.

    تبدو الدالة constructor على النحو التالي: 

    (options?: StrategyOptions) => {...}

  • cacheName

    سلسلة

  • fetchOptions

    RequestInit اختياري

  • matchOptions

    CacheQueryOptions اختياري

  • المكوّنات الإضافية

    WorkboxPlugin[]

  • ‎_awaitComplete

    غير صالح

    تبدو الدالة _awaitComplete على النحو التالي: 

    (responseDone: Promise<Response>, handler: StrategyHandler, request: Request, event: ExtendableEvent) => {...}

    • responseDone

      Promise<Response>

    • المعالج

      StrategyHandler

    • طلب

      الطلب

    • حدث

      ExtendableEvent

    • returns

      Promise<void>

  • _getResponse

    غير صالح

    تبدو الدالة _getResponse على النحو التالي: 

    (handler: StrategyHandler, request: Request, event: ExtendableEvent) => {...}

    • returns

      Promise<Response>

  • مؤشر

    غير صالح

    تنفيذ استراتيجية طلب وإرجاع Promise سيتم حلّه باستخدام Response، مع استدعاء جميع عمليات استدعاء المكوّنات الإضافية ذات الصلة

    عند تسجيل مثيل استراتيجية باستخدام Workbox workbox-routing.Route، يتم تلقائيًا استدعاء هذه الطريقة عند مطابقة المسار.

    بدلاً من ذلك، يمكن استخدام هذه الطريقة في FetchEvent مستمع مستقل من خلال تمريرها إلى event.respondWith().

    تبدو الدالة handle على النحو التالي: 

    (options: FetchEvent | HandlerCallbackOptions) => {...}

    • الخيارات

      FetchEvent | HandlerCallbackOptions

      FetchEvent أو عنصر يتضمّن السمات الواردة أدناه

    • returns

      Promise<Response>

  • handleAll

    غير صالح

    يشبه workbox-strategies.Strategy~handle، ولكن بدلاً من عرض Promise الذي يحلّ محل Response، فإنه سيعرض مجموعة من [response, done] الوعود، حيث يكون العنصر السابق (response) مساويًا لما يعرضه handle()، والعنصر الأخير هو وعد سيتم حلّه بعد اكتمال أي وعود تمت إضافتها إلى event.waitUntil() كجزء من تنفيذ الاستراتيجية.

    يمكنك انتظار done promise لضمان اكتمال أي عمل إضافي تنفّذه الاستراتيجية (عادةً ما يكون تخزين الإجابات مؤقتًا) بنجاح.

    تبدو الدالة handleAll على النحو التالي: 

    (options: FetchEvent | HandlerCallbackOptions) => {...}

    • الخيارات

      FetchEvent | HandlerCallbackOptions

      FetchEvent أو عنصر يتضمّن السمات الواردة أدناه

    • returns

      [Promise<Response>, Promise<void>]

      مجموعة من الوعود [response, done] التي يمكن استخدامها لتحديد وقت حلّ الاستجابة وكذلك وقت اكتمال المعالج لجميع أعماله

CacheOnly

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

يكون هذا الصف مفيدًا إذا كنت تريد الاستفادة من أي مكوّنات إضافية في Workbox.

في حال عدم تطابق ذاكرة التخزين المؤقت، سيؤدي ذلك إلى طرح استثناء WorkboxError.

أماكن إقامة

  • constructor

    غير صالح

    تُنشئ مثيلًا جديدًا للاستراتيجية وتضبط جميع ملفّات خيار الموثَّقة على أنّها ملفّات مثيل علنية.

    ملاحظة: إذا كانت فئة استراتيجية مخصّصة تمدّد فئة Strategy الأساسية ولا تحتاج إلى أكثر من هذه السمات، لن تحتاج إلى تحديد ملف سازنده خاص بها.

    تبدو الدالة constructor على النحو التالي: 

    (options?: StrategyOptions) => {...}

  • cacheName

    سلسلة

  • fetchOptions

    RequestInit اختياري

  • matchOptions

    CacheQueryOptions اختياري

  • المكوّنات الإضافية

    WorkboxPlugin[]

  • _awaitComplete

    غير صالح

    تبدو الدالة _awaitComplete على النحو التالي: 

    (responseDone: Promise<Response>, handler: StrategyHandler, request: Request, event: ExtendableEvent) => {...}

    • responseDone

      Promise<Response>

    • المعالج

      StrategyHandler

    • طلب

      الطلب

    • حدث

      ExtendableEvent

    • returns

      Promise<void>

  • _getResponse

    غير صالح

    تبدو الدالة _getResponse على النحو التالي: 

    (handler: StrategyHandler, request: Request, event: ExtendableEvent) => {...}

    • returns

      Promise<Response>

  • مؤشر

    غير صالح

    تنفيذ استراتيجية طلب وإرجاع Promise سيتم حلّه باستخدام Response، مع استدعاء جميع عمليات استدعاء المكوّنات الإضافية ذات الصلة

    عند تسجيل مثيل استراتيجية باستخدام Workbox workbox-routing.Route، يتم تلقائيًا استدعاء هذه الطريقة عند مطابقة المسار.

    بدلاً من ذلك، يمكن استخدام هذه الطريقة في FetchEvent مستمع مستقل من خلال تمريرها إلى event.respondWith().

    تبدو الدالة handle على النحو التالي: 

    (options: FetchEvent | HandlerCallbackOptions) => {...}

    • الخيارات

      FetchEvent | HandlerCallbackOptions

      FetchEvent أو عنصر يتضمّن السمات الواردة أدناه

    • returns

      Promise<Response>

  • handleAll

    غير صالح

    يشبه workbox-strategies.Strategy~handle، ولكن بدلاً من عرض Promise الذي يحلّ محل Response، فإنه سيعرض مجموعة من [response, done] الوعود، حيث يكون العنصر السابق (response) مساويًا لما يعرضه handle()، والعنصر الأخير هو وعد سيتم حلّه بعد اكتمال أي وعود تمت إضافتها إلى event.waitUntil() كجزء من تنفيذ الاستراتيجية.

    يمكنك انتظار done promise لضمان اكتمال أي عمل إضافي تنفّذه الاستراتيجية (عادةً ما يكون تخزين الإجابات مؤقتًا) بنجاح.

    تبدو الدالة handleAll على النحو التالي: 

    (options: FetchEvent | HandlerCallbackOptions) => {...}

    • الخيارات

      FetchEvent | HandlerCallbackOptions

      FetchEvent أو عنصر يتضمّن السمات الواردة أدناه

    • returns

      [Promise<Response>, Promise<void>]

      مجموعة من الوعود [response, done] التي يمكن استخدامها لتحديد وقت حلّ الاستجابة وكذلك وقت اكتمال المعالج لجميع أعماله

NetworkFirst

تنفيذ استراتيجية طلبات الشبكة أولاً

ستخزّن هذه الاستراتيجية تلقائيًا الردود التي تتضمّن رمز الحالة 200، بالإضافة إلى الردود غير الشفافة. الردود غير الشفافة هي طلبات من مصادر مختلفة لا يسمح فيها بالاستجابة باستخدام CORS.

إذا تعذّر طلب الشبكة ولم يتم العثور على مطابقة في ذاكرة التخزين المؤقت، سيؤدي ذلك إلى طرح استثناء WorkboxError.

أماكن إقامة

  • constructor

    غير صالح

    تبدو الدالة constructor على النحو التالي: 

    (options?: NetworkFirstOptions) => {...}

  • cacheName

    سلسلة

  • fetchOptions

    RequestInit اختياري

  • matchOptions

    CacheQueryOptions اختياري

  • المكوّنات الإضافية

    WorkboxPlugin[]

  • ‎_awaitComplete

    غير صالح

    تبدو الدالة _awaitComplete على النحو التالي: 

    (responseDone: Promise<Response>, handler: StrategyHandler, request: Request, event: ExtendableEvent) => {...}

    • responseDone

      Promise<Response>

    • المعالج

      StrategyHandler

    • طلب

      الطلب

    • حدث

      ExtendableEvent

    • returns

      Promise<void>

  • _getResponse

    غير صالح

    تبدو الدالة _getResponse على النحو التالي: 

    (handler: StrategyHandler, request: Request, event: ExtendableEvent) => {...}

    • returns

      Promise<Response>

  • مؤشر

    غير صالح

    تنفيذ استراتيجية طلب وإرجاع Promise سيتم حلّه باستخدام Response، مع استدعاء جميع عمليات استدعاء المكوّنات الإضافية ذات الصلة

    عند تسجيل مثيل استراتيجية باستخدام Workbox workbox-routing.Route، يتم تلقائيًا استدعاء هذه الطريقة عند مطابقة المسار.

    بدلاً من ذلك، يمكن استخدام هذه الطريقة في FetchEvent مستمع مستقل من خلال تمريرها إلى event.respondWith().

    تبدو الدالة handle على النحو التالي: 

    (options: FetchEvent | HandlerCallbackOptions) => {...}

    • الخيارات

      FetchEvent | HandlerCallbackOptions

      FetchEvent أو عنصر يتضمّن السمات الواردة أدناه

    • returns

      Promise<Response>

  • handleAll

    غير صالح

    يشبه workbox-strategies.Strategy~handle، ولكن بدلاً من عرض Promise الذي يحلّ محل Response، فإنه سيعرض مجموعة من [response, done] الوعود، حيث يكون العنصر السابق (response) مساويًا لما يعرضه handle()، والعنصر الأخير هو وعد سيتم حلّه بعد اكتمال أي وعود تمت إضافتها إلى event.waitUntil() كجزء من تنفيذ الاستراتيجية.

    يمكنك انتظار done promise لضمان اكتمال أي عمل إضافي تنفّذه الاستراتيجية (عادةً ما يكون تخزين الإجابات مؤقتًا) بنجاح.

    تبدو الدالة handleAll على النحو التالي: 

    (options: FetchEvent | HandlerCallbackOptions) => {...}

    • الخيارات

      FetchEvent | HandlerCallbackOptions

      FetchEvent أو عنصر يتضمّن السمات الواردة أدناه

    • returns

      [Promise<Response>, Promise<void>]

      مجموعة من الوعود [response, done] التي يمكن استخدامها لتحديد وقت حلّ الاستجابة وكذلك وقت اكتمال المعالج لجميع أعماله

NetworkFirstOptions

أماكن إقامة

  • cacheName

    سلسلة اختيارية

  • fetchOptions

    RequestInit اختياري

  • matchOptions

    CacheQueryOptions اختياري

  • networkTimeoutSeconds

    رقم اختياري

  • المكوّنات الإضافية

    WorkboxPlugin[] اختياري

NetworkOnly

تنفيذ استراتيجية طلبات على الشبكة فقط

يكون هذا الصف مفيدًا إذا كنت تريد الاستفادة من أي مكوّنات إضافية في Workbox.

إذا تعذّر طلب الشبكة، سيؤدي ذلك إلى طرح استثناء WorkboxError.

أماكن إقامة

  • constructor

    غير صالح

    تبدو الدالة constructor على النحو التالي: 

    (options?: NetworkOnlyOptions) => {...}

  • cacheName

    سلسلة

  • fetchOptions

    RequestInit اختياري

  • matchOptions

    CacheQueryOptions اختياري

  • المكوّنات الإضافية

    WorkboxPlugin[]

  • ‎_awaitComplete

    غير صالح

    تبدو الدالة _awaitComplete على النحو التالي: 

    (responseDone: Promise<Response>, handler: StrategyHandler, request: Request, event: ExtendableEvent) => {...}

    • responseDone

      Promise<Response>

    • المعالج

      StrategyHandler

    • طلب

      الطلب

    • حدث

      ExtendableEvent

    • returns

      Promise<void>

  • _getResponse

    غير صالح

    تبدو الدالة _getResponse على النحو التالي: 

    (handler: StrategyHandler, request: Request, event: ExtendableEvent) => {...}

    • returns

      Promise<Response>

  • مؤشر

    غير صالح

    تنفيذ استراتيجية طلب وإرجاع Promise سيتم حلّه باستخدام Response، مع استدعاء جميع عمليات استدعاء المكوّنات الإضافية ذات الصلة

    عند تسجيل مثيل استراتيجية باستخدام Workbox workbox-routing.Route، يتم تلقائيًا استدعاء هذه الطريقة عند مطابقة المسار.

    بدلاً من ذلك، يمكن استخدام هذه الطريقة في FetchEvent مستمع مستقل من خلال تمريرها إلى event.respondWith().

    تبدو الدالة handle على النحو التالي: 

    (options: FetchEvent | HandlerCallbackOptions) => {...}

    • الخيارات

      FetchEvent | HandlerCallbackOptions

      FetchEvent أو عنصر يتضمّن السمات الواردة أدناه

    • returns

      Promise<Response>

  • handleAll

    غير صالح

    يشبه workbox-strategies.Strategy~handle، ولكن بدلاً من عرض Promise الذي يحلّ محل Response، فإنه سيعرض مجموعة من [response, done] الوعود، حيث يكون العنصر السابق (response) مساويًا لما يعرضه handle()، والعنصر الأخير هو وعد سيتم حلّه بعد اكتمال أي وعود تمت إضافتها إلى event.waitUntil() كجزء من تنفيذ الاستراتيجية.

    يمكنك انتظار done promise لضمان اكتمال أي عمل إضافي تنفّذه الاستراتيجية (عادةً ما يكون تخزين الإجابات مؤقتًا) بنجاح.

    تبدو الدالة handleAll على النحو التالي: 

    (options: FetchEvent | HandlerCallbackOptions) => {...}

    • الخيارات

      FetchEvent | HandlerCallbackOptions

      FetchEvent أو عنصر يتضمّن السمات الواردة أدناه

    • returns

      [Promise<Response>, Promise<void>]

      مجموعة من الوعود [response, done] التي يمكن استخدامها لتحديد وقت حلّ الاستجابة وكذلك وقت اكتمال المعالج لجميع أعماله

NetworkOnlyOptions

أماكن إقامة

  • fetchOptions

    RequestInit اختياري

  • networkTimeoutSeconds

    رقم اختياري

  • المكوّنات الإضافية

    WorkboxPlugin[] اختياري

StaleWhileRevalidate

تنفيذ استراتيجية طلب stale-while-revalidate

يتم طلب الموارد من ذاكرة التخزين المؤقت والشبكة بشكل متزامن. ستستجيب الاستراتيجية بالإصدار المخزّن مؤقتًا إذا كان متاحًا، وإلا ستنتظر استجابة الشبكة. يتم تعديل ذاكرة التخزين المؤقت استنادًا إلى ردّ الشبكة مع كل طلب ناجح.

ستخزّن هذه الاستراتيجية تلقائيًا الردود التي تتضمّن رمز الحالة 200، بالإضافة إلى الردود غير الشفافة. الردود غير الشفافة هي طلبات من مصادر مختلفة لا يسمح فيها بالاستجابة باستخدام CORS.

إذا تعذّر طلب الشبكة ولم يتم العثور على مطابقة في ذاكرة التخزين المؤقت، سيؤدي ذلك إلى طرح استثناء WorkboxError.

أماكن إقامة

  • constructor

    غير صالح

    تبدو الدالة constructor على النحو التالي: 

    (options?: StrategyOptions) => {...}

  • cacheName

    سلسلة

  • fetchOptions

    RequestInit اختياري

  • matchOptions

    CacheQueryOptions اختياري

  • المكوّنات الإضافية

    WorkboxPlugin[]

  • ‎_awaitComplete

    غير صالح

    تبدو الدالة _awaitComplete على النحو التالي: 

    (responseDone: Promise<Response>, handler: StrategyHandler, request: Request, event: ExtendableEvent) => {...}

    • responseDone

      Promise<Response>

    • المعالج

      StrategyHandler

    • طلب

      الطلب

    • حدث

      ExtendableEvent

    • returns

      Promise<void>

  • _getResponse

    غير صالح

    تبدو الدالة _getResponse على النحو التالي: 

    (handler: StrategyHandler, request: Request, event: ExtendableEvent) => {...}

    • returns

      Promise<Response>

  • مؤشر

    غير صالح

    تنفيذ استراتيجية طلب وإرجاع Promise سيتم حلّه باستخدام Response، مع استدعاء جميع عمليات استدعاء المكوّنات الإضافية ذات الصلة

    عند تسجيل مثيل استراتيجية باستخدام Workbox workbox-routing.Route، يتم تلقائيًا استدعاء هذه الطريقة عند مطابقة المسار.

    بدلاً من ذلك، يمكن استخدام هذه الطريقة في FetchEvent مستمع مستقل من خلال تمريرها إلى event.respondWith().

    تبدو الدالة handle على النحو التالي: 

    (options: FetchEvent | HandlerCallbackOptions) => {...}

    • الخيارات

      FetchEvent | HandlerCallbackOptions

      FetchEvent أو عنصر يتضمّن السمات الواردة أدناه

    • returns

      Promise<Response>

  • handleAll

    غير صالح

    يشبه workbox-strategies.Strategy~handle، ولكن بدلاً من عرض Promise الذي يحلّ محل Response، فإنه سيعرض مجموعة من [response, done] الوعود، حيث يكون العنصر السابق (response) مساويًا لما يعرضه handle()، والعنصر الأخير هو وعد سيتم حلّه بعد اكتمال أي وعود تمت إضافتها إلى event.waitUntil() كجزء من تنفيذ الاستراتيجية.

    يمكنك انتظار done promise لضمان اكتمال أي عمل إضافي تنفّذه الاستراتيجية (عادةً ما يكون تخزين الإجابات مؤقتًا) بنجاح.

    تبدو الدالة handleAll على النحو التالي: 

    (options: FetchEvent | HandlerCallbackOptions) => {...}

    • الخيارات

      FetchEvent | HandlerCallbackOptions

      FetchEvent أو عنصر يتضمّن السمات الواردة أدناه

    • returns

      [Promise<Response>, Promise<void>]

      مجموعة من الوعود [response, done] التي يمكن استخدامها لتحديد وقت حلّ الاستجابة وكذلك وقت اكتمال المعالج لجميع أعماله

Strategy

فئة أساسية مجردة يجب أن تمتد منها جميع فئات الاستراتيجيات الأخرى:

أماكن إقامة

  • constructor

    غير صالح

    تُنشئ مثيلًا جديدًا للاستراتيجية وتضبط جميع ملفّات خيار الموثَّقة على أنّها ملفّات مثيل علنية.

    ملاحظة: إذا كانت فئة استراتيجية مخصّصة تمدّد فئة Strategy الأساسية ولا تحتاج إلى أكثر من هذه السمات، لن تحتاج إلى تحديد ملف سازنده خاص بها.

    تبدو الدالة constructor على النحو التالي: 

    (options?: StrategyOptions) => {...}

  • cacheName

    سلسلة

  • fetchOptions

    RequestInit اختياري

  • matchOptions

    CacheQueryOptions اختياري

  • المكوّنات الإضافية

    WorkboxPlugin[]

  • ‎_awaitComplete

    غير صالح

    تبدو الدالة _awaitComplete على النحو التالي: 

    (responseDone: Promise<Response>, handler: StrategyHandler, request: Request, event: ExtendableEvent) => {...}

    • responseDone

      Promise<Response>

    • المعالج

      StrategyHandler

    • طلب

      الطلب

    • حدث

      ExtendableEvent

    • returns

      Promise<void>

  • _getResponse

    غير صالح

    تبدو الدالة _getResponse على النحو التالي: 

    (handler: StrategyHandler, request: Request, event: ExtendableEvent) => {...}

    • returns

      Promise<Response>

  • _handle

    غير صالح

    تبدو الدالة _handle على النحو التالي: 

    (request: Request, handler: StrategyHandler) => {...}

    • returns

      Promise<Response>

  • مؤشر

    غير صالح

    تنفيذ استراتيجية طلب وإرجاع Promise سيتم حلّه باستخدام Response، مع استدعاء جميع عمليات استدعاء المكوّنات الإضافية ذات الصلة

    عند تسجيل مثيل استراتيجية باستخدام Workbox workbox-routing.Route، يتم تلقائيًا استدعاء هذه الطريقة عند مطابقة المسار.

    بدلاً من ذلك، يمكن استخدام هذه الطريقة في FetchEvent مستمع مستقل من خلال تمريرها إلى event.respondWith().

    تبدو الدالة handle على النحو التالي: 

    (options: FetchEvent | HandlerCallbackOptions) => {...}

    • الخيارات

      FetchEvent | HandlerCallbackOptions

      FetchEvent أو عنصر يتضمّن السمات الواردة أدناه

    • returns

      Promise<Response>

  • handleAll

    غير صالح

    يشبه workbox-strategies.Strategy~handle، ولكن بدلاً من عرض Promise الذي يحلّ محل Response، فإنه سيعرض مجموعة من [response, done] الوعود، حيث يكون العنصر السابق (response) مساويًا لما يعرضه handle()، والعنصر الأخير هو وعد سيتم حلّه بعد اكتمال أي وعود تمت إضافتها إلى event.waitUntil() كجزء من تنفيذ الاستراتيجية.

    يمكنك انتظار done promise لضمان اكتمال أي عمل إضافي تنفّذه الاستراتيجية (عادةً ما يكون تخزين الإجابات مؤقتًا) بنجاح.

    تبدو الدالة handleAll على النحو التالي: 

    (options: FetchEvent | HandlerCallbackOptions) => {...}

    • الخيارات

      FetchEvent | HandlerCallbackOptions

      FetchEvent أو عنصر يتضمّن السمات الواردة أدناه

    • returns

      [Promise<Response>, Promise<void>]

      مجموعة من الوعود [response, done] التي يمكن استخدامها لتحديد وقت حلّ الاستجابة وكذلك وقت اكتمال المعالج لجميع أعماله

StrategyHandler

فئة يتم إنشاؤها في كل مرة يُطلِق فيها مثيل Strategy workbox-strategies.Strategy~handle أو workbox-strategies.Strategy~handleAll التي تلفّ جميع إجراءات الجلب والذاكرة المؤقتة حول عمليات استدعاء المكوّنات الإضافية وتتتبّع وقت "انتهاء" الاستراتيجية (أي تم حلّ جميع event.waitUntil() promises المُضافة).

أماكن إقامة

  • constructor

    غير صالح

    تُنشئ هذه الوظيفة مثيلًا جديدًا مرتبطًا بالاستراتيجية والحدث المُرسَلين والمعنيّين بمعالجة الطلب.

    يُنشئ المُنشئ أيضًا الحالة التي سيتم تمريرها إلى كل من الإضافات التي تعالج هذا الطلب.

    تبدو الدالة constructor على النحو التالي: 

    (strategy: Strategy, options: HandlerCallbackOptions) => {...}

  • حدث

    ExtendableEvent

  • params

    أيّ اختياري

  • طلب

    الطلب

  • url

    عنوان URL اختياري

  • cacheMatch

    غير صالح

    تتطابق مع طلب من ذاكرة التخزين المؤقت (وتستدعي أيّ من طُرق callback الخاصة بالمكونات الإضافية السارية) باستخدام cacheName وmatchOptions وplugins المحدّدة في كائن الاستراتيجية.

    يتمّ استدعاء طرق دورة حياة المكوّن الإضافي التالية عند استخدام هذه الطريقة:

    • cacheKeyWillBeUsed()
    • cachedResponseWillBeUsed()

    تبدو الدالة cacheMatch على النحو التالي: 

    (key: RequestInfo) => {...}

    • مفتاح

      RequestInfo

      الطلب أو عنوان URL المُراد استخدامه كمفتاح ذاكرة التخزين المؤقت

    • returns

      Promise<Response>

      إجابة مطابقة، في حال توفّرها

  • cachePut

    غير صالح

    تضع هذه الطريقة زوج طلب/استجابة في ذاكرة التخزين المؤقت (وتستدعي أي مثيل من مثيلات طرق الاستدعاء الخاصة بالمكونات الإضافية) باستخدام cacheName وplugins المحدَّدين في عنصر الاستراتيجية.

    يتمّ استدعاء طرق دورة حياة المكوّن الإضافي التالية عند استخدام هذه الطريقة:

    • cacheKeyWillBeUsed()
    • cacheWillUpdate()
    • cacheDidUpdate()

    تبدو الدالة cachePut على النحو التالي: 

    (key: RequestInfo, response: Response) => {...}

    • مفتاح

      RequestInfo

      الطلب أو عنوان URL المراد استخدامه كمفتاح ذاكرة التخزين المؤقت

    • رد

      الرد

      الاستجابة لذاكرة التخزين المؤقت.

    • returns

      Promise&lt;boolean&gt;

      false إذا تسببت cacheWillUpdate في عدم تخزين الاستجابة مؤقتًا، وtrue بخلاف ذلك.

  • إتلافه

    غير صالح

    يوقف تنفيذ الاستراتيجية ويحلّ على الفور أيّ وعد waitUntil() معلّق.

    تبدو الدالة destroy على النحو التالي: 

    () => {...}

  • doneWaiting

    غير صالح

    تعرِض وعدًا يتم حلّه بعد تسوية جميع الوعود التي تم تمريرها إلى workbox-strategies.StrategyHandler~waitUntil.

    ملاحظة: يجب توجيه أي عمل تم تنفيذه بعد تسوية doneWaiting() يدويًا إلى طريقة waitUntil() للحدث (وليس إلى طريقة waitUntil() لمعالج هذا الحدث)، وإلا قد يتم إنهاء سلسلة مهام مشغّل الخدمات قبل اكتمال عملك.

    تبدو الدالة doneWaiting على النحو التالي: 

    () => {...}

    • returns

      Promise<void>

  • استرجاع

    غير صالح

    تُستخدَم هذه الوظيفة لجلب طلب معيّن (وتنشيط أيّ من طرق callback المتوافقة مع المكوّن الإضافي) باستخدام fetchOptions (لطلبات التنقّل) و plugins المحدّدَين في عنصر Strategy.

    يتمّ استدعاء طرق دورة حياة المكوّن الإضافي التالية عند استخدام هذه الطريقة:

    • requestWillFetch()
    • fetchDidSucceed()
    • fetchDidFail()

    تبدو الدالة fetch على النحو التالي: 

    (input: RequestInfo) => {...}

    • الإدخال

      RequestInfo

      عنوان URL أو طلب الجلب

    • returns

      Promise<Response>

  • fetchAndCachePut

    غير صالح

    يتصل this.fetch() بتطبيق this.cachePut() و (في الخلفية) يشغّل this.cachePut() على الردّ الذي أنشأه this.fetch().

    يؤدي طلب this.cachePut() تلقائيًا إلى استدعاء this.waitUntil()، لذا ليس عليك طلب waitUntil() يدويًا في الحدث.

    تبدو الدالة fetchAndCachePut على النحو التالي: 

    (input: RequestInfo) => {...}

    • الإدخال

      RequestInfo

      الطلب أو عنوان URL المطلوب جلبه وتخزينه مؤقتًا.

    • returns

      Promise<Response>

  • getCacheKey

    غير صالح

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

    تبدو الدالة getCacheKey على النحو التالي: 

    (request: Request, mode: "read" 
          | "write" 
         ) => {...}

    • طلب

      الطلب

    • الوضع

      "read"
       | "write"

    • returns

      Promise<Request>

  • hasCallback

    غير صالح

    تعرِض هذه الدالة القيمة true إذا كانت الاستراتيجية تحتوي على مكوّن إضافي واحد على الأقل يحتوي على دالّة callback المحدّدة.

    تبدو الدالة hasCallback على النحو التالي: 

    (name: C) => {...}

    • الاسم

      C

      اسم طلب إعادة الاتصال المطلوب البحث عنه.

    • returns

      قيمة منطقية

  • iterateCallbacks

    غير صالح

    يقبل دالة استدعاء وتُرجع مجموعة قابلة للتكرار من دوال استدعاء المكوّن الإضافي المطابقة، حيث يتم لف كل دالة استدعاء بحالة معالِج الحدث الحالية (أي عند استدعاء كل دالة استدعاء، سيتم دمج أي مَعلمة عنصر يتم تمريرها مع الحالة الحالية للمكوّن الإضافي).

    تبدو الدالة iterateCallbacks على النحو التالي: 

    (name: C) => {...}

    • الاسم

      C

      اسم دالة الاستدعاء المطلوب تنفيذها

    • returns

      Generator<NonNullable<indexedAccess>anyunknown>

  • runCallbacks

    غير صالح

    تُشغِّل جميع عمليات استدعاء المكوّن الإضافي التي تتطابق مع الاسم المحدّد، بالترتيب، مع تمرير ملفparam.js المحدّد (المدمج مع حالة المكوّن الإضافي الحالية) كوسيطة الوحيدة.

    ملاحظة: بما أنّ هذه الطريقة تشغّل جميع الإضافات، فهي غير مناسبة للحالات التي يجب فيها تطبيق القيمة المعروضة في دالة الاستدعاء قبل استدعاء دالة الاستدعاء التالية. اطّلِع على القسم workbox-strategies.StrategyHandler#iterateCallbacks أدناه لمعرفة كيفية التعامل مع هذه الحالة.

    تبدو الدالة runCallbacks على النحو التالي: 

    (name: C, param: Omit<indexedAccess"state" 
         >) => {...}

    • الاسم

      C

      اسم دالة الاستدعاء المطلوب تنفيذها في كل مكوّن إضافي.

    • param

      Omit<indexedAccess"state"
      >

      العنصر الذي سيتم تمريره كأول مَعلمة (والوحيدة) عند تنفيذ كل ردّ اتصال سيتم دمج هذا العنصر مع حالة المكوّن الإضافي الحالية قبل تنفيذ دالة الاستدعاء.

    • returns

      Promise<void>

  • waitUntil

    غير صالح

    تُضيف وعدًا إلى [extend lifetime promises]https://w3c.github.io/ServiceWorker/#extendableevent-extend-lifetime-promises للحدث المرتبط بالطلب الذي تتم معالجته (عادةً هو FetchEvent).

    ملاحظة: يمكنك الانتظار workbox-strategies.StrategyHandler~doneWaiting لمعرفة وقت تسوية جميع التعهدات المُضافة.

    تبدو الدالة waitUntil على النحو التالي: 

    (promise: Promise<T>) => {...}

    • وعد

      Promise<T>

      وعد بإضافة مدة إضافية إلى المدة التي وعد بها العميل للحدث الذي أدّى إلى تقديم الطلب

    • returns

      Promise<T>

StrategyOptions

أماكن إقامة

  • cacheName

    سلسلة اختيارية

  • fetchOptions

    RequestInit اختياري

  • matchOptions

    CacheQueryOptions اختياري

  • المكوّنات الإضافية

    WorkboxPlugin[] اختياري