Workbox-webpack-Plugins

يوفّر Workbox مكوّنَين إضافيَّين من webpack: ينشئ أحدهما مشغِّل خدمات كاملًا لك والآخر ينشئ قائمة بمواد العرض لتخزينها مسبقًا والتي يتم إدخالها في ملف مشغّل الخدمات.

يتم تنفيذ المكوّنات الإضافية في فئتَين في وحدة workbox-webpack-plugin، باسم GenerateSW وInjectManifest. يمكن أن تساعدك الإجابات على الأسئلة التالية في اختيار المكون الإضافي والتهيئة المناسبين لاستخدامه.

المكون الإضافي الذي يمكن استخدامه

GenerateSW

سينشئ لك المكوّن الإضافي GenerateSW ملف مشغّل خدمات ويضيفه إلى مسار مواد عرض حزمة الويب.

حالات استخدام GenerateSW

  • تريد تخزين الملفات مؤقتًا بشكل مسبق.
  • لديك احتياجات بسيطة للتخزين المؤقت في وقت التشغيل.

الحالات التي يُحظر فيها استخدام GenerateSW

  • إذا كنت تريد استخدام ميزات "مشغّل الخدمات" الأخرى (مثل Web Push).
  • تريد استيراد نصوص برمجية إضافية أو إضافة منطق إضافي لاستراتيجيات التخزين المؤقت المخصصة.

InjectManifest

سينشئ المكوّن الإضافي InjectManifest قائمة بعناوين URL لتخزينها مُسبقًا ويضيف بيان التخزين المؤقت هذا إلى ملف عامل خدمات حالي. وإلا سيترك الملف كما هو.

حالات استخدام InjectManifest

  • تريد المزيد من التحكّم في مشغّل الخدمات.
  • تريد تخزين الملفات مؤقتًا بشكل مسبق.
  • عليك تخصيص التوجيه والاستراتيجيات.
  • إذا كنت تريد استخدام مشغّل الخدمات مع ميزات أخرى للأنظمة الأساسية (مثل Web Push).

الحالات التي يُحظر فيها استخدام InjectManifest

  • أنت تريد أسهل مسار لإضافة عامل خدمات إلى موقعك الإلكتروني.

المكوّن الإضافي generateSW

يمكنك إضافة المكوّن الإضافي GenerateSW إلى إعدادات حزمة الويب كما يلي:

// 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: ...,
    }),
  ],
};

وسيؤدي ذلك إلى إنشاء مشغّل خدمات باستخدام إعداد التخزين المؤقت لجميع أصول حزمة الويب التي تم اختيارها من خلال الإعدادات، فضلاً عن قواعد التخزين المؤقت في وقت التشغيل المقدَّمة.

يمكن العثور على مجموعة كاملة من خيارات الضبط في المستندات المرجعية.

المكوّن الإضافي InjectManifest

يمكنك إضافة المكوّن الإضافي InjectManifest إلى إعدادات حزمة الويب كما يلي:

// 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: '...',
    }),
  ],
};

سيؤدي هذا الإجراء إلى إنشاء بيان ميزة "التخزين المؤقت للصفحات" استنادًا إلى أصول حزمة الويب التي تم اختيارها من خلال الإعدادات وإدخاله في ملف مشغّل الخدمات المجمّع والمجمّع.

يمكن العثور على مجموعة كاملة من خيارات الضبط في المستندات المرجعية.

معلومات إضافية

ويمكن الحصول على الإرشادات حول استخدام المكوّنات الإضافية ضمن سياق إصدار حزمة ويب أكبر في قسم "تطبيق الويب التقدمي" في وثائق حزمة الويب.

الأنواع

GenerateSW

تتيح هذه الفئة إنشاء ملف مشغّل خدمات جديد وجاهز للاستخدام كجزء من عملية تجميع حزمة الويب.

استخدِم مثيل GenerateSW في مصفوفة plugins من إعدادات حزمة الويب.

// 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: ...,
});

أماكن إقامة

GenerateSWConfig

أماكن إقامة

  • additionalManifestEntries

    (سلسلة | ManifestEntry)[] اختيارية

    تمثّل هذه السمة قائمة بالإدخالات المطلوب تخزينها مؤقتًا بشكل مسبق، بالإضافة إلى أي إدخالات يتم إنشاؤها كجزء من إعدادات التصميم.

  • babelPresetEnvTargets

    سلسلة[] اختيارية

    القيمة التلقائية هي: ["chrome >= 56"].

    تمثّل هذه السمة الأهداف المطلوب ضبطها إلى babel-preset-env عند تحويل حزمة مشغّلي الخدمات.

  • cacheId

    سلسلة اختيارية

    معرّف اختياري يتم إضافته قبل أسماء ذاكرة التخزين المؤقت ويكون ذلك مفيدًا في المقام الأول للتطوير المحلي حيث قد يتم عرض مواقع إلكترونية متعددة من مصدر http://localhost:port نفسه.

  • قِطَع

    سلسلة[] اختيارية

    اسم مقطع واحد أو أكثر يجب تضمين ملفات الإخراج المقابلة فيها في بيان ذاكرة التخزين المؤقت.

  • cleanupOutdatedCaches

    منطقية اختيارية

    القيمة التلقائية هي: false.

    ما إذا كان يجب أن يحاول Workbox تحديد وحذف أي ذاكرات تخزين مؤقتة تم إنشاؤها بواسطة إصدارات قديمة غير متوافقة.

  • clientsClaim

    منطقية اختيارية

    القيمة التلقائية هي: false.

    ما إذا كان يجب على عامل الخدمة بدء التحكم في أي عملاء حاليين فور تنشيطه.

  • directoryIndex

    سلسلة اختيارية

    إذا تعذّر على طلب التنقّل لعنوان URL ينتهي بـ / أن يطابق عنوان URL مخزنًا مؤقتًا بشكل مسبق، سيتم إلحاق هذه القيمة بعنوان URL وسيتم التحقق منها بحثًا عن تطابُق في ذاكرة التخزين المؤقت. يجب ضبط هذا الإجراء على ما يستخدمه خادم الويب في فهرس الدليل.

  • disableDevLogs

    منطقية اختيارية

    القيمة التلقائية هي: false.

  • dontCacheBustURLsMatching

    التعبير العادي اختياري

    وسيتم افتراض أن مواد العرض التي تتطابق مع هذا النوع من مواد العرض تتوفر لها نُسخ فريدة من خلال عنوان URL الخاص بها، وأن يتم إعفاؤها من عملية اختراق ذاكرة التخزين المؤقت المعتادة لبروتوكول HTTP التي تتم عند تعبئة ذاكرة التخزين المؤقت المسبق. رغم أنّه ليس مطلوبًا، ننصح بتقديم قيمة [hash] في كل اسم ملفّ، إلا أنّنا ننصحك بتقديم تعبير عادي يرصد ذلك، لأنّه سيقلّل من معدل نقل البيانات المُستخدَم في التخزين المؤقت.

  • لا تشمل

    (سلسلة | RegExp | الدالة)[] اختياري

    مُحدِّد واحد أو أكثر يُستخدَم لاستبعاد مواد العرض من بيان التخزين المؤقت قبل التخزين المؤقت. يتم تفسير ذلك من خلال اتّباع القواعد نفسها كخيار exclude العادي في webpack. وفي حال عدم توفيرها، ستكون القيمة التلقائية هي [/\.map$/, /^manifest.*\.js$].

  • excludeChunks

    سلسلة[] اختيارية

    اسم مقطع واحد أو أكثر يجب استبعاد ملفات الإخراج المقابلة الخاصة به من بيان ذاكرة التخزين المؤقت المسبق.

  • ignoreURLParametersMatching

    التعبير العادي[] اختياري

    وستتم إزالة أي أسماء مَعلمات بحث تتطابق مع أحد تعبيرات التعبير العادي في هذه المصفوفة قبل البحث عن تطابق مُخزَّن مسبقًا. ويكون هذا الإجراء مفيدًا إذا كان المستخدمون قد يطلبون عناوين URL تتضمّن، على سبيل المثال، مَعلمات عناوين URL المستخدَمة لتتبّع مصدر الزيارات. وفي حال عدم توفيرها، تكون القيمة التلقائية هي [/^utm_/, /^fbclid$/].

  • importScripts

    سلسلة[] اختيارية

    قائمة بملفات JavaScript التي يجب تمريرها إلى importScripts() داخل ملف مشغّل الخدمات الذي تم إنشاؤه. يكون هذا مفيدًا عندما تريد السماح لـ Workbox بإنشاء ملف مشغّل الخدمات ذي المستوى الأعلى، ولكنك تريد تضمين بعض التعليمات البرمجية الإضافية، مثل أداة معالجة أحداث الدفع.

  • importScriptsViaChunks

    سلسلة[] اختيارية

    اسم واحد أو أكثر من مقاطع حزمة الويب. سيتم تضمين محتوى هذه الأجزاء في مشغّل الخدمات الذي تم إنشاؤه، وذلك من خلال الاتصال بـ importScripts().

  • تتضمّن

    (سلسلة | RegExp | الدالة)[] اختياري

    مُحدِّد واحد أو أكثر يُستخدَم لتضمين مواد العرض في بيان التخزين المؤقت المسبق. يتم تفسير ذلك من خلال اتّباع القواعد نفسها كخيار include العادي في webpack.

  • inlineWorkboxRuntime

    منطقية اختيارية

    القيمة التلقائية هي: false.

    تحدّد هذه السمة ما إذا كان يجب تضمين رمز وقت التشغيل لمكتبة Workbox في مشغّل الخدمات ذي المستوى الأعلى، أو تقسيمه إلى ملف منفصل يجب نشره مع عامل الخدمة. يعني فصل وقت التشغيل أن المستخدمين لن يضطروا إلى إعادة تنزيل رمز Workbox في كل مرة يتغير فيها عامل الخدمة ذو المستوى الأعلى.

  • manifestEntries

    ManifestEntry[] اختيارية

  • manifestTransforms

    تحويل البيان[] اختياري

    دالة واحدة أو أكثر سيتم تطبيقها بشكل تسلسلي مقابل البيان الذي تم إنشاؤه. إذا تم أيضًا تحديد modifyURLPrefix أو dontCacheBustURLsMatching، سيتم تطبيق عمليات التحويل المقابلة لهما أولاً.

  • maximumFileSizeToCacheInBytes

    الرقم اختياري

    القيمة التلقائية: 2097152

    ويمكن استخدام هذه القيمة لتحديد الحد الأقصى لحجم الملفات التي سيتم تخزينها مؤقتًا. وهذا يمنعك من التخزين المؤقت للملفات الكبيرة جدًا التي ربما تطابقت عن طريق الخطأ مع أحد أنماطك، وذلك عن غير قصد.

  • الوضع

    سلسلة اختيارية

    في حال ضبط هذه السياسة على "الإنتاج"، سيتم إنشاء حزمة مشغّل خدمات محسَّنة تستثني معلومات تصحيح الأخطاء. إذا لم يتم ضبطها هنا بشكل واضح، سيتم استخدام قيمة 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 الذي تم إدراجه في بيان التخزين المؤقت قبل التخزين المؤقت. من المفترض أن يُستخدم هذا في سيناريو تطبيق من صفحة واحدة، والذي تريد فيه أن تستخدم جميع عمليات التنقل رمز HTML الشائع لـ App Shell.

  • navigateFallbackAllowlist

    التعبير العادي[] اختياري

    تمثّل هذه السمة مصفوفة اختيارية من التعبيرات العادية التي تفرض قيودًا على عناوين URL التي ينطبق عليها سلوك navigateFallback الذي تم ضبطه. ويكون هذا الإجراء مفيدًا إذا كان يجب التعامل فقط مع مجموعة فرعية من عناوين URL لموقعك الإلكتروني باعتبارها جزءًا من تطبيق صفحة واحدة. في حال ضبط كل من navigateFallbackDenylist وnavigateFallbackAllowlist، تكون الأولوية لقائمة الحظر.

    ملاحظة: يمكن تقييم التعبير العادي هذا مقابل كل عنوان URL مقصود أثناء عملية التنقل. تجنَّب استخدام RegExps المعقّدة، وإلا قد يلاحظ المستخدمون تأخيرات عند التنقّل في موقعك الإلكتروني.

  • navigateFallbackDenylist

    التعبير العادي[] اختياري

    تمثّل هذه السمة مصفوفة اختيارية من التعبيرات العادية التي تفرض قيودًا على عناوين URL التي ينطبق عليها سلوك navigateFallback الذي تم ضبطه. ويكون هذا الإجراء مفيدًا إذا كان يجب التعامل فقط مع مجموعة فرعية من عناوين URL لموقعك الإلكتروني باعتبارها جزءًا من تطبيق صفحة واحدة. وإذا تم ضبط كل من navigateFallbackDenylist وnavigateFallbackAllowlist، ستكون الأولوية لقائمة الحظر.

    ملاحظة: يمكن تقييم التعبير العادي هذا مقابل كل عنوان URL مقصود أثناء عملية التنقل. تجنَّب استخدام RegExps المعقّدة، وإلا قد يلاحظ المستخدمون تأخيرات عند التنقّل في موقعك الإلكتروني.

  • navigationPreload

    منطقية اختيارية

    القيمة التلقائية هي: false.

    لتحديد ما إذا كان سيتم تفعيل التحميل المُسبق للتنقّل في مشغّل الخدمة الذي تم إنشاؤه أم لا. وعند ضبطها على "صحيح"، عليك أيضًا استخدام runtimeCaching لإعداد استراتيجية استجابة مناسبة تتطابق مع طلبات التنقّل، والاستفادة من الاستجابة المحمَّلة مُسبَقًا.

  • offlineGoogleAnalytics

    منطقية | GoogleAnalyticsInitializeOptions اختيارية

    القيمة التلقائية هي: false.

    تتحكّم في ما إذا كان سيتم تضمين الدعم لخدمة "إحصاءات Google" بلا اتصال بالإنترنت أم لا. عند true، ستتم إضافة المكالمة إلى initialize() في workbox-google-analytics إلى مشغّل الخدمات الذي تم إنشاؤه. أمّا عند ضبط السياسة على Object، فسيتم تمرير هذا الكائن إلى طلب initialize()، ما يتيح لك تخصيص السلوك.

  • runtimeCaching

    التخزين المؤقت لوقت التشغيل[] اختياري

    عند استخدام أدوات تصميم Workbox لإنشاء مشغّل الخدمات، يمكنك تحديد واحد أو أكثر من إعدادات التخزين المؤقت في وقت التشغيل. وبعد ذلك، تتم ترجمتها إلى استدعاءات workbox-routing.registerRoute باستخدام إعدادات المطابقة والمعالج التي تحدّدها.

    للاطّلاع على كل الخيارات، يمكنك مراجعة مستندات workbox-build.RuntimeCaching. يوضح المثال أدناه تهيئة نموذجية، مع تحديد مسارين للتشغيل:

  • skipWaiting

    منطقية اختيارية

    القيمة التلقائية هي: false.

    يمكنك اختيار ما إذا كنت تريد إضافة طلب غير مشروط إلى skipWaiting() إلى مشغّل الخدمات الذي تم إنشاؤه. إذا كانت false، ستتم إضافة أداة معالجة بيانات message بدلاً منها، ما يسمح لصفحات العملاء بتشغيل skipWaiting() من خلال استدعاء postMessage({type: 'SKIP_WAITING'}) على عامل خدمة انتظار.

  • خريطة مصدر

    منطقية اختيارية

    القيمة التلقائية هي: true.

    ما إذا كان سيتم إنشاء خريطة مصدر لملفات مشغّل الخدمات التي تم إنشاؤها

  • swDest

    سلسلة اختيارية

    القيمة التلقائية هي: "service-worker.js".

    اسم مادة العرض لملف مشغّل الخدمات الذي أنشأه هذا المكوّن الإضافي

InjectManifest

تتيح هذه الفئة تجميع ملف مشغّل الخدمات المقدَّم من خلال swSrc، وإدخال قائمة بعناوين URL ومعلومات المراجعة في مشغّل الخدمات هذا للتخزين المؤقت استنادًا إلى مسار مواد عرض حزمة الويب.

استخدِم مثيل InjectManifest في مصفوفة plugins من إعدادات حزمة الويب.

بالإضافة إلى إدخال البيان، سيُجري هذا المكوّن الإضافي تجميعًا لملف swSrc باستخدام الخيارات المتاحة في إعدادات حزمة الويب الرئيسية.

// 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: '...',
});

أماكن إقامة

  • الدالة الإنشائية

    void

    تنشئ مثيلاً من InjectManifest.

    تبدو الدالة constructor على النحو التالي: 

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

    • config

      WebpackInjectManifestOptions

  • config

    WebpackInjectManifestOptions

أماكن إقامة

default

النوع

عنصر

أماكن إقامة

  • GenerateSW

    query

  • InjectManifest

    query