פלאגין לתיבת עבודה-Webpack

ב-Workbox יש שני יישומי פלאגין של webpack: אחד שיוצר בשבילכם Service Worker מלא, ואחד שיוצר רשימה של נכסים למטמון מראש שמוחדר לקובץ של Service Worker.

יישומי הפלאגין מוטמעים כשני מחלקות במודול workbox-webpack-plugin בשם GenerateSW ו-InjectManifest. התשובות לשאלות הבאות יעזרו לכם לבחור את הפלאגין ואת ההגדרות המתאימים.

באיזה פלאגין להשתמש

GenerateSW

הפלאגין GenerateSW ייצור בשבילכם קובץ Service Worker ויוסיף אותו לצינור עיבוד הנתונים של נכסי Webpack.

מתי להשתמש בGenerateSW

• אתם רוצים לשמור מראש קבצים.
• יש לכם צרכים פשוטים לשמירה במטמון בזמן הריצה.

מתי אין להשתמש ב-GenerateSW

• כשרוצים להשתמש בתכונות אחרות של Service Worker (למשל, Web Push).
• ברצונך לייבא סקריפטים נוספים או להוסיף לוגיקה לאסטרטגיות מותאמות אישית של שמירה במטמון.

InjectManifest

הפלאגין InjectManifest ייצור רשימה של כתובות URL לשמירה מראש ויוסיף את המניפסט של המטמון לקובץ שירות קיים. אחרת הקובץ יישאר כפי שהוא.

מתי להשתמש בInjectManifest

• אתם רוצים יותר שליטה על קובץ השירות (service worker).
• אתם רוצים לשמור מראש קבצים.
• צריך להתאים אישית את המסלול והאסטרטגיות.
• אתם רוצים להשתמש בקובץ השירות (service worker) עם תכונות פלטפורמה אחרות (למשל, Web Push).

מתי אין להשתמש ב-InjectManifest

• אתם מעוניינים בדרך הקלה ביותר להוספת קובץ שירות (service worker) לאתר שלכם.

הפלאגין GenerateSW

אפשר להוסיף את הפלאגין GenerateSW להגדרת ה-webpack באופן הבא:

// Inside of webpack.config.js:
const {GenerateSW} = require('workbox-webpack-plugin');

module.exports = {
  // Other webpack config...
  plugins: [
    // Other plugins...
    new GenerateSW({
      // These are some common options, and not all are required.
      // Consult the docs for more info.
      exclude: [/.../, '...'],
      maximumFileSizeToCacheInBytes: ...,
      navigateFallback: '...',
      runtimeCaching: [{
        // Routing via a matchCallback function:
        urlPattern: ({request, url}) => ...,
        handler: '...',
        options: {
          cacheName: '...',
          expiration: {
            maxEntries: ...,
          },
        },
      }, {
        // Routing via a RegExp:
        urlPattern: new RegExp('...'),
        handler: '...',
        options: {
          cacheName: '...',
          plugins: [..., ...],
        },
      }],
      skipWaiting: ...,
    }),
  ],
};

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

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

פלאגין InjectManifest

אפשר להוסיף את הפלאגין InjectManifest להגדרת ה-webpack באופן הבא:

// Inside of webpack.config.js:
const {InjectManifest} = require('workbox-webpack-plugin');

module.exports = {
  // Other webpack config...
  plugins: [
    // Other plugins...
    new InjectManifest({
      // These are some common options, and not all are required.
      // Consult the docs for more info.
      exclude: [/.../, '...'],
      maximumFileSizeToCacheInBytes: ...,
      swSrc: '...',
    }),
  ],
};

הפעולה הזו תיצור מניפסט של מטמון (pre-cache) על סמך נכסי ה-Webpack שנאספו בהגדרות שלכם ותכניס אותו לקובץ ה-Service Worker המצורף.

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

מידע נוסף

הנחיות לגבי שימוש ביישומי הפלאגין בהקשר של build גדול יותר של Webpack מופיעות בקטע Progressive Web Application במסמכי התיעוד של Webpack.

סוגים

GenerateSW

בכיתה הזו יש תמיכה ביצירת קובץ שירות (service worker) חדש ומוכן לשימוש כחלק מתהליך הידור של Webpack.

משתמשים במכונה של GenerateSW במערך plugins של הגדרת Webpack.

// The following lists some common options; see the rest of the documentation
// for the full set of options and defaults.
new GenerateSW({
  exclude: [/.../, '...'],
  maximumFileSizeToCacheInBytes: ...,
  navigateFallback: '...',
  runtimeCaching: [{
    // Routing via a matchCallback function:
    urlPattern: ({request, url}) => ...,
    handler: '...',
    options: {
      cacheName: '...',
      expiration: {
        maxEntries: ...,
      },
    },
  }, {
    // Routing via a RegExp:
    urlPattern: new RegExp('...'),
    handler: '...',
    options: {
      cacheName: '...',
      plugins: [..., ...],
    },
  }],
  skipWaiting: ...,
});

תכונות

• Constructor

  void

  יוצר מופע של GenerateSW.

  הפונקציה constructor נראית כך:

  (config?: GenerateSWConfig)=> {...}

  • config

    GenerateSWConfig אופציונלי

  • החזרות

    GenerateSW

• config

  GenerateSWConfig

GenerateSWConfig

תכונות

• additionalManifestEntries

  (string|ManifestEntry)[] אופציונלי

  רשימת הרשומות לשמירה מראש, בנוסף לרשומות שנוצרות כחלק מתצורת ה-build.

• babelPresetEnvTargets

  string[] אופציונלי

  ערך ברירת המחדל הוא: ["chrome >= 56"]

  היעדים שצריך להעביר ל-babel-preset-env בעת העברת החבילה של קובץ השירות (service worker).

• cacheId

  מחרוזת אופציונלי

  מזהה אופציונלי שיתווסף בתחילת השמות של המטמון. זה שימושי בעיקר לפיתוח מקומי, שבו מספר אתרים יכולים להיות מוצגים מאותו מקור http://localhost:port.

• מקטעים

  string[] אופציונלי

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

• cleanupOutdatedCaches

  בוליאני אופציונלי

  ערך ברירת המחדל הוא: false

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

• clientsClaim

  בוליאני אופציונלי

  ערך ברירת המחדל הוא: false

  האם ה-Service Worker צריך להתחיל לשלוט בלקוחות קיימים מיד לאחר ההפעלה.

• directoryIndex

  מחרוזת אופציונלי

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

• disableDevLogs

  בוליאני אופציונלי

  ערך ברירת המחדל הוא: false

• dontCacheBustURLsMatching

  RegExp אופציונלי

  נכסים שתואמים לערך הזה יחשבו שיש להם גרסאות ייחודיות באמצעות כתובת ה-URL שלהם, והם פטורים מעקיפת מטמון HTTP רגילה שמתבצעת כשמאכלסים את המטמון מראש. אמנם זו לא חובה, אבל מומלץ שאם תהליך ה-build הקיים כבר יוסיף ערך [hash] לכל שם קובץ, תצטרכו לספק ביטוי רגולרי שיזהה את זה, כי הוא יצמצם את רוחב הפס שאתם משתמשים בו בזמן ההכנה מראש של המטמון.

• לא כולל

  (string|RegExp|function)[] optional

  מאפיין אחד או יותר שמשמשים להחרגת נכסים מהמניפסט של המטמון מראש. הפעולה הזו מפורשת לפי אותם כללים כמו האפשרות exclude הרגילה של webpack. אם לא מציינים את הפרמטר הזה, ערך ברירת המחדל הוא [/\.map$/, /^manifest.*\.js$].

• excludeChunks

  string[] אופציונלי

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

• ignoreURLParametersMatching

  RegExp[] אופציונלי

  שמות של פרמטרים של חיפוש שתואמים לאחד מה-RegExp במערך הזה יוסרו לפני שמחפשים התאמה למטמון. האפשרות הזו שימושית אם המשתמשים שלכם עשויים לבקש כתובות URL שמכילות, למשל, פרמטרים של כתובות URL שמשמשים למעקב אחר מקור התנועה. אם לא מציינים אותו, ערך ברירת המחדל הוא [/^utm_/, /^fbclid$/].

• importScripts

  string[] אופציונלי

  רשימה של קובצי JavaScript שצריך להעביר אל importScripts() בקובץ ה-Service Worker שנוצר. זו אפשרות שימושית כשרוצים לאפשר ל-Workbox ליצור קובץ Service Worker ברמה העליונה, אבל רוצים לכלול קוד נוסף, כמו Push event listener.

• importScriptsViaChunks

  string[] אופציונלי

  שם אחד או יותר של מקטעי Webpack. התוכן של המקטעים האלה ייכלל ב-Service Worker שנוצר באמצעות קריאה ל-importScripts().

• כוללים

  (string|RegExp|function)[] optional

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

• inlineWorkboxRuntime

  בוליאני אופציונלי

  ערך ברירת המחדל הוא: false

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

• manifestEntries

  ManifestEntry[] אופציונלי

• manifestTransforms

  ManifestTransform[] אופציונלי

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

• maximumFileSizeToCacheInBytes

  מספר אופציונלי

  ערך ברירת המחדל הוא: 2097152

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

• אמצעי תחבורה

  מחרוזת אופציונלי

  אם המדיניות מוגדרת כ-production, תיווצר חבילה של Service Worker שעבר אופטימיזציה, שלא כוללת מידע על תוצאות ניפוי הבאגים. אם לא מוגדר כאן באופן מפורש, המערכת תשתמש בערך mode שהוגדר בהידור הנוכחי של webpack.

• modifyURLPrefix

  אובייקט אופציונלי

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

  שימוש לדוגמה:

  // Replace a '/dist/' prefix with '/', and also prepend
  // '/static' to every URL.
  modifyURLPrefix: {
    '/dist/': '/',
    '': '/static',
  }
  

• navigateFallback

  מחרוזת אופציונלי

  ערך ברירת המחדל הוא: null

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

• navigateFallbackAllowlist

  RegExp[] אופציונלי

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

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

• navigateFallbackDenylist

  RegExp[] אופציונלי

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

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

• navigationPreload

  בוליאני אופציונלי

  ערך ברירת המחדל הוא: false

  האם להפעיל טעינה מראש של ניווט ב-Service Worker שנוצר או לא להפעיל אותו. אם היא מוגדרת כ-True, צריך להשתמש גם ב-runtimeCaching כדי להגדיר אסטרטגיית תגובה מתאימה שתתאים לבקשות הניווט, ותשתמש בתגובה שנטענה מראש.

• offlineGoogleAnalytics

  boolean|GoogleAnalyticsInitializeOptions optional

  ערך ברירת המחדל הוא: false

  המדיניות קובעת אם לכלול תמיכה ב-Google Analytics אופליין. כש-true, הקריאה ל-initialize() של workbox-google-analytics תתווסף ל-Service Worker שנוצר. כשמגדירים את הערך Object, האובייקט הזה יועבר לקריאה ל-initialize(), כך שתוכלו להתאים אישית את ההתנהגות.

• runtimeCaching

  RuntimeCaching[] אופציונלי

  כשמשתמשים בכלי ה-build של Workbox כדי ליצור את קובץ השירות (service worker), אפשר לציין הגדרה אחת או יותר של שמירה במטמון בזמן הריצה. לאחר מכן, הן יתורגמו לקריאות ל-workbox-routing.registerRoute באמצעות הגדרות ההתאמה וה-handler שהגדרתם.

  לכל האפשרויות, עיינו במסמכי התיעוד של workbox-build.RuntimeCaching. הדוגמה הבאה מציגה תצורה אופיינית, עם שני מסלולי זמן ריצה מוגדרים:

• skipWaiting

  בוליאני אופציונלי

  ערך ברירת המחדל הוא: false

  האם להוסיף קריאה בלתי מותנית ל-skipWaiting() ל-Service Worker שנוצר. אם false, יתווסף במקום זאת listener של message, כך שדפי לקוח יוכלו להפעיל את skipWaiting() על ידי קריאה ל-postMessage({type: 'SKIP_WAITING'}) ב-service worker בהמתנה.

• מפת מקור

  בוליאני אופציונלי

  ערך ברירת המחדל הוא: true

  האם ליצור מפת מקור עבור קובצי ה-Service Worker שנוצרו.

• swDest

  מחרוזת אופציונלי

  ערך ברירת המחדל הוא: "service-worker.js"

  שם הנכס של קובץ ה-Service Worker שנוצר על ידי הפלאגין הזה.

InjectManifest

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

משתמשים במכונה של InjectManifest במערך plugins של הגדרת Webpack.

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

// The following lists some common options; see the rest of the documentation
// for the full set of options and defaults.
new InjectManifest({
  exclude: [/.../, '...'],
  maximumFileSizeToCacheInBytes: ...,
  swSrc: '...',
});

תכונות

• Constructor

  void

  יוצר מופע של InjectManifest.

  הפונקציה constructor נראית כך:

  (config: WebpackInjectManifestOptions)=> {...}

  • config

    WebpackInjectManifestOptions

  • החזרות

    InjectManifest

• config

  WebpackInjectManifestOptions

תכונות

default

סוג

אובייקט

תכונות

• GenerateSW

  שאילתה

• InjectManifest

  שאילתה