אסטרטגיות של ארגזי עבודה

כשהוצגו לראשונה שירותי ה-Worker, הופיעה קבוצה של אסטרטגיות נפוצות לשמירת נתונים במטמון. אסטרטגיית שמירת מטמון היא דפוס שקובע איך עובד שירות לשירות (service worker) יוצר תשובה אחרי שהוא מקבל אירוע אחזור.

workbox-strategies מספק את אסטרטגיות האחסון השכיחות ביותר במטמון, כך שקל להחיל אותן ב-service worker.

לא נרחיב על שיטות שלא נתמכות ב-Workbox, אבל תוכלו לקרוא מידע נוסף במדריך Offline Cookbook.

שימוש באסטרטגיות

בדוגמאות הבאות נסביר איך להשתמש באסטרטגיות האחסון במטמון של 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());

מטמון בלבד

האסטרטגיה cache only מבטיחה שהתשובות יתקבלו מהמטמון. האפשרות הזו פחות נפוצה ב-Workbox, אבל היא יכולה להיות שימושית אם יש לכם שלב ייעודי של שמירת פריטים במטמון מראש.

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

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

הגדרת אסטרטגיות

בכל השיטות אפשר להגדיר:

• השם של המטמון שבו נעשה שימוש בשיטה.
• הגבלות על תפוגת התוקף של נתוני מטמון לשימוש בשיטה.
• מערך של יישומי פלאגין שקריאות ל-methods של מחזור החיים שלהם יתבצעו בזמן אחזור הבקשה ושמירתה במטמון.

שינוי המטמון שבו נעשה שימוש באסטרטגיה

כדי לשנות את שיטת האחסון במטמון שבה נעשה שימוש, מציינים שם של מטמון. האפשרות הזו שימושית אם רוצים להפריד את הנכסים כדי לעזור בניפוי באגים.

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

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

שימוש בפלאגינים

Workbox כולל קבוצה של יישומי פלאגין שאפשר להשתמש בהם עם השיטות האלה.

• workbox-background-sync
• workbox-broadcast-update
• workbox-cacheable-response
• workbox-expiration
• workbox-range-requests

כדי להשתמש בכל אחד מהפלאגינים האלה (או בפלאגין בהתאמה אישית), פשוט מעבירים את המופעים לאפשרות 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, תוך הפעלה של כל הקריאות החזרה (callbacks) הרלוונטיות של הפלאגין.
• 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: הפונקציה מקבלת קריאה חוזרת (callback) כקלט ומחזירה true אם לשיטה יש לפחות פלאגין אחד עם הקריאה החוזרת (callback) שצוינה.
• runCallbacks: הפונקציה מפעילה את כל הפונקציות החוזרות של הפלאגין שתואמות לשם נתון, לפי הסדר, ומעבירה אובייקט פרמטר נתון (הממוזג עם מצב הפלאגין הנוכחי) בתור הארגומנט היחיד.
• iterateCallbacks: מקבלת פונקציית קריאה חוזרת ומחזירה אוסף של פונקציות קריאה חוזרת תואמות של הפלאגין, כאשר כל פונקציית קריאה חוזרת עטופה במצב הנוכחי של הטיפול (כלומר, כשאתם קוראים לכל פונקציית קריאה חוזרת, פרמטר האובייקט שאתם מעבירים למעשה ימוזג עם המצב הנוכחי של הפלאגין).
• waitUntil: הוספת הבטחה להבטחות להארכת משך החיים של האירוע שמשויך לבקשה שמטופלת (בדרך כלל FetchEvent).
• doneWaiting: הפונקציה מחזירה הבטחה (promise) שמתבצעת ברגע שכל ההבטחות שהועברו ל-waitUntil() מתבצעות.
• destroy: הפסקת ההרצה של האסטרטגיה ופתרוך מיידי של כל ההתחייבויות waitUntil() בהמתנה.

הערה: בקוד המקור של StrategyHandler מפורטים כל הפרמטרים שכל פעולה מקבלת

אסטרטגיית מרוץ של רשת מטמון בהתאמה אישית

הדוגמה הבאה מבוססת על 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-strategies.

סוגים

CacheFirst

הטמעה של אסטרטגיית בקשות cache-first.

אסטרטגיית 'מטמון קודם' שימושית לנכסים ששונו, כמו כתובות URL כמו /styles/example.a8f5f1.css, כי אפשר לשמור אותם במטמון לפרקי זמן ארוכים.

אם הבקשה לרשת נכשלת ואין התאמה במטמון, תופיע החרגה מסוג WorkboxError.

מאפיינים

• constructor

  void

  יצירת מכונה חדשה של האסטרטגיה והגדרה של כל מאפייני האפשרויות המתועדים כמאפייני מכונה ציבוריים.

  הערה: אם סוג אסטרטגיה בהתאמה אישית מרחיב את סוג האסטרטגיה הבסיסי ולא צריך יותר מהמאפיינים האלה, אין צורך להגדיר בונה משלו.

  הפונקציה constructor נראית כך:

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

  • אפשרויות

    StrategyOptions אופציונלי

  • החזרות

    CacheFirst

• cacheName

  מחרוזת

• fetchOptions

  RequestInit אופציונלי

• matchOptions

  CacheQueryOptions אופציונלי

• פלאגינים

  WorkboxPlugin[]

• ‎_awaitComplete

  void

  הפונקציה _awaitComplete נראית כך:

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

  • responseDone

    Promise<Response>

  • טיפול

    StrategyHandler

  • בקשה

    בקשה

  • אירוע

    ExtendableEvent

  • החזרות

    Promise<void>

• _getResponse

  void

  הפונקציה _getResponse נראית כך:

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

  • טיפול

    StrategyHandler

  • בקשה

    בקשה

  • אירוע

    ExtendableEvent

  • החזרות

    Promise<Response>

• נקודת אחיזה

  void

  ביצוע אסטרטגיית בקשה והחזרת Promise שייפתר עם Response, ויבצע את כל קריאות החזרה (callbacks) הרלוונטיות של הפלאגין.

  כשמכשיר של אסטרטגיה רשום ב-Workbox‏ workbox-routing.Route, השיטה הזו נקראת באופן אוטומטי כשהמסלול תואם.

  לחלופין, אפשר להשתמש בשיטה הזו במאזין FetchEvent עצמאי על ידי העברה שלה ל-event.respondWith().

  הפונקציה handle נראית כך:

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

  • אפשרויות

    FetchEvent | HandlerCallbackOptions

    FetchEvent או אובייקט עם המאפיינים שמפורטים בהמשך.

  • החזרות

    Promise<Response>

• handleAll

  void

  דומה ל-workbox-strategies.Strategy~handle, אבל במקום להחזיר רק Promise שמתבצעת בו פתרון ל-Response, הוא מחזיר קבוצה של הבטחות [response, done], כאשר הראשונה (response) זהה למה ש-handle() מחזיר, והאחרונה היא הבטחה שתתבצע ברגע שההבטחות שנוספו ל-event.waitUntil() כחלק מהפעלת האסטרטגיה יסתיימו.

  אפשר להמתין להבטחה done כדי לוודא שכל העבודה הנוספת שהשיטה מבצעת (בדרך כלל שמירת תשובות במטמון) הושלמה בהצלחה.

  הפונקציה handleAll נראית כך:

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

  • אפשרויות

    FetchEvent | HandlerCallbackOptions

    FetchEvent או אובייקט עם המאפיינים שמפורטים בהמשך.

  • החזרות

    [Promise<Response>, Promise<void>]

    קבוצה של שתי הבטחות [response, done] שאפשר להשתמש בהן כדי לקבוע מתי התשובה מתקבלת, וכדי לקבוע מתי הטיפול הושלם.

CacheOnly

הטמעה של אסטרטגיית בקשות cache-only.

הסיווג הזה שימושי אם רוצים להשתמש ביישומי פלאגין של Workbox.

אם לא נמצאה התאמה במטמון, תופיע חריגה מסוג WorkboxError.

מאפיינים

• constructor

  void

  יצירת מכונה חדשה של האסטרטגיה והגדרה של כל מאפייני האפשרויות המתועדים כמאפייני מכונה ציבוריים.

  הערה: אם סוג אסטרטגיה בהתאמה אישית מרחיב את סוג האסטרטגיה הבסיסי ולא צריך יותר מהמאפיינים האלה, אין צורך להגדיר בונה משלו.

  הפונקציה constructor נראית כך:

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

  • אפשרויות

    StrategyOptions אופציונלי

  • החזרות

    CacheOnly

• cacheName

  מחרוזת

• fetchOptions

  RequestInit אופציונלי

• matchOptions

  CacheQueryOptions אופציונלי

• פלאגינים

  WorkboxPlugin[]

• ‎_awaitComplete

  void

  הפונקציה _awaitComplete נראית כך:

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

  • responseDone

    Promise<Response>

  • טיפול

    StrategyHandler

  • בקשה

    בקשה

  • אירוע

    ExtendableEvent

  • החזרות

    Promise<void>

• _getResponse

  void

  הפונקציה _getResponse נראית כך:

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

  • טיפול

    StrategyHandler

  • בקשה

    בקשה

  • אירוע

    ExtendableEvent

  • החזרות

    Promise<Response>

• נקודת אחיזה

  void

  ביצוע אסטרטגיית בקשה והחזרת Promise שייפתר עם Response, ויבצע את כל קריאות החזרה (callbacks) הרלוונטיות של הפלאגין.

  כשמכשיר של אסטרטגיה רשום ב-Workbox‏ workbox-routing.Route, השיטה הזו נקראת באופן אוטומטי כשהמסלול תואם.

  לחלופין, אפשר להשתמש בשיטה הזו במאזין FetchEvent עצמאי על ידי העברה שלה ל-event.respondWith().

  הפונקציה handle נראית כך:

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

  • אפשרויות

    FetchEvent | HandlerCallbackOptions

    FetchEvent או אובייקט עם המאפיינים שמפורטים בהמשך.

  • החזרות

    Promise<Response>

• handleAll

  void

  דומה ל-workbox-strategies.Strategy~handle, אבל במקום להחזיר רק Promise שמתבצעת בו פתרון ל-Response, הוא מחזיר קבוצה של הבטחות [response, done], כאשר הראשונה (response) זהה למה ש-handle() מחזיר, והאחרונה היא הבטחה שתתבצע ברגע שההבטחות שנוספו ל-event.waitUntil() כחלק מהפעלת האסטרטגיה יסתיימו.

  אפשר להמתין להבטחה done כדי לוודא שכל העבודה הנוספת שהשיטה מבצעת (בדרך כלל שמירת תשובות במטמון) הושלמה בהצלחה.

  הפונקציה handleAll נראית כך:

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

  • אפשרויות

    FetchEvent | HandlerCallbackOptions

    FetchEvent או אובייקט עם המאפיינים שמפורטים בהמשך.

  • החזרות

    [Promise<Response>, Promise<void>]

    קבוצה של שתי הבטחות [response, done] שאפשר להשתמש בהן כדי לקבוע מתי התשובה מתקבלת, וגם מתי הטיפול הושלם.

NetworkFirst

הטמעה של שיטת בקשות רשת קודם.

כברירת מחדל, השיטה הזו תשמור בתגובה את התשובות עם קוד הסטטוס 200 וגם תשובות אטומות. תגובות אטומות הן בקשות ממקורות שונים שבהן התגובה לא תומכת ב-CORS.

אם הבקשה לרשת נכשלת ואין התאמה במטמון, תופיע החרגה מסוג WorkboxError.

מאפיינים

• constructor

  void

  הפונקציה constructor נראית כך:

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

  • אפשרויות

    NetworkFirstOptions אופציונלי

  • החזרות

    NetworkFirst

• cacheName

  מחרוזת

• fetchOptions

  RequestInit אופציונלי

• matchOptions

  CacheQueryOptions אופציונלי

• פלאגינים

  WorkboxPlugin[]

• ‎_awaitComplete

  void

  הפונקציה _awaitComplete נראית כך:

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

  • responseDone

    Promise<Response>

  • טיפול

    StrategyHandler

  • בקשה

    בקשה

  • אירוע

    ExtendableEvent

  • החזרות

    Promise<void>

• _getResponse

  void

  הפונקציה _getResponse נראית כך:

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

  • טיפול

    StrategyHandler

  • בקשה

    בקשה

  • אירוע

    ExtendableEvent

  • החזרות

    Promise<Response>

• נקודת אחיזה

  void

  ביצוע אסטרטגיית בקשה והחזרת Promise שייפתר עם Response, ויבצע את כל קריאות החזרה (callbacks) הרלוונטיות של הפלאגין.

  כשמכשיר של אסטרטגיה רשום ב-Workbox‏ workbox-routing.Route, השיטה הזו נקראת באופן אוטומטי כשהמסלול תואם.

  לחלופין, אפשר להשתמש בשיטה הזו במאזין FetchEvent עצמאי על ידי העברה שלה ל-event.respondWith().

  הפונקציה handle נראית כך:

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

  • אפשרויות

    FetchEvent | HandlerCallbackOptions

    FetchEvent או אובייקט עם המאפיינים שמפורטים בהמשך.

  • החזרות

    Promise<Response>

• handleAll

  void

  דומה ל-workbox-strategies.Strategy~handle, אבל במקום להחזיר רק Promise שמתבצעת בו פתרון ל-Response, הוא מחזיר קבוצה של הבטחות [response, done], כאשר הראשונה (response) זהה למה ש-handle() מחזיר, והאחרונה היא הבטחה שתתבצע ברגע שההבטחות שנוספו ל-event.waitUntil() כחלק מהפעלת האסטרטגיה יסתיימו.

  אפשר להמתין להבטחה done כדי לוודא שכל העבודה הנוספת שהשיטה מבצעת (בדרך כלל שמירת תשובות במטמון) הושלמה בהצלחה.

  הפונקציה handleAll נראית כך:

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

  • אפשרויות

    FetchEvent | HandlerCallbackOptions

    FetchEvent או אובייקט עם המאפיינים שמפורטים בהמשך.

  • החזרות

    [Promise<Response>, Promise<void>]

    קבוצה של שתי הבטחות [response, done] שאפשר להשתמש בהן כדי לקבוע מתי התשובה מתקבלת, וכדי לקבוע מתי הטיפול הושלם.

NetworkFirstOptions

מאפיינים

• cacheName

  מחרוזת אופציונלי

• fetchOptions

  RequestInit אופציונלי

• matchOptions

  CacheQueryOptions אופציונלי

• networkTimeoutSeconds

  מספר אופציונלי

• פלאגינים

  WorkboxPlugin[] אופציונלי

NetworkOnly

הטמעה של אסטרטגיית בקשות לרשת בלבד.

הסיווג הזה שימושי אם רוצים להשתמש ביישומי פלאגין של Workbox.

אם בקשת הרשת נכשלת, תופיע חריגה מסוג WorkboxError.

מאפיינים

• constructor

  void

  הפונקציה constructor נראית כך:

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

  • אפשרויות

    NetworkOnlyOptions אופציונלי

  • החזרות

    NetworkOnly

• cacheName

  מחרוזת

• fetchOptions

  RequestInit אופציונלי

• matchOptions

  CacheQueryOptions אופציונלי

• פלאגינים

  WorkboxPlugin[]

• ‎_awaitComplete

  void

  הפונקציה _awaitComplete נראית כך:

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

  • responseDone

    Promise<Response>

  • טיפול

    StrategyHandler

  • בקשה

    בקשה

  • אירוע

    ExtendableEvent

  • החזרות

    Promise<void>

• _getResponse

  void

  הפונקציה _getResponse נראית כך:

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

  • טיפול

    StrategyHandler

  • בקשה

    בקשה

  • אירוע

    ExtendableEvent

  • החזרות

    Promise<Response>

• נקודת אחיזה

  void

  ביצוע אסטרטגיית בקשה והחזרת Promise שייפתר עם Response, ויבצע את כל קריאות החזרה (callbacks) הרלוונטיות של הפלאגין.

  כשמכשיר של אסטרטגיה רשום ב-Workbox‏ workbox-routing.Route, השיטה הזו נקראת באופן אוטומטי כשהמסלול תואם.

  לחלופין, אפשר להשתמש בשיטה הזו במאזין FetchEvent עצמאי על ידי העברה שלה ל-event.respondWith().

  הפונקציה handle נראית כך:

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

  • אפשרויות

    FetchEvent | HandlerCallbackOptions

    FetchEvent או אובייקט עם המאפיינים שמפורטים בהמשך.

  • החזרות

    Promise<Response>

• handleAll

  void

  דומה ל-workbox-strategies.Strategy~handle, אבל במקום להחזיר רק Promise שמתבצעת בו פתרון ל-Response, הוא מחזיר קבוצה של הבטחות [response, done], כאשר הראשונה (response) זהה למה ש-handle() מחזיר, והאחרונה היא הבטחה שתתבצע ברגע שההבטחות שנוספו ל-event.waitUntil() כחלק מהפעלת האסטרטגיה יסתיימו.

  אפשר להמתין להבטחה done כדי לוודא שכל העבודה הנוספת שהשיטה מבצעת (בדרך כלל שמירת תשובות במטמון) הושלמה בהצלחה.

  הפונקציה handleAll נראית כך:

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

  • אפשרויות

    FetchEvent | HandlerCallbackOptions

    FetchEvent או אובייקט עם המאפיינים שמפורטים בהמשך.

  • החזרות

    [Promise<Response>, Promise<void>]

    קבוצה של שתי הבטחות [response, done] שאפשר להשתמש בהן כדי לקבוע מתי התשובה מתקבלת, וכדי לקבוע מתי הטיפול הושלם.

NetworkOnlyOptions

מאפיינים

• fetchOptions

  RequestInit אופציונלי

• networkTimeoutSeconds

  מספר אופציונלי

• פלאגינים

  WorkboxPlugin[] אופציונלי

StaleWhileRevalidate

הטמעה של אסטרטגיית בקשות stale-while-revalidate.

הבקשות למשאבים נשלחות במקביל מהמטמון ומהרשת. אם הגרסה ששמורה במטמון זמינה, היא תהיה התשובה של האסטרטגיה. אחרת, המערכת תמתין לתשובה מהרשת. המטמון מתעדכן בתשובה מהרשת בכל בקשה מוצלחת.

כברירת מחדל, השיטה הזו תשמור בתגובה את התשובות עם קוד הסטטוס 200 וגם תשובות אטומות. תגובות אטומות הן בקשות ממקורות שונים שבהן התגובה לא תומכת ב-CORS.

אם הבקשה לרשת נכשלת ואין התאמה במטמון, תופיע החרגה מסוג WorkboxError.

מאפיינים

• constructor

  void

  הפונקציה constructor נראית כך:

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

  • אפשרויות

    StrategyOptions אופציונלי

  • החזרות

    StaleWhileRevalidate

• cacheName

  מחרוזת

• fetchOptions

  RequestInit אופציונלי

• matchOptions

  CacheQueryOptions אופציונלי

• פלאגינים

  WorkboxPlugin[]

• ‎_awaitComplete

  void

  הפונקציה _awaitComplete נראית כך:

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

  • responseDone

    Promise<Response>

  • טיפול

    StrategyHandler

  • בקשה

    בקשה

  • אירוע

    ExtendableEvent

  • החזרות

    Promise<void>

• _getResponse

  void

  הפונקציה _getResponse נראית כך:

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

  • טיפול

    StrategyHandler

  • בקשה

    בקשה

  • אירוע

    ExtendableEvent

  • החזרות

    Promise<Response>

• נקודת אחיזה

  void

  ביצוע אסטרטגיית בקשה והחזרת Promise שייפתר עם Response, ויבצע את כל קריאות החזרה (callbacks) הרלוונטיות של הפלאגין.

  כשמכשיר של אסטרטגיה רשום ב-Workbox‏ workbox-routing.Route, השיטה הזו נקראת באופן אוטומטי כשהמסלול תואם.

  לחלופין, אפשר להשתמש בשיטה הזו במאזין FetchEvent עצמאי על ידי העברה שלה ל-event.respondWith().

  הפונקציה handle נראית כך:

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

  • אפשרויות

    FetchEvent | HandlerCallbackOptions

    FetchEvent או אובייקט עם המאפיינים שמפורטים בהמשך.

  • החזרות

    Promise<Response>

• handleAll

  void

  דומה ל-workbox-strategies.Strategy~handle, אבל במקום להחזיר רק Promise שמתבצעת בו פתרון ל-Response, הוא מחזיר קבוצה של הבטחות [response, done], כאשר הראשונה (response) זהה למה ש-handle() מחזיר, והאחרונה היא הבטחה שתתבצע ברגע שההבטחות שנוספו ל-event.waitUntil() כחלק מהפעלת האסטרטגיה יסתיימו.

  אפשר להמתין להבטחה done כדי לוודא שכל העבודה הנוספת שהשיטה מבצעת (בדרך כלל שמירת תשובות במטמון) הושלמה בהצלחה.

  הפונקציה handleAll נראית כך:

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

  • אפשרויות

    FetchEvent | HandlerCallbackOptions

    FetchEvent או אובייקט עם המאפיינים שמפורטים בהמשך.

  • החזרות

    [Promise<Response>, Promise<void>]

    קבוצה של שתי הבטחות [response, done] שאפשר להשתמש בהן כדי לקבוע מתי התשובה מתקבלת, וגם מתי הטיפול הושלם.

Strategy

כיתה בסיסית מופשטת שכל שאר כיתות האסטרטגיות צריכות להרחיב ממנה:

מאפיינים

• constructor

  void

  יצירת מכונה חדשה של האסטרטגיה והגדרה של כל מאפייני האפשרויות המתועדים כמאפייני מכונה ציבוריים.

  הערה: אם סוג אסטרטגיה בהתאמה אישית מרחיב את סוג האסטרטגיה הבסיסי ולא צריך יותר מהמאפיינים האלה, אין צורך להגדיר בונה משלו.

  הפונקציה constructor נראית כך:

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

  • אפשרויות

    StrategyOptions אופציונלי

  • החזרות

    האסטרטגיה

• cacheName

  מחרוזת

• fetchOptions

  RequestInit אופציונלי

• matchOptions

  CacheQueryOptions אופציונלי

• פלאגינים

  WorkboxPlugin[]

• ‎_awaitComplete

  void

  הפונקציה _awaitComplete נראית כך:

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

  • responseDone

    Promise<Response>

  • טיפול

    StrategyHandler

  • בקשה

    בקשה

  • אירוע

    ExtendableEvent

  • החזרות

    Promise<void>

• _getResponse

  void

  הפונקציה _getResponse נראית כך:

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

  • טיפול

    StrategyHandler

  • בקשה

    בקשה

  • אירוע

    ExtendableEvent

  • החזרות

    Promise<Response>

• _handle

  void

  הפונקציה _handle נראית כך:

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

  • בקשה

    בקשה

  • טיפול

    StrategyHandler

  • החזרות

    Promise<Response>

• נקודת אחיזה

  void

  ביצוע אסטרטגיית בקשה והחזרת Promise שייפתר עם Response, ויבצע את כל קריאות החזרה (callbacks) הרלוונטיות של הפלאגין.

  כשמכשיר של אסטרטגיה רשום ב-Workbox‏ workbox-routing.Route, השיטה הזו נקראת באופן אוטומטי כשהמסלול תואם.

  לחלופין, אפשר להשתמש בשיטה הזו במאזין FetchEvent עצמאי על ידי העברה שלה ל-event.respondWith().

  הפונקציה handle נראית כך:

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

  • אפשרויות

    FetchEvent | HandlerCallbackOptions

    FetchEvent או אובייקט עם המאפיינים שמפורטים בהמשך.

  • החזרות

    Promise<Response>

• handleAll

  void

  דומה ל-workbox-strategies.Strategy~handle, אבל במקום להחזיר רק Promise שמתבצעת בו פתרון ל-Response, הוא מחזיר קבוצה של הבטחות [response, done], כאשר הראשונה (response) זהה למה ש-handle() מחזיר, והאחרונה היא הבטחה שתתבצע ברגע שההבטחות שנוספו ל-event.waitUntil() כחלק מהפעלת האסטרטגיה יסתיימו.

  אפשר להמתין להבטחה done כדי לוודא שכל העבודה הנוספת שהשיטה מבצעת (בדרך כלל שמירת תשובות במטמון) הושלמה בהצלחה.

  הפונקציה handleAll נראית כך:

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

  • אפשרויות

    FetchEvent | HandlerCallbackOptions

    FetchEvent או אובייקט עם המאפיינים שמפורטים בהמשך.

  • החזרות

    [Promise<Response>, Promise<void>]

    קבוצה של שתי הבטחות [response, done] שאפשר להשתמש בהן כדי לקבוע מתי התשובה מתקבלת, וגם מתי הטיפול הושלם.

StrategyHandler

כיתה שנוצרת בכל פעם שמופיעה קריאה ל-workbox-strategies.Strategy~handle או ל-workbox-strategies.Strategy~handleAll במופע של Strategy. הכיתה עוטפת את כל פעולות האחזור והאחסון במטמון בקריאות חזרה (callbacks) של הפלאגין, ומעקב אחרי המועד שבו האסטרטגיה 'סתיימה' (כלומר, כל ה-promises של event.waitUntil() שנוספו נפתרו).

מאפיינים

• constructor

  void

  יצירת מכונה חדשה שמשויכת לאסטרטגיה ולאירוע שהועברו, והיא זו שתטפל בבקשה.

  בנוסף, ה-constructor מאתחלל את המצב שיוענק לכל אחד מהפלאגינים שמטפלים בבקשה הזו.

  הפונקציה constructor נראית כך:

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

  • אסטרטגיה

    האסטרטגיה

  • אפשרויות

    HandlerCallbackOptions

  • החזרות

    StrategyHandler

• אירוע

  ExtendableEvent

• params

  כל אופציונלי

• בקשה

  בקשה

• כתובת אתר

  כתובת URL אופציונלית

• cacheMatch

  void

  התאמה של בקשה מהמטמון (והפעלה של שיטות ה-callback הרלוונטיות של הפלאגין) באמצעות הערכים של cacheName,‏ matchOptions ו-plugins שמוגדרים באובייקט האסטרטגיה.

  כשמשתמשים בשיטה הזו, מתבצעת קריאה לשיטות הבאות של מחזור החיים של הפלאגין:

  • cacheKeyWillBeUsed()
  • cachedResponseWillBeUsed()

  הפונקציה cacheMatch נראית כך:

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

  • מקש

    RequestInfo

    הבקשה או כתובת ה-URL שישמשו כמפתח למטמון.

  • החזרות

    Promise<Response>

    תגובה תואמת, אם נמצאה.

• cachePut

  void

  שומרת זוג בקשה/תגובה במטמון (ומפעילה את כל שיטות ה-callback הרלוונטיות של הפלאגין) באמצעות cacheName ו-plugins שהוגדרו באובייקט האסטרטגיה.

  כשמשתמשים בשיטה הזו, מתבצעת קריאה לשיטות הבאות של מחזור החיים של הפלאגין:

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

  הפונקציה cachePut נראית כך:

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

  • מקש

    RequestInfo

    הבקשה או כתובת ה-URL שישמשו כמפתח למטמון.

  • תשובה

    תשובה

    התגובה ששמורה במטמון.

  • החזרות

    Promise<boolean>

    false אם האירוע cacheWillUpdate גרם לכך שהתגובה לא תישמר במטמון, ו-true במקרים אחרים.

• כיבוי סופי

  void

  הפעולה הזו מפסיקה את הפעלת האסטרטגיה ומפיקה באופן מיידי את כל ההתחייבויות של waitUntil() שבהמתנה.

  הפונקציה destroy נראית כך:

  () => {...}

• doneWaiting

  void

  הפונקציה מחזירה הבטחה שתתבצע ברגע שכל ההבטחות שהועברו ל-workbox-strategies.StrategyHandler~waitUntil יתקבלו.

  הערה: כל עבודה שמתבצעת אחרי שה-doneWaiting() מסתיים צריכה לעבור באופן ידני ל-method‏ waitUntil() של האירוע (ולא ל-method‏ waitUntil() של ה-handler הזה), אחרת ייתכן ששרשור ה-service worker יופסק לפני שהעבודה תושלם.

  הפונקציה doneWaiting נראית כך:

  () => {...}

  • החזרות

    Promise<void>

• אחזור

  void

  הפונקציה מאחזרת בקשה נתונה (ומפעילה את כל שיטות ה-callback הרלוונטיות של הפלאגין) באמצעות fetchOptions (לבקשות שאינן של ניווט) ו-plugins שמוגדרים באובייקט Strategy.

  כשמשתמשים בשיטה הזו, מתבצעת קריאה לשיטות הבאות של מחזור החיים של הפלאגין:

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

  הפונקציה fetch נראית כך:

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

  • קלט

    RequestInfo

    כתובת ה-URL או הבקשה לאחזור.

  • החזרות

    Promise<Response>

• fetchAndCachePut

  void

  קוראת ל-this.fetch() ומריצה (ברקע) את this.cachePut() בתגובה שנוצרה על ידי this.fetch().

  הקריאה ל-this.cachePut() מפעילה באופן אוטומטי את this.waitUntil(), כך שאין צורך לקרוא ל-waitUntil() באופן ידני באירוע.

  הפונקציה fetchAndCachePut נראית כך:

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

  • קלט

    RequestInfo

    הבקשה או כתובת ה-URL לאחזור ולשמירה במטמון.

  • החזרות

    Promise<Response>

• getCacheKey

  void

  המערכת בודקת את רשימת יישומי הפלאגין כדי למצוא את קריאת החזרה (callback) cacheKeyWillBeUsed, ומבצעת את כל קריאות החזרה שנמצאות ברצף. האובייקט Request הסופי שמוחזר על ידי הפלאגין האחרון מטופל כמפתח המטמון לקריאות ולכתובות במטמון. אם לא נרשמו קריאות חזרה של הפלאגין cacheKeyWillBeUsed, הבקשה שהועברה תוחזר ללא שינוי

  הפונקציה getCacheKey נראית כך:

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

  • בקשה

    בקשה

  • מצב

    "read"
     | "write"
    

  • החזרות

    Promise<Request>

• hasCallback

  void

  הפונקציה מחזירה את הערך True אם לשיטה יש לפחות פלאגין אחד עם פונקציית ה-callback שצוינה.

  הפונקציה hasCallback נראית כך:

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

  • שם

    C

    השם של פונקציית ה-callback שרוצים לבדוק.

  • החזרות

    בוליאני

• iterateCallbacks

  void

  הפונקציה מקבלת פונקציית קריאה חוזרת ומחזירה אוסף של פונקציות קריאה חוזרת תואמות של הפלאגין, כאשר כל פונקציית קריאה חוזרת עטופה במצב הנוכחי של הטיפול (כלומר, כשקוראים לכל פונקציית קריאה חוזרת, פרמטר האובייקט שתעבירו לה ימוזג עם המצב הנוכחי של הפלאגין).

  הפונקציה iterateCallbacks נראית כך:

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

  • שם

    C

    השם של פונקציית ה-callback להפעלה

  • החזרות

    Generator<NonNullable<indexedAccess>anyunknown>

• runCallbacks

  void

  הפונקציה מפעילה את כל פונקציות ה-callback של הפלאגין שתואמות לשם שצוין, לפי הסדר, ומעבירה את אובייקט הפרמטר שצוין (הממוזג עם מצב הפלאגין הנוכחי) כארגומנטים היחיד.

  הערה: מכיוון שהשיטה הזו מפעילה את כל הפלאגינים, היא לא מתאימה למקרים שבהם צריך להחיל את ערך ההחזרה של קריאה חוזרת לפני שמפעילים את הקריאה החוזרת הבאה. בקטע workbox-strategies.StrategyHandler#iterateCallbacks שבהמשך מוסבר איך לטפל בבקשה הזו.

  הפונקציה runCallbacks נראית כך:

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

  • שם

    C

    השם של פונקציית ה-callback שתופעל בכל פלאגין.

  • param

    Omit<indexedAccess"state"
    >

    האובייקט שצריך להעביר כפרמטר הראשון (והיחיד) כשמריצים כל פונקציית קריאה חוזרת. האובייקט הזה ימוזג עם המצב הנוכחי של הפלאגין לפני ביצוע הקריאה החוזרת.

  • החזרות

    Promise<void>

• waitUntil

  void

  הוספת הבטחה ל-[extend lifetime promises]https://w3c.github.io/ServiceWorker/#extendableevent-extend-lifetime-promises של האירוע שמשויך לבקשה שמטופלת (בדרך כלל FetchEvent).

  הערה: אפשר להמתין ל-workbox-strategies.StrategyHandler~doneWaiting כדי לדעת מתי כל ההתחייבויות שנוספו יסתיימו.

  הפונקציה waitUntil נראית כך:

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

  • promise

    Promise<T>

    התחייבות להוסיף להבטחות להארכת משך החיים של האירוע שהפעיל את הבקשה.

  • החזרות

    Promise<T>

StrategyOptions

מאפיינים

• cacheName

  מחרוזת אופציונלי

• fetchOptions

  RequestInit אופציונלי

• matchOptions

  CacheQueryOptions אופציונלי

• פלאגינים

  WorkboxPlugin[] אופציונלי