Workbox-webpack-Plugins

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

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

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

GenerateSW

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

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

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

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

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

InjectManifest

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

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

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

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

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

المكون الإضافي 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: ...,
    }),
  ],
};

سيؤدي ذلك إلى إنشاء عامل خدمة مع إعداد التخزين المؤقت المُسبَق لجميع مواد عرض 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: '...',
    }),
  ],
};

سيؤدي ذلك إلى إنشاء بيان تخزين مؤقت مُسبَق استنادًا إلى مواد عرض webpack التي تم اختيارها من خلال الإعدادات وإدراجها في ملف worker الخدمة المجمّع والمُجمَّع.

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

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

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

الأنواع

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

    (string | ManifestEntry)[] اختياري

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

  • babelPresetEnvTargets

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

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

    الاستهدافات التي يتم تمريرها إلى babel-preset-env عند تحويل حِزمة worker الخدمة

  • cacheId

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

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

  • أجزاء

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

    اسم جزء واحد أو أكثر يجب تضمين ملفات الإخراج المقابلة له في بيان التخزين المؤقت المُسبَق

  • cleanupOutdatedCaches

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

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

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

  • clientsClaim

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

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

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

  • directoryIndex

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

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

  • disableDevLogs

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

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

  • dontCacheBustURLsMatching

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

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

  • استبعاد

    (string | RegExp | function)[] اختيارية

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

  • excludeChunks

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

    اسم جزء واحد أو أكثر يجب استبعاد ملفات الإخراج المقابلة له من بيان التخزين المؤقت المُسبَق

  • ignoreURLParametersMatching

    RegExp[] اختيارية

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

  • importScripts

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

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

  • importScriptsViaChunks

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

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

  • تتضمّن

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

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

  • inlineWorkboxRuntime

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

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

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

  • manifestEntries

    ManifestEntry[] اختيارية

  • manifestTransforms

    ManifestTransform[] اختياري

    دالة واحدة أو أكثر سيتم تطبيقها بشكل تسلسلي على البيان الذي تم إنشاؤه. إذا تم تحديد 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 المشترَك لإطار التطبيق.

  • navigateFallbackAllowlist

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

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

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

  • navigateFallbackDenylist

    RegExp[] اختيارية

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

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

  • navigationPreload

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

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

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

  • offlineGoogleAnalytics

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

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

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

  • runtimeCaching

    RuntimeCaching[] اختياري

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

    للاطّلاع على جميع الخيارات، يُرجى الاطّلاع على مستندات workbox-build.RuntimeCaching. يوضّح المثال أدناه إعدادًا نموذجيًا، مع تحديد مجريتَي ejecutant:

  • skipWaiting

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

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

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

  • sourcemap

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

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

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

  • swDest

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

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

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

InjectManifest

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

استخدِم مثيلًا من 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: '...',
});

أماكن إقامة

أماكن إقامة

default

النوع

عنصر

أماكن إقامة

  • GenerateSW

    query

  • InjectManifest

    query