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

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

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

workbox-precaching

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

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

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

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

אם משתמשים בנכסים שנשמרו במטמון בדרך הזו, החל מגרסה 4 של Workbox, צריך לבצע שלב נוסף כדי לתרגם כתובת URL מקורית למפתח המטמון התואם שאפשר להשתמש בו כדי לקרוא את הרשומה ששמורה במטמון. כדי לעשות זאת, מתקשרים למספר 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 גרסה 3 ל-Workbox גרסה 4, יהיו לכם שתי עותקים של כל המשאבים שנשמרו במטמון מראש.

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

אנחנו ממליצים למפתחים שנתקלו בבעיות כלשהן במהלך השימוש בנתונים האלה, כמו תוצאות שגויות לגבי מחיקה, להודיע לנו.

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

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

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

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

// 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({...});

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

workbox-background-sync

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

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

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

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

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

בגרסה 4, הקריאות החוזרות האלה הוסרו לטובת קריאה חוזרת אחת של 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 באופן פנימי), ולכן היא השתנתה באותו אופן.

workbox-expiration

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

workbox-broadcast-update

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

workbox-core

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

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

תיבת עבודה

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

הגדרת כלי ה-build

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

• dontCacheBustURLsMatching
• ignoreURLParametersMatching
• modifyURLPrefix
• templatedURLs

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

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

workbox-window

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

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

העברה לדוגמה

דוגמה להעברה בעולם האמיתי מ-Workbox בגרסה 3 ל-v4 מופיעה בבקשת המשיכה הזו.

קבלת עזרה

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