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

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

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

השם של מחלקות יישומי פלאגין השתנה

מספר חבילות של Workbox בגרסה 4 כללו כיתות בשם Plugin. בגרסה 5, השמות של המחלקות האלה השתנו כך שיתאימו למזהה החבילה של דוגמת העיצוב + Plugin:

  • BackgroundSyncPlugin
  • BroadcastUpdatePlugin
  • CacheableResponsePlugin
  • ExpirationPlugin
  • RangeRequestsPlugin

שינוי השם הזה חל גם אם משתמשים בכיתות בייבוא של מודולים או במרחבי שמות של workbox.*.

נקודת החלפת ברירת מחדל של מניפסט מטמון מראש

בעבר, כשהשתמשתם באחד מכלי ה-build במצב 'הזרקת מניפסט', נבדק אם precacheAndRoute([]) נמצא בקובץ ה-service worker המקור, והמערך הריק [] שימש כ-placeholder לנקודה שבה הוזן המניפסט של האחסון המוקדם.

בגרסה 5 של Workbox, הלוגיקה של ההחלפה השתנתה, ועכשיו self.__WB_MANIFEST משמש כברירת מחדל כנקודת ההחדרה.

// v4:
precacheAndRoute([]);

// v5:
precacheAndRoute(self.__WB_MANIFEST);

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

שתי אפשרויות שנתמכו בעבר במסלולי ניווט, blacklist ו-whitelist, השתנו מסוג denylist ו-allowlist.

workbox-routing תמכה בעבר בשיטה registerNavigationRoute(), שבאופן כללי ביצעה שתי פעולות:

  1. המערכת זיהתה אם אירוע fetch מסוים היה mode מתוך 'navigate' או לא.
  2. אם כן, הגבתם לבקשה באמצעות התוכן של כתובת URL שהוזנה בעבר במטמון, ללא קשר לכתובת ה-URL שאליה מנווטים.

זהו דפוס נפוץ שכדאי להשתמש בו כשמטמיעים את ארכיטקטורת App Shell.

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

אם משתמשים באפשרות navigateFallback באחד מ'יצירת SW' של כלי ה-build המעבר יתבצע באופן אוטומטי. אם הגדרתם בעבר את האפשרויות navigateFallbackBlacklist או navigateFallbackWhitelist, צריך לשנות אותן ל-navigateFallbackDenylist או ל-navigateFallbackAllowlist, בהתאמה.

אם אתם משתמשים במצב 'הזרקת מניפסט' או פשוט כותבים את ה-service worker בעצמכם, ו-service worker של Workbox v4 קורא ישירות ל-registerNavigationRoute(), תצטרכו לבצע שינוי בקוד כדי לקבל את ההתנהגות המקבילה.

// v4:
import {getCacheKeyForURL} from 'workbox-precaching';
import {registerNavigationRoute} from 'workbox-routing';

const appShellCacheKey = getCacheKeyForURL('/app-shell.html');
registerNavigationRoute(appShellCacheKey, {
  whitelist: [...],
  blacklist: [...],
});

// v5:
import {createHandlerBoundToURL} from 'workbox-precaching';
import {NavigationRoute, registerRoute} from 'workbox-routing';

const handler = createHandlerBoundToURL('/app-shell.html');
const navigationRoute = new NavigationRoute(handler, {
  allowlist: [...],
  denylist: [...],
});
registerRoute(navigationRoute);

אין יותר צורך להתקשר אל getCacheKeyForURL(), כי createHandlerBoundToURL() יטפל בזה בשבילך.

הסרת makeRequest() מאסטרטגיות של תיבות עבודה

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

// v4:
const strategy = new StaleWhileRevalidate({...});
const response = await strategy.makeRequest({event, request});

// v5:
const strategy = new StaleWhileRevalidate({...});
const response = await strategy.handle({event, request});

בגרסה 5, handle() מתייחס ל-request כפרמטר נדרש, ולא יחזור להשתמש ב-event.request. חשוב להקפיד להעביר בקשה תקפה בהתקשרות אל handle().

עדכון תיבת העבודה בשידור חי תמיד משתמש ב-postMessage()

בגרסה 4, הספרייה workbox-broadcast-update תשתמש כברירת מחדל ב-Broadcast Channel API לשליחת הודעות כשהיא נתמכת, ותחזור להשתמש ב-postMessage() רק כשאין תמיכה בערוץ Broadcast.

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

לכן, שינינו את workbox-broadcast-update כך שישתמש תמיד ב-postMessage() בגרסה 5. ההודעות נשלחות אחת אחרי השנייה לכל דפי הלקוח שנמצאים בהיקף של ה-service worker הנוכחי.

כדי להתאים את ההתנהגות החדשה הזו, אפשר להסיר כל קוד שהיה בדפי לקוח שיצרו BroadcastChannel מכונות, ובמקום זאת, להגדיר האזנה לאירועים של message ב-navigator.serviceWorker:

// v4:
const updatesChannel = new BroadcastChannel('api-updates');
updatesChannel.addEventListener('message', event => {
  const {cacheName, updatedUrl} = event.data.payload;
  // ... your code here ...
});

// v5:
// This listener should be added as early as possible in your page's lifespan
// to ensure that messages are properly buffered.
navigator.serviceWorker.addEventListener('message', event => {
  // Optional: ensure the message came from workbox-broadcast-update
  if (event.meta === 'workbox-broadcast-update') {
    const {cacheName, updatedUrl} = event.data.payload;
    // ... your code here ...
  }
});

משתמשי workbox-window לא צריכים לבצע שינויים כלשהם, כי הלוגיקה הפנימית שלהם עודכנה כדי להקשיב לשיחות postMessage().

לכלים build נדרש Node.js גרסה 8 ומעלה

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

פלאגין של workbox-webpack מחייב webpack מגרסה 4 ואילך

אם משתמשים ב-workbox-webpack-plugin, צריך לעדכן את ההגדרה של חבילת ה-webpack כדי להשתמש ב-webpack v4 לפחות.

שיפורים משמעותיים באפשרויות של כלי ה-build

מספר פרמטרים של הגדרה workbox-build, workbox-cli ו-workbox-webpack-plugin כבר לא נתמכים. לדוגמה, generateSW תמיד ייצור עבורך חבילת זמן ריצה מקומית של Workbox, לכן האפשרות importWorkboxFrom כבר לא הגיונית.

אפשר לעיין בתיעוד של הכלי הרלוונטי כדי לקבל רשימה של האפשרויות הנתמכות.

הסרת generateSWString מ-workbox-build

המצב generateSWString הוסר מהמצב workbox-build. אנחנו צופים שההשפעה של האפשרות הזו תהיה מינימלית, כי נעשה בה שימוש פנימי בעיקר על ידי workbox-webpack-plugin.

שינויים אופציונליים

שימוש בייבוא מודולים

השינוי הזה הוא (א) אופציונלי ו(ב) היה אפשרי מבחינה טכנית גם בגרסה 4 של Workbox, אבל השינוי הגדול ביותר שאנחנו צופים במעבר לגרסה 5 הוא מודל שבו יוצרים שירות משולב משלכם על ידי ייבוא המודולים של Workbox. זאת גישה חלופית לקריאת importScripts('/path/to/workbox-sw.js') בחלק העליון של קובץ השירות (service worker) ולשימוש ב-Workbox דרך מרחב השמות workbox.*.

אם השתמשת באחד מכלי ה-build (workbox-webpack-plugin, workbox-build, workbox-cli) ב'יצירת SW' במצב כזה, השינוי יתבצע עבורכם באופן אוטומטי. כל הכלים האלה ייצרו חבילת build מקומית בהתאמה אישית של סביבת זמן הריצה של Workbox, לצד הקוד בפועל שנחוץ להטמעת הלוגיקה של ה-service worker. בתרחיש הזה אין יותר תלות ב-workbox-sw או בעותק CDN של Workbox. בהתאם לערך של ההגדרה inlineWorkboxRuntime, סביבת זמן הריצה של Workbox תפוצל לקובץ נפרד שצריך לפרוס לצד ה-service worker (כשהערך מוגדר כ-false, שהיא ברירת המחדל), או שתכלול את הלוגיקה של ה-service worker (כשהערך מוגדר כ-true).

אם משתמשים בכלי ה-build ב'החדרת מניפסט' או אם אתם לא משתמשים בכלי ה-build של Workbox, תוכלו לקבל מידע נוסף על יצירת חבילת זמן ריצה משלכם ב-Workbox במדריך הקיים שימוש ב-Bundler (webpack/נכס-על) עם Workbox.

התיעוד והדוגמאות לגרסה 5 נכתבים בהנחה שהמודול מיובא לתחביר, אבל מרחב השמות של workbox.* ימשיך להיות נתמך ב-Workbox v5.

קריאת תשובות שנשמרו במטמון

חלק מהמפתחים צריכים לקרוא תשובות שנשמרו במטמון ישירות מהמטמון, במקום להשתמש בהן באופן משתמע באמצעות השיטה precacheAndRoute(). דפוס נפוץ בגרסה 4 הוא לקבל קודם את מפתח המטמון שספציפי לגרסה הנוכחית של משאב שנשמר במטמון מראש, ולאחר מכן להעביר את המפתח הזה יחד עם שם המטמון של השמירה מראש אל caches.match() כדי לקבל את Response.

כדי לפשט את התהליך הזה, workbox-precaching בגרסה 5 תומכת בשיטה חדשה מקבילה: matchPrecache():

// v4:
import {cacheNames} from 'workbox-core';
import {getCacheKeyForURL} from 'workbox-precaching';

const cachedResponse = await caches.match(
  getCacheKeyForURL(`/somethingPrecached`),
  {
    cacheName: cacheNames.precache,
  }
);

// v5:
import {matchPrecache} from 'workbox-precaching';

const cachedResponse = await matchPrecache(`/somethingPrecached`);

אימוץ TypeScript

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

דוגמה למיגרציה

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

הדוגמה הבאה לא כוללת את כל השינויים שעשויים לגרום לכשל, אבל היא מראה את המצב הקודם ואת המצב החדש אחרי שדרוג של קובץ אחד של service worker מגרסה 4 לגרסה 5, כולל מעבר ל-TypeScript.

קבלת עזרה

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