מעבר מתיבת עבודה בגרסה 3 לגרסה 4

המדריך הזה מתמקד בפריצת שינויים שנערכו ב-Workbox v4, עם דוגמאות לשינויים שצריך לבצע במהלך השדרוג מ-Workbox v3.

שינויי תוכנה שעלולים לגרום לכשלים

טעינה מראש של ארגז עבודה

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

מפתחים שמשתמשים מראש במטמון דרך workbox.precaching.precacheAndRoute(), שהוא התרחיש הנפוץ ביותר לדוגמה, לא צריכים לבצע שינויים בתצורת קובץ השירות (service worker) שלהם. לאחר השדרוג ל-Workbox v4, הנכסים השמורים במטמון של המשתמשים יועברו באופן אוטומטי לפורמט המפתח החדש של המטמון, ומעכשיו והלאה, משאבים שנשמרו מראש ימשיכו להיות מוגשים באותו אופן כמו קודם.

שימוש ישיר במפתחות המטמון

יכול להיות שמפתחים מסוימים יצטרכו לגשת ישירות לרשומות של מטמון מראש, מחוץ להקשר של workbox.precaching.precacheAndRoute(). לדוגמה, יכול להיות שתרצו לשמור מראש תמונה שבסופו של דבר תשתמשו בה כתגובת 'חזרה', כשאי אפשר לאחזר תמונה ממשית מהרשת.

אם משתמשים בנכסים ששמורים מראש באופן הזה, החל מגרסה Workbox v4, צריך לבצע שלב נוסף כדי לתרגם כתובת אתר מקורית למפתח המטמון המתאים, שיכול לשמש לקריאת הערך שנשמר במטמון. כדי לעשות זאת, מתקשרים אל workbox.precaching.getCacheKeyForURL(originURL).

לדוגמה, אם ידוע לך ש-'fallback.png' נשמר מראש:

const imageFallbackCacheKey =
  workbox.precaching.getCacheKeyForURL('fallback.png');

workbox.routing.setCatchHandler(({event}) => {
  switch (event.request.destination) {
    case 'image':
      return caches.match(imageFallbackCacheKey);
      break;
    // ...other fallback logic goes here...
  }
});

ניקוי נתונים ישנים שנשמרו מראש

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

כדי למנוע זאת, אפשר להוסיף את הקריאה ל-workbox.precaching.cleanupOutdatedCaches() ישירות ל-Service Workers, או להגדיר את האפשרות החדשה cleanupOutdatedCaches: true אם משתמשים בכלי build במצב GenerateSW. מכיוון שהלוגיקה של ניקוי המטמון פועלת על מוסכמות מתן שמות למטמון כדי למצוא קובצי מטמון ישנים יותר, ומאחר שלמפתחים יש אפשרות לשנות את המוסכמות האלה, טעינו בצד הבטיחות ולא הפעלנו זאת כברירת מחדל.

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

שימוש באותיות רישיות בפרמטרים

השמות של שני פרמטרים אופציונליים שאפשר להעביר אל workbox.precaching.precacheAndRoute() וגם workbox.precaching.addRoute() השתנו, כדי להתאים להסכמה הכוללת שלנו לשימוש באותיות רישיות. ignoreUrlParametersMatching נקראת עכשיו ignoreURLParametersMatching, וcleanUrls נקראת עכשיו cleanURLs.

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

יש שתי דרכים, פחות או יותר, דומות ליצירת מכונה של handler ב-workbox-strategies. אנחנו מוציאים משימוש את שיטת היצרן, לטובת קריאה מפורשת לבונה האסטרטגיה.

// This factory method syntax has been deprecated:
const networkFirstStrategy = workbox.strategies.networkFirst({...});

// Instead, use the constructor directly:
// (Note that the class name is Uppercase.)
const networkFirstStrategy = new workbox.strategies.NetworkFirst({...});

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

סנכרון ברקע של תיבת העבודה

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

בגרסה 3, למחלקה Queue הייתה דרך אחת להוסיף בקשות לתור (שיטת addRequest()), אבל לא הייתה לה דרך לשנות את התור או להסיר בקשות.

בגרסה 4, השיטה addRequests() הוסרה ונוספו השיטות דמויות המערך הבאות:

• pushRequest()
• popRequest()
• shiftRequest()
• unshiftRequest()

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

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

דוגמה ללוגיקה של הפעלה חוזרת בהתאמה אישית:

const queue = new workbox.backgroundSync.Queue('my-queue-name', {
  onSync: async ({queue}) => {
    let entry;
    while ((entry = await this.shiftRequest())) {
      try {
        await fetch(entry.request);
      } catch (error) {
        console.error('Replay failed for request', entry.request, error);
        await this.unshiftRequest(entry);
        return;
      }
    }
    console.log('Replay complete!');
  },
});

באופן דומה, המחלקה workbox.backgroundSync.Plugin מקבלת את אותם ארגומנטים כמו המחלקה Queue (כי היא יוצרת מכונה של Queue באופן פנימי), כך שהיא השתנתה באותו אופן.

תפוגה של ארגז עבודה

השם של החבילה npm השתנה ל-workbox-expiration, בהתאם למוסכמות מתן השמות שנעשה בהן שימוש במודולים אחרים. הפונקציונליות של החבילה הזו מקבילה מבחינה פונקציונליות לחבילת workbox-cache-expiration הישנה יותר, שהוצאה משימוש עכשיו.

עדכון-workbox-broadcast-update

השם של החבילה npm השתנה ל-workbox-broadcast-update, בהתאם למוסכמות מתן השמות שנעשה בהן שימוש במודולים אחרים. הפונקציונליות של החבילה הזו מקבילה מבחינה פונקציונליות לחבילת workbox-broadcast-cache-update הישנה יותר, שהוצאה משימוש עכשיו.

תיבת עבודה-ליבה

בגרסה 3 של Workbox אפשר לשנות את דרגת המלל של רמות היומן באמצעות השיטה workbox.core.setLogLevel(), שאותה צריך להעביר אחד מהערכים שבמספרים workbox.core.LOG_LEVELS. אפשר גם לקרוא את רמת היומן הנוכחית באמצעות workbox.core.logLevel.

ב-Workbox v4, כל התכונות האלה הוסרו כי כל הכלים המודרניים למפתחים כוללים עכשיו יכולות סינון יומנים עשירות (מידע נוסף זמין במאמר סינון פלט המסוף לכלים למפתחים ב-Chrome).

תיבת עבודה-sw

שתי שיטות שנחשפו בעבר ישירות במרחב השמות של workbox (התואמים למודול workbox-sw) הועברו במקום זאת אל workbox.core. workbox.skipWaiting() הפך ל-workbox.core.skipWaiting() ודומה, workbox.clientsClaim() הפך ל-workbox.core.clientsClaim().

הגדרת כלי ה-Build

השתנה השמות של חלק מהאפשרויות שניתן להעביר ל: workbox-cli, workbox-build או workbox-webpack-פלאגין. בכל פעם שנעשה שימוש ב-Url בשם אפשרות, נוציא אותה משימוש לטובת URL. המשמעות היא שהשמות הבאים הם המועדפים:

• dontCacheBustURLsMatching
• ignoreURLParametersMatching
• modifyURLPrefix
• templatedURLs

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

פונקציונליות חדשה

חלון תיבת עבודה

מודול workbox-window החדש מפשט את תהליך הרישום של קובצי השירות וזיהוי עדכונים, ומספק אמצעי תקשורת סטנדרטי בין קוד שפועל ב-Service Worker לבין קוד שפועל בהקשר של אפליקציית האינטרנט window.

השימוש ב-workbox-window הוא אופציונלי, אבל אנחנו מקווים שהמפתחים יועילו להם. כמו כן, כדאי להעביר חלק מהלוגיקה של כתב היד שלהם לשימוש במקרה הצורך. במדריך למודול אפשר לקבל מידע נוסף על השימוש ב-workbox-window.

העברה לדוגמה

דוגמה להעברה בעולם האמיתי מ-Workbox v3 לגרסה v4 ניתן למצוא בבקשת המשיכה הזו.

קבלת עזרה

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