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

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

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

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

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

בדוגמאות הבאות נסביר איך להשתמש באסטרטגיות האחסון במטמון של Workbox באמצעות workbox-routing. יש כמה אפשרויות שאפשר להגדיר לכל אחת מהשיטות, שמפורטות בקטע 'הגדרת שיטות' במאמר הזה.

בקטע שימוש מתקדם נסביר איך משתמשים באסטרטגיות האחסון במטמון ישירות, בלי workbox-routing.

Stale-While-Revalidate

תרשים של 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 כולל קבוצה של יישומי פלאגין שאפשר להשתמש בהם עם השיטות האלה.

כדי להשתמש בכל אחד מהפלאגינים האלה (או בפלאגין בהתאמה אישית), פשוט מעבירים את המופעים לאפשרות 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() בהמתנה.

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

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

  • 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) => {...}

    • החזרות

      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) => {...}

  • 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) => {...}

    • החזרות

      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) => {...}

  • 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) => {...}

    • החזרות

      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) => {...}

  • 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) => {...}

    • החזרות

      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) => {...}

  • 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) => {...}

    • החזרות

      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) => {...}

  • 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) => {...}

    • החזרות

      Promise<Response>

  • _handle

    void

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

    (request: Request, handler: 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) => {...}

  • אירוע

    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[] אופציונלי