מעבר מתיבת עבודה מגרסה 5 לגרסה 6

המדריך הזה מתמקד בשינויים שעלולים להיווצר ב-Workbox v6, עם דוגמאות לשינויים שצריך לבצע במהלך השדרוג מ-Workbox v5.

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

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

השיטה skipWaiting() ב-workbox-core לא תוסיף יותר ב-handler של install, והיא שוות-ערך לקריאה ל-self.skipWaiting().

מעכשיו יש להשתמש ב-self.skipWaiting() במקום זאת, כי ככל הנראה skipWaiting() תוסר ב-Workbox v7.

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

• לא ניתן יותר להשתמש במסמכי HTML ממקורות שונים עבור כתובות URL שתואמות להפניה אוטומטית מסוג HTTP כדי למלא בקשת ניווט באמצעות workbox-precaching. תרחיש זה אינו נפוץ בדרך כלל.
• מעכשיו, מערכת workbox-precaching מתעלמת מפרמטר השאילתה של כתובת ה-URL fbclid כשמחפשים תגובה שנשמרה מראש במטמון עבור בקשה נתונה.
• הבנאי PrecacheController מקבל עכשיו אובייקט עם מאפיינים ספציפיים כפרמטר שלו, במקום מחרוזת. אובייקט זה תומך במאפיינים הבאים: cacheName (משמש לאותה מטרה כמו המחרוזת שהועברה ל-constructor בגרסה 5), plugins (מחליף את השיטה addPlugins() מ-v5) ו-fallbackToNetwork (מחליף את האפשרות הדומה שהועברה אל createHandler() ו-'createHandlerBoundToURL() ב-v5).
• השיטות install() ו-activate() של PrecacheController מקבלות עכשיו פרמטר אחד בדיוק, שצריך להגדיר אותו לערך InstallEvent או ActivateEvent תואם, בהתאמה.
• השיטה addRoute() הוסרה מ-PrecacheController. במקומה, אפשר להשתמש במחלקה החדשה PrecacheRoute כדי ליצור מסלול ואז לרשום אותו.
• השיטה precacheAndRoute() הוסרה מ-PrecacheController. (היא עדיין קיימת כשיטת עזר סטטית שמיוצאת על ידי המודול workbox-precaching.) היא הוסרה כי אפשר להשתמש ב-PrecacheRoute במקומה.
• השיטה createMatchCalback() הוסרה מ-PrecacheController. אפשר להשתמש במקום זאת בגרסה החדשה של PrecacheRoute.
• השיטה createHandler() הוסרה מ-PrecacheController. במקום זאת, אפשר להשתמש במאפיין strategy של האובייקט PrecacheController כדי לטפל בבקשות.
• הייצוא הסטטי createHandler() כבר הוסר מהמודול workbox-precaching. במקום זאת, מפתחים צריכים ליצור מופע של PrecacheController ולהשתמש במאפיין strategy שלו.
• המסלול הרשום ב-precacheAndRoute() הוא עכשיו מסלול 'אמיתי' שמתבצעת בו שימוש במחלקה Router של workbox-routing. אם ישולבו שיחות לregisterRoute() ולprecacheAndRoute(), יכול להיות שסדר הניווט במסלולים עשוי להשתנות.

ניתוב תיבת עבודה

השיטה setDefaultHandler() משתמשת עכשיו בפרמטר שני אופציונלי שתואם לשיטת ה-HTTP שעליה היא חלה, וברירת המחדל שלו היא 'GET'.

• אם אתה משתמש ב-setDefaultHandler() וכל הבקשות שלך הן GET, אין צורך לבצע שינויים.
• אם יש לך בקשות שאינן GET (POST, PUT וכו'...), setDefaultHandler() לא יגרום יותר לבקשות האלה להיות תואמות.

הגדרת build

האפשרות mode עבור המצבים getManifest ו-injectManifest ב-workbox-build וב-workbox-cli לא הייתה נתמכת, ולכן היא הוסרה. המדיניות הזו לא חלה על workbox-webpack-plugin, שתומך ב-mode בפלאגין InjectManifest.

כדי להשתמש בכלים לפיתוח, נדרש Node.js מגרסה 10 ואילך

אין יותר תמיכה בגרסאות Node.js שקודמות לגרסה 10 של workbox-webpack-plugin, workbox-build או workbox-cli. אם במכשיר פועלת גרסה של Node.js מוקדמת מ-v8, יש לעדכן את זמן הריצה לגרסה נתמכת.

שיפורים חדשים

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

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

מחלקה בסיסית חדשה לאסטרטגיה

בגרסה 6, כל מחלקות האסטרטגיה של תיבת העבודה חייבות להרחיב את מחלקת הבסיס החדשה של Strategy. כל האסטרטגיות המובנות נכתבו מחדש כדי לתמוך בכך.

מחלקת הבסיס Strategy אחראית לשני דברים עיקריים:

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

מחלקה חדשה של "handler"

בעבר היו לנו מודולים פנימיים שנקראים fetchWrapper ו-cacheWrapper, ש (כפי שמשתמע מהשם שלהם) אורזים את ממשקי ה-API השונים לאחזור ולמטמון עם הוּקים במחזור החיים שלהם. זה המנגנון שמאפשר כרגע ליישומי פלאגין לפעול, אבל הוא לא חשוף למפתחים.

המחלקה החדשה של "handler", StrategyHandler, תחשוף את השיטות האלה כך שאסטרטגיות מותאמות אישית יוכלו לקרוא ל-fetch() או ל-cacheMatch() ולהפעיל את כל יישומי הפלאגין שנוספו למופע השיטה באופן אוטומטי.

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

מצב חדש של מחזור החיים של יישומי פלאגין

ב-Workbox v5, יישומי פלאגין הם ללא שמירת מצב. המשמעות היא שאם בקשה ל-/index.html מפעילה גם את הקריאה החוזרת (callback) וגם את requestWillFetch וגם את cachedResponseWillBeUsed של הקריאות החוזרות (callback), שתי הקריאות החוזרות האלה לא יכולות לתקשר זו עם זו, ואפילו לא יודעים שהן הופעלו על ידי אותה בקשה.

בגרסה 6, כל הקריאות החוזרות של הפלאגין יועברו גם אובייקט state חדש. אובייקט המצב הזה יהיה ייחודי לאובייקט הפלאגין הספציפי הזה ולהפעלה המסוימת הזו של האסטרטגיה (כלומר, הקריאה ל-handle()). כך מפתחים יכולים לכתוב יישומי פלאגין שבהם קריאה חוזרת אחת יכולה לבצע פעולה מסוימת באופן מותנה, על סמך פעולה אחרת של קריאה חוזרת באותו פלאגין (למשל, חישוב של הפרש הזמן בין הרצת requestWillFetch ל-fetchDidSucceed או fetchDidFail).

קריאה חוזרת (callback) חדשה במחזור החיים של הפלאגין

נוספו קריאות חוזרות חדשות במחזור החיים של הפלאגין, כדי לאפשר למפתחים למנף באופן מלא את מצב מחזור החיים של הפלאגין:

• handlerWillStart: הופעלה לפני כל לוגיקה של handler שמתחילה לפעול. ניתן להשתמש בהתקשרות חזרה כדי להגדיר את המצב הראשוני של ה-handler (למשל, תיעוד שעת ההתחלה).
• handlerWillRespond: הופעלה לפני שהשיטה handle() מחזירה תגובה. אפשר להשתמש בקריאה החוזרת (callback) כדי לשנות את התגובה הזו לפני החזרתה ל-handler של מסלול או ללוגיקה מותאמת אישית אחרת.
• handlerDidRespond: מתבצעת קריאה לאחר ששיטת handle() של השיטה מחזירה תשובה. ניתן להשתמש בהתקשרות חזרה כדי לתעד פרטים לגבי התגובה הסופית, למשל לאחר שינויים שבוצעו על ידי יישומי פלאגין אחרים.
• handlerDidComplete: נקרא לאחר שכל הבטחות להארכת משך החיים שנוספו לאירוע בעקבות הפעלת השיטה הזו יושבו. ניתן להשתמש בקריאה החוזרת (callback) כדי לדווח על נתונים שצריכים להמתין עד שה-handler יסתיים כדי לחשב (לדוגמה, סטטוס היט של המטמון, זמן האחזור של המטמון, זמן האחזור ברשת).
• handlerDidError: תתבצע קריאה אם ה-handler לא הצליח לספק תגובה חוקית מאף מקור. ניתן להשתמש בקריאה החוזרת (callback) כדי לספק תוכן "חלופה" כחלופה לשגיאת רשת.

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

סוגים מדויקים יותר של TypeScript עבור handlers

הגדרות TypeScript עבור שיטות שונות של קריאה חוזרת עברו נירמול. הדבר אמור להוביל לחוויה טובה יותר עבור מפתחים שמשתמשים ב-TypeScript וכותבים קוד משלהם כדי להטמיע או לקרוא ל-handlers.

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

השיטה החדשה של messageSkip pendinging()

שיטה חדשה, messageSkipWaiting(), נוספה למודול workbox-window כדי לפשט את התהליך של מתן הודעה ל-"waiting" Service worker להפעיל. השיפורים כוללים:

• היא קוראת ל-postMessage() באמצעות גוף ההודעה הרגיל, {type: 'SKIP_WAITING'}, ש-Service Worker שנוצר על ידי Workbox מחפש להפעיל את skipWaiting().
• היא בוחרת את קובץ השירות המתאים ('בהמתנה') שאליו תישלח ההודעה הזו, גם אם זה לא אותו קובץ שירות (service worker) שרשום אצל workbox-window.

הסרת אירועים "חיצוניים" לטובת נכס isExternal

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

מתכון נקי יותר מסוג 'הצעה לטעינה מחדש של דף עבור משתמשים'

הודות לשני השינויים שלמעלה, אפשר לפשט את המתכון 'שליחת הצעה לטעינה מחדש של דף למשתמשים':

MULTI_LINE_CODE_PLACEHOLDER_0

ניתוב תיבת עבודה

פרמטר בוליאני חדש, sameOrigin, מועבר אל הפונקציה matchCallback שבה נעשה שימוש ב-workbox-routing. אם הבקשה היא לכתובת URL ממקור זהה, היא מוגדרת ל-true. אחרת, היא מוגדרת כ-False.

כך מפשטים כמה תבניות סטנדרטיות (boilerplate):

MULTI_LINE_CODE_PLACEHOLDER_1

Matchאפשרויות בארגז העבודה-expiration

עכשיו אפשר להגדיר את matchOptions ב-workbox-expiration, ולאחר מכן הוא יועבר בתור CacheQueryOptions לקריאת cache.delete() הבסיסית. (רוב המפתחים לא יצטרכו לעשות זאת).

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

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

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

כשמשתמשים בהגדרה מראש, המערכת מעבדת עכשיו רשומות אחת אחרי השנייה, לא בכמות גדולה

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

כך תפחיתו את הסבירות לשגיאות net::ERR_INSUFFICIENT_RESOURCES בזמן העיבוד מראש, ובנוסף יקטינו את התחרות בין רוחב הפס בין בקשות מראש לבין בקשות שאפליקציית האינטרנט שולחת בו-זמנית.

PrecacheFallbackPlugin מאפשר החזרה פשוטה יותר למצב אופליין

workbox-precaching כולל עכשיו PrecacheFallbackPlugin, שמטמיע את השיטה החדשה של מחזור החיים של handlerDidError שנוספה בגרסה 6.

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

הנה דוגמה לשימוש בתכונה /offline.html ששמורה מראש במטמון /offline.html, כשהשיטה NetworkOnly לא יכולה לייצר תגובה לבקשת ניווט – במילים אחרות, הצגת דף HTML מותאם אישית אופליין:

MULTI_LINE_CODE_PLACEHOLDER_2

precacheFallback במטמון בזמן ריצה

אם משתמשים ב-generateSW כדי ליצור קובץ שירות (service worker) במקום לכתוב ידנית את קובץ השירות (service worker), ניתן להשתמש באפשרות ההגדרה החדשה precacheFallback ב-runtimeCaching כדי לבצע את אותה פעולה:

{
  // ... other generateSW config options...
  runtimeCaching: [{
    urlPattern: ({request}) => request.mode === 'navigate',
    handler: 'NetworkOnly',
    options: {
      precacheFallback: {
        // This URL needs to be included in your precache manifest.
        fallbackURL: '/offline.html',
      },
    },
  }],
}

קבלת עזרה

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