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

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

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

עבודה בשיטה הזאת חוסכת לכם הרבה עבודה קשה בשמירה במטמון – היא מפשטת את ה-API ומוודאים שההורדה של הנכסים היא יעילה.

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

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

workbox-precaching עושה את כל זה במהלך האירוע install של קובץ השירות (service worker).

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

ה-Service worker החדש לא ישמש כדי להגיב לבקשות עד להפעלת האירוע activate שלו. באירוע activate, מערכת workbox-precaching תבדוק אם יש נכסים שנשמרו במטמון שכבר לא נמצאים ברשימה של כתובות ה-URL הנוכחיות, ותסיר אותם מהמטמון.

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

הצגת תגובות שנשמרו מראש

קריאה ל-precacheAndRoute() או ל-addRoute() תיצור מסלול שתואם לבקשות לכתובות URL שנשמרו מראש במטמון.

אסטרטגיית התגובה שבה נעשה שימוש במסלול הזה היא שמירה במטמון: המערכת תשתמש בתגובה שנשמרה מראש, אלא אם כן התשובה שנשמרה במטמון לא קיימת (בגלל שגיאה לא צפויה), ובמקרה כזה ייעשה שימוש בתגובת רשת במקום זאת.

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

הסבר על רשימת המטמון מראש

workbox-precaching מצפה למערך אובייקטים עם המאפיינים url ו-revision. המערך הזה נקרא לפעמים מניפסט טרום-מטמון:

import {precacheAndRoute} from 'workbox-precaching';

precacheAndRoute([
  {url: '/index.html', revision: '383676'},
  {url: '/styles/app.0c9a31.css', revision: null},
  {url: '/scripts/app.0d5770.js', revision: null},
  // ... other entries ...
]);

הרשימה הזו מפנה לקבוצה של כתובות URL, כשכל אחת מכילה פרט משלה של "תיקון".

עבור האובייקט השני והשלישי בדוגמה שלמעלה, המאפיין revision מוגדר ל-null. הסיבה לכך היא שהמידע על השינויים נמצא בכתובת ה-URL עצמה, שהיא בדרך כלל שיטה מומלצת לנכסים סטטיים.

האובייקט הראשון (/index.html) מגדיר במפורש מאפיין גרסה, שהוא גיבוב (hash) שנוצר באופן אוטומטי של תוכן הקובץ. בניגוד למשאבי JavaScript ו-CSS, קובצי HTML בדרך כלל לא יכולים לכלול מידע על גרסאות URL, אחרת הקישורים לקבצים האלה באינטרנט יפסיקו לפעול בכל פעם שתוכן הדף ישתנה.

העברת מאפיין גרסה קודמת ל-precacheAndRoute() מאפשרת ל-Workbox לדעת מתי הקובץ השתנה ולעדכן אותו בהתאם.

תיבת העבודה כוללת כלים שיעזרו לכם ליצור את הרשימה הזו:

• workbox-build: זוהי חבילת צמתים שניתן להשתמש בה במשימת שכם או כסקריפט להרצת npm.
• workbox-webpack-plugin: משתמשי Webpack יכולים להשתמש בפלאגין הזה.
• workbox-cli: אפשר להשתמש ב-CLI שלנו גם כדי ליצור את רשימת הנכסים ולהוסיף אותם ל-Service Worker.

בקשות נכנסות לקבצים שנשמרו מראש

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

לדוגמה, בקשה עבור / ��דרך כלל יכולה להתבצע על ידי הקובץ בכתובת /index.html.

בהמשך מופיעה רשימת המניפולציות ש-workbox-precaching מבצע כברירת מחדל, ואיך אפשר לשנות את ההתנהגות הזו.

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

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

כברירת מחדל, המערכת מסירה פרמטרים של חיפוש שמתחילים ב-utm_ או שתואמים בדיוק ל-fbclid, כלומר בקשה של /about.html?utm_campaign=abcd תמומש באמצעות רשומה ששמורה מראש במטמון עבור /about.html.

אפשר להתעלם מקבוצה שונה של פרמטרים לחיפוש באמצעות ignoreURLParametersMatching:

import {precacheAndRoute} from 'workbox-precaching';

precacheAndRoute(
  [
    {url: '/index.html', revision: '383676'},
    {url: '/styles/app.0c9a31.css', revision: null},
    {url: '/scripts/app.0d5770.js', revision: null},
  ],
  {
    // Ignore all URL parameters.
    ignoreURLParametersMatching: [/.*/],
  }
);

אינדקס הספרייה

בקשות שמסתיימות ב-/, כברירת מחדל, יותאמו לרשומות עם הסיומת index.html שמוצמדת לסוף. כלומר, ניתן לטפל באופן אוטומטי בבקשה נכנסת של / באמצעות הערך /index.html שנשמר מראש במטמון.

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

import {precacheAndRoute} from 'workbox-precaching';

precacheAndRoute(
  [
    {url: '/index.html', revision: '383676'},
    {url: '/styles/app.0c9a31.css', revision: null},
    {url: '/scripts/app.0d5770.js', revision: null},
  ],
  {
    directoryIndex: null,
  }
);

כתובות URL נקיות

אם בקשה לא תואמת למטמון מראש, נוסיף .html בסוף כדי לתמוך בכתובות URL "נקיות" (כלומר, כתובות URL "יפות"). כלומר, בקשה כמו /about תטופל על ידי הרשומה השמורה מראש של /about.html.

אפשר להשבית את ההתנהגות הזו על ידי הגדרת cleanUrls:

import {precacheAndRoute} from 'workbox-precaching';

precacheAndRoute([{url: '/about.html', revision: 'b79cd4'}], {
  cleanUrls: false,
});

שינויים בהתאמה אישית

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

import {precacheAndRoute} from 'workbox-precaching';

precacheAndRoute(
  [
    {url: '/index.html', revision: '383676'},
    {url: '/styles/app.0c9a31.css', revision: null},
    {url: '/scripts/app.0d5770.js', revision: null},
  ],
  {
    urlManipulation: ({url}) => {
      // Your logic goes here...
      return [alteredUrlOption1, alteredUrlOption2];
    },
  }
);

שימוש מתקדם

שימוש ישיר ב-PrecacheController

כברירת מחדל, workbox-precaching יגדיר בשבילך את המאזינים install ו-activate. ייתכן שזה לא רצוי עבור מפתחים שבקיאים ב-Service Workers אם אתם זקוקים לשליטה רבה יותר.

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

import {PrecacheController} from 'workbox-precaching';

const precacheController = new PrecacheController();
precacheController.addToCacheList([
  {url: '/styles/example-1.abcd.css', revision: null},
  {url: '/styles/example-2.1234.css', revision: null},
  {url: '/scripts/example-1.abcd.js', revision: null},
  {url: '/scripts/example-2.1234.js', revision: null},
]);

precacheController.addToCacheList([{
  url: '/index.html',
  revision: 'abcd',
}, {
  url: '/about.html',
  revision: '1234',
}]);

self.addEventListener('install', (event) => {
  // Passing in event is required in Workbox v6+
  event.waitUntil(precacheController.install(event));
});

self.addEventListener('activate', (event) => {
  // Passing in event is required in Workbox v6+
  event.waitUntil(precacheController.activate(event));
});

self.addEventListener('fetch', (event) => {
  const cacheKey = precacheController.getCacheKeyForURL(event.request.url);
  event.respondWith(caches.match(cacheKey).then(...));
});

קריאה ישירה של נכסים שנשמרו מראש

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

באופן כללי, אפשר להשתמש ב-Cache Storage API כדי להשיג את האובייקטים Response השמורים מראש, אבל יש רק בעיית אחת: מפתח המטמון של כתובת ה-URL שצריך להשתמש בו כשמפעילים את cache.match() יכול להכיל פרמטר לניהול גרסאות שworkbox-precaching יוצר ומתחזק באופן אוטומטי.

כדי להשיג את מפתח המטמון הנכון אפשר לקרוא ל-getCacheKeyForURL(), להעביר את כתובת ה-URL המקורית ולהשתמש בתוצאה הזו כדי לבצע cache.match() במטמון המתאים.

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

const cache = await caches.open(cacheNames.precache);
const response = await cache.match(getCacheKeyForURL('/precached-file.html'));

לחלופין, אם כל מה שצריך הוא אובייקט Response שנשמר מראש במטמון, אפשר לקרוא ל-matchPrecache(), שישתמש באופן אוטומטי במפתח המטמון הנכון ולחפש במטמון הנכון:

import {matchPrecache} from 'workbox-precaching';

const response = await matchPrecache('/precached-file.html');

ניקוי מטמון ישן

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

הנתונים המיושנים לא אמורים להפריע לפעילות הרגילה, אבל הם כן תורמים לשימוש הכולל במכסת האחסון, ויכול להיות שלמשתמשים שלכם יהיה קל יותר למחוק אותם באופן מפורש. כדי לעשות זאת, מוסיפים את הערך cleanupOutdatedCaches() ל-Service Worker, או מגדירים את cleanupOutdatedCaches: true אם אתם משתמשים באחד מכלי ה-build של Workbox כדי ליצור את קובץ השירות (service worker).

שימוש בתקינות של משאבי משנה

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

אפשר להוסיף מאפיין אופציונלי נוסף בשם integrity לכל רשומה במניפסט של המטמון מראש. אם תספקו אותו, הוא ישמש בתור הערך integrity במהלך בניית ה-Request שישמש לאכלוס המטמון. במקרה של אי-התאמה, תהליך השמירה מראש ייכשל.

היכולת להחליט אילו רשומות מניפסט של מניפסט מראש במטמון צריכות לכלול מאפייני integrity, ולדעת מהם הערכים המתאימים לשימוש, היא מחוץ להיקף של כלי ה-build של תיבת עבודה. במקום זאת, מפתחים שרוצים להביע הסכמה לפונקציונליות הזו צריכים לשנות את מניפסט המטמון מראש שנוצר על ידי Workbox כדי להוסיף את המידע המתאים בעצמם. האפשרות manifestTransform בהגדרות של כלי ה-build של Workbox יכולה לעזור לכם:

const ssri = require('ssri');

const integrityManifestTransform = (originalManifest, compilation) => {
  const warnings = [];
  const manifest = originalManifest.map(entry => {
    // If some criteria match:
    if (entry.url.startsWith('...')) {
      // This has to be a synchronous function call, for example:
      // compilation will be set when using workbox-webpack-plugin.
      // When using workbox-build directly, you can read the file's
      // contents from disk using, e.g., the fs module.
      const asset = compilation.getAsset(entry.url);
      entry.integrity = ssri.fromData(asset.source.source()).toString();

      // Push a message to warnings if needed.
    }
    return entry;
  });

  return {warnings, manifest};
};

// Then add manifestTransform: [integrityManifestTransform]
// to your Workbox build configuration.

workbox-precaching.urlManipulation(
  { url }: object,
)

workbox-precaching.addPlugins(
  plugins: WorkboxPlugin[],
)

workbox-precaching.addRoute(
  options?: PrecacheRouteOptions,
)

workbox-precaching.cleanupOutdatedCaches()

workbox-precaching.createHandlerBoundToURL(
  url: string,
)

workbox-precaching.getCacheKeyForURL(
  url: string,
)

workbox-precaching.matchPrecache(
  request: string | Request,
)

workbox-precaching.precache(
  entries: (string | PrecacheEntry)[],
)

workbox-precaching.precacheAndRoute(
  entries: (string | PrecacheEntry)[],
  options?: PrecacheRouteOptions,
)