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

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

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

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

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

• BackgroundSyncPlugin
• BroadcastUpdatePlugin
• CacheableResponsePlugin
• ExpirationPlugin
• RangeRequestsPlugin

שינוי השם הזה חל בין אם משתמשים במחלקות דרך ייבוא מודולים או דרך מרחבי השמות של workbox.*.

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

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

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

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

השלב השני, יצירת תגובה על ידי קריאה מהמטמון, לא חורג מתחומי האחריות של workbox-routing. במקום זאת, אנחנו רואים אותה כפונקציונליות שצריכה להיות חלק מ-workbox-precaching, בשיטה חדשה, 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 Channel.

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

לכן שינינו את workbox-broadcast-update כך שישתמש תמיד ב-postMessage() בגרסה 5. ההודעות נשלחות בזו אחר זו לכל דפי הלקוח שנכללים ב-Service Worker הנוכחי.

כדי להתאים להתנהגות החדשה הזו, אפשר להסיר כל קוד שנכלל בדפי לקוח שיצרו BroadcastChannel מכונות. במקום זאת, אפשר להגדיר פונקציות event listener של 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().

כלי הבנייה מחייבים את Node.js v8 ואילך

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

פלאגין של workbox-webpack דורש webpack מגרסה 4 ומעלה

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

שינוי אפשרות לכלי הבנייה

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

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

הסרת createSWString מ-workbox-build

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

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

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

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

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

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

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

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

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