العمل بصندوق العمل

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

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

تُخفّف أداة Workbox من الجهد المبذول في التحميل المُسبَق من خلال تبسيط واجهة برمجة التطبيقات وضمان تنزيل مواد العرض بكفاءة.

آلية عمل ميزة "التخزين المؤقت المُسبَق في Workbox"

عند تحميل تطبيق ويب لأول مرة، سيراجع workbox-precaching كل مواد العرض التي تريد تنزيلها، ويزيل أي نُسخ طبق الأصل ويربط أحداث الخدمة ذات الصلة لتنزيل مواد العرض وتخزينها. يتم استخدام عناوين URL التي تتضمّن معلومات عن الإصدار (مثل تجزئة المحتوى) كمفاتيح ذاكرة التخزين المؤقت بدون أي تعديل إضافي. إنّ عناوين URL التي لا تتضمّن معلومات عن الإصدار تتضمّن مَعلمة طلب بحث إضافية لعنوان URL يتم إلحاقها بمفتاح ذاكرة التخزين المؤقت الذي يمثّل تجزئة لمحتوى الذي تنشئه Workbox في وقت الإنشاء.

ينفِّذ workbox-precaching كل ذلك أثناء حدث install الخاص بعامل الخدمة.

عندما يعود المستخدم إلى تطبيق الويب لاحقًا وكان لديك عامل خدمة جديد يحتوي على مواد عرض مختلفة تم تخزينها مسبقًا، سيراجع workbox-precaching القائمة الجديدة ويحدّد مواد العرض الجديدة تمامًا ومواد العرض الحالية التي تحتاج إلى تعديل، استنادًا إلى عملية المراجعة. أي مواد عرض جديدة أو نُسخ معدَّلة، ستتم إضافتها إلى ذاكرة التخزين المؤقت أثناء حدث install لخدمة Worker الجديدة.

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

سينفِّذ workbox-precaching هذه الخطوات في كل مرة يتم فيها تثبيت worker الخدمة وتفعيله، ما يضمن حصول المستخدم على أحدث مواد العرض، وتحميل الملفّات التي تغيّرت فقط.

عرض الإجابات المخزّنة مسبقًا

سيؤدي استدعاء precacheAndRoute() أو addRoute() إلى إنشاء مسار يتطابق مع طلبات عناوين URL التي تم تخزينها مؤقتًا.

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

من المهم تحديد الترتيب الذي تتصل به بالرقم precacheAndRoute() أو addRoute(). وعادةً ما يتم استدعاؤه في وقت مبكر من ملف worker الخدمة، قبل تسجيل أي مسارات إضافية باستخدام registerRoute(). إذا اتصلت بخدمة 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) صراحةً سمة مراجعة، وهي تجزئة تم إنشاؤها تلقائيًا لمحتوى الملف. على عكس ملفات JavaScript وCSS، لا يمكن لملفات HTML بشكل عام تضمين معلومات المراجعة في عناوين URL الخاصة بها، وإلا ستتعطّل الروابط المؤدية إلى هذه الملفات على الويب في أي وقت يتغيّر فيه محتوى الصفحة.

من خلال تمرير سمة مراجعة إلى precacheAndRoute()، يمكن لخدمة Workbox معرفة متى تغيّر الملف وتعديله وفقًا لذلك.

يوفّر Workbox أدوات للمساعدة في إنشاء هذه القائمة:

  • workbox-build: هذه حزمة node يمكن استخدامها في مهمة gulp أو كأحد النصوص البرمجية لتشغيل npm.
  • workbox-webpack-plugin: يمكن لمستخدمي webpack استخدام هذه المكوّنة الإضافية.
  • workbox-cli: يمكن أيضًا استخدام واجهة سطر الأوامر لإنشاء قائمة مواد العرض وإضافتها إلى الخدمة العاملة.

الطلبات الواردة للحصول على الملفات التي تم تخزينها مؤقتًا

من بين الإجراءات التي سينفّذها workbox-precaching تلقائيًا هي التلاعب بطلبات الشبكة الواردة لمحاولة مطابقة الملفات المخزّنة مؤقتًا. ويتيح ذلك مراعاة الممارسات الشائعة على الويب.

على سبيل المثال، يمكن عادةً تلبية طلب / من خلال الملف المتوفّر على الرابط /index.html.

في ما يلي قائمة بعمليات التلاعب التي ينفّذها workbox-precaching تلقائيًا، وكيفية تغيير هذا السلوك.

تجاهل مَعلمات عناوين URL

يمكن تغيير الطلبات التي تحتوي على مَعلمات طلب بحث لإزالة قيم معيّنة أو إزالة جميع القيم.

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

بدلاً من استخدام عملية التصدير التلقائية، يمكنك استخدام العنصر 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 كما هي من قِبل الإصدارات الأحدث. في حالات نادرة، يحدث تغيير جذري في مساحة التخزين المخصّصة لتخزين البيانات المُخزَّنة مسبقًا، مما يتطلّب من المستخدمين الحاليين إعادة تنزيل كل المحتوى، ويؤدي إلى عدم صلاحية البيانات المخزَّنة مسبقًا. (حدث هذا التغيير بين إصدارَي Workbox 3 و4).

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

استخدام ميزة "سلامة الموارد الفرعية"

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

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

إنّ تحديد إدخالات بيان التخزين المؤقت المُسبَق التي يجب أن تحتوي على سمات integrity، وتحديد القيم المناسبة لاستخدامها، لا يدخل في نطاق أدوات إنشاء Workbox. بدلاً من ذلك، على المطوّرين الذين يريدون تفعيل هذه الميزة تعديل ملف بيان التخزين المؤقت المُسبَق الذي تنشئه Workbox لإضافة المعلومات المناسبة بأنفسهم. يمكن أن يساعد خيار manifestTransform في إعدادات أدوات الإنشاء في 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.

الأنواع

CleanupResult

أماكن إقامة

  • deletedCacheRequests

    string[]

InstallResult

أماكن إقامة

  • notUpdatedURLs

    string[]

  • updatedURLs

    string[]

PrecacheController

تنفيذ ميزة "التخزين المؤقت المُسبَق" بكفاءة لمواد العرض

أماكن إقامة

  • طريقة وضع التصميم

    غير صالح

    أنشئ عنصر تحكّم جديدًا في التخزين المؤقت المُسبَق.

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

    (options?: PrecacheControllerOptions) => {...}

    • الخيارات

      PrecacheControllerOptions اختياري

  • الإستراتيجية

    الاستراتيجية

  • تفعيل

    غير صالح

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

    ملاحظة: تستدعي هذه الطريقة event.waitUntil() نيابةً عنك، لذا لا تحتاج إلى استدعائه بنفسك في معالجات الأحداث.

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

    (event: ExtendableEvent) => {...}

    • حدث

      ExtendableEvent

  • addToCacheList

    غير صالح

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

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

    (entries: (string | PrecacheEntry)[]) => {...}

    • الإدخالات

      (string | PrecacheEntry)[]

      مصفوفة للإدخالات التي سيتم تخزينها مؤقتًا مسبقًا

  • createHandlerBoundToURL

    غير صالح

    تُرجِع دالة تبحث عن url في ذاكرة التخزين المؤقت المُسبَق (مع مراعاة معلومات المراجعة)، وتُرجِع Response المقابلة.

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

    (url: string) => {...}

    • url

      سلسلة

      عنوان URL المحفوظ مسبقًا الذي سيتم استخدامه للبحث عن Response.

  • getCacheKeyForURL

    غير صالح

    تعرِض هذه السمة مفتاح ذاكرة التخزين المؤقت المستخدَم لتخزين عنوان URL معيّن. إذا كان عنوان URL هذا غير مرتبط بإصدار معيّن، مثل "‎/index.html"، سيكون مفتاح ذاكرة التخزين المؤقت هو عنوان URL الأصلي مع إلحاق مَعلمة بحث به.

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

    (url: string) => {...}

    • url

      سلسلة

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

    • returns

      سلسلة

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

  • getCachedURLs

    غير صالح

    تعرِض هذه السمة قائمة بجميع عناوين URL التي تم تخزينها مؤقتًا مسبقًا من قِبل العامل الحالي في الخدمة.

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

    () => {...}

    • returns

      string[]

      عناوين URL التي تم تخزينها مؤقتًا مسبقًا

  • getIntegrityForCacheKey

    غير صالح

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

    (cacheKey: string) => {...}

    • cacheKey

      سلسلة

    • returns

      سلسلة

      سلامة المورد الفرعي المرتبطة بمفتاح التخزين المؤقت، أو غير محدّد إذا لم يتم ضبطه

  • getURLsToCacheKeys

    غير صالح

    تعرِض هذه الدالة تعيين عنوان URL محفوظ مسبقًا في ذاكرة التخزين المؤقت إلى مفتاح ذاكرة التخزين المؤقت المقابل، مع مراعاة معلومات المراجعة لعنوان URL.

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

    () => {...}

    • returns

      Map<stringstring>

      عنوان URL لتخزين تعيين المفاتيح مؤقتًا

  • تثبيت

    غير صالح

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

    ملاحظة: تستدعي هذه الطريقة event.waitUntil() نيابةً عنك، لذا لا تحتاج إلى استدعائه بنفسك في معالجات الأحداث.

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

    (event: ExtendableEvent) => {...}

    • حدث

      ExtendableEvent

  • matchPrecache

    غير صالح

    ويعمل هذا الإجراء كبديل لعلامة cache.match() مع الاختلافات التالية:

    • ويعرف اسم ذاكرة التخزين المؤقت المُسبَقة، ولا يبحث إلا في ذاكرة التخزين المؤقت هذه.
    • ويسمح لك هذا الإجراء بإدخال عنوان URL "أصلي" بدون مَعلمات تحديد الإصدار، وسيتم البحث تلقائيًا عن مفتاح ذاكرة التخزين المؤقت الصحيح للمراجعة النشط حاليًا لعنوان URL هذا.

    مثال: سيعثر matchPrecache('index.html') على الردّ الصحيح الذي سبق تخزينه في ذاكرة التخزين المؤقت لعامل الخدمة النشط حاليًا، حتى إذا كان مفتاح ذاكرة التخزين المؤقت هو '/index.html?__WB_REVISION__=1234abcd'.

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

    (request: string | Request) => {...}

    • طلب

      سلسلة | طلب

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

    • returns

      Promise<Response>

  • precache

    غير صالح

    تُضيف العناصر إلى قائمة التخزين المؤقت المُسبَق، وتزيل أي نُسخ مكرّرة، و"تخزِّن الملفات في ملف التخزين المؤقت" عند تثبيت عامل تدخُّل الخدمة.

    يمكن استدعاء هذه الطريقة عدة مرات.

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

    (entries: (string | PrecacheEntry)[]) => {...}

PrecacheEntry

أماكن إقامة

  • السلامة

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

  • مراجعة

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

  • url

    سلسلة

PrecacheFallbackPlugin

يتيح لك PrecacheFallbackPlugin تحديد استجابة "احتياطية بلا إنترنت" لاستخدامها عندما يتعذّر على استراتيجية معيّنة إنشاء استجابة.

ويتم ذلك من خلال اعتراض طلب استدعاء handlerDidError plugin وعرض ردّ محفوظ مسبقًا، مع أخذ مَعلمة المراجعة المتوقّعة في الاعتبار تلقائيًا.

ما لم يتم تمرير مثيل PrecacheController صراحةً إلى دالّة الإنشاء ، سيتم استخدام المثيل التلقائي. بشكل عام، سينتهي الأمر بمعظم المطوّرين باستخدام الإعداد التلقائي.

أماكن إقامة

  • طريقة وضع التصميم

    غير صالح

    تُنشئ هذه الوظيفة إضافة PrecacheFallbackPlugin جديدة باستخدام عنوان fallbackURL المرتبط.

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

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

    • config

      عنصر

      • fallbackURL

        سلسلة

        عنوان URL محفوظ مسبقًا لاستخدامه كخيار احتياطي إذا تعذّر على الاستراتيجية المرتبطة إنشاء استجابة

      • precacheController

        PrecacheController اختياري

PrecacheRoute

فئة فرعية من workbox-routing.Route تأخذ مثيلًا workbox-precaching.PrecacheController وتستخدمه لمطابقة الطلبات الواردة ومعالجة جلب الردود من ذاكرة التخزين المؤقت المُسبَق.

أماكن إقامة

PrecacheRouteOptions

أماكن إقامة

  • cleanURLs

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

  • directoryIndex

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

  • ignoreURLParametersMatching

    RegExp[] اختيارية

  • urlManipulation

    ‫urlManipulation اختيارية

PrecacheStrategy

عملية تنفيذ workbox-strategies.Strategy مصمّمة خصيصًا للعمل مع workbox-precaching.PrecacheController لكلٍّ من تخزين مواد العرض المخزّنة مؤقتًا واستردادها.

ملاحظة: يتم إنشاء مثيل لهذه الفئة تلقائيًا عند إنشاء PrecacheController، وليس من الضروري بشكل عام إنشاء هذا العنصر بنفسك.

أماكن إقامة

  • طريقة وضع التصميم

    غير صالح

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

    (options?: PrecacheStrategyOptions) => {...}

    • الخيارات

      PrecacheStrategyOptions اختيارية

  • cacheName

    سلسلة

  • fetchOptions

    RequestInit اختياري

  • matchOptions

    CacheQueryOptions اختياري

  • المكوّنات الإضافية

    WorkboxPlugin[]

  • copyRedirectedCacheableResponsesPlugin

    WorkboxPlugin

  • defaultPrecacheCacheabilityPlugin

    WorkboxPlugin

  • ‎_awaitComplete

    غير صالح

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

    (responseDone: Promise<Response>, handler: StrategyHandler, request: Request, event: ExtendableEvent) => {...}

    • responseDone

      Promise<Response>

    • handler

      StrategyHandler

    • طلب

      الطلب

    • حدث

      ExtendableEvent

    • returns

      Promise<void>

  • _getResponse

    غير صالح

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

    (handler: StrategyHandler, request: Request, event: ExtendableEvent) => {...}

    • returns

      Promise<Response>

  • ‎_handleFetch

    غير صالح

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

    (request: Request, handler: StrategyHandler) => {...}

    • returns

      Promise<Response>

  • ‎_handleInstall

    غير صالح

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

    (request: Request, handler: StrategyHandler) => {...}

    • returns

      Promise<Response>

  • مؤشر

    غير صالح

    تنفيذ استراتيجية طلب وإرجاع Promise سيتم حلّه باستخدام Response، مع استدعاء جميع عمليات استدعاء المكوّنات الإضافية ذات الصلة

    عند تسجيل مثيل استراتيجية باستخدام Workbox workbox-routing.Route، يتم تلقائيًا استدعاء هذه الطريقة عند مطابقة المسار.

    بدلاً من ذلك، يمكن استخدام هذه الطريقة في FetchEvent مستمع مستقل من خلال تمريرها إلى event.respondWith().

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

    (options: FetchEvent | HandlerCallbackOptions) => {...}

    • الخيارات

      FetchEvent | HandlerCallbackOptions

      FetchEvent أو عنصر يتضمّن السمات الواردة أدناه

    • returns

      Promise<Response>

  • handleAll

    غير صالح

    يشبه workbox-strategies.Strategy~handle، ولكن بدلاً من عرض Promise الذي يحلّ إلى Response، فإنه سيعرض تربيعة من [response, done] promises، حيث يكون العنصر السابق (response) مساويًا لما يعرضه handle()، والعنصر الأخير هو [response, done] promise الذي سيتم حلّه بعد اكتمال أيّ promises تمت إضافتها إلى event.waitUntil() كجزء من تنفيذ الاستراتيجية.

    يمكنك انتظار done promise لضمان اكتمال أي عمل إضافي تنفّذه الاستراتيجية (عادةً ما يكون تخزين الإجابات مؤقتًا) بنجاح.

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

    (options: FetchEvent | HandlerCallbackOptions) => {...}

    • الخيارات

      FetchEvent | HandlerCallbackOptions

      FetchEvent أو عنصر يتضمّن السمات الواردة أدناه

    • returns

      [Promise<Response>, Promise<void>]

      مجموعة من الوعود [response, done] التي يمكن استخدامها لتحديد وقت حلّ الاستجابة وكذلك وقت اكتمال المعالج لجميع أعماله

urlManipulation()

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

النوع

دالة

المعلمات

  • { url }

    عنصر

    • url

      عنوان URL

المرتجعات

  • عنوان URL[]

الطُرق

addPlugins()

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

تضيف هذه السمة مكوّنات إضافية إلى استراتيجية التخزين المؤقت المُسبَق.

المعلمات

addRoute()

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

أضِف مستمعًا fetch إلى مشغّل الخدمة الذي سيؤدي إلى الاستجابة لطلبات الشبكة [network requests]https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API/Using_Service_Workers#Custom_responses_to_requests باستخدام مواد العرض التي تم تخزينها مسبقًا.

طلبات مواد العرض التي لم يتم تخزينها مسبقًا: لن يتم الردّ على FetchEvent، ما يسمح بمرور الحدث إلى مستمعي حدثfetch الآخرين.

المعلمات

cleanupOutdatedCaches()

workbox-precaching.cleanupOutdatedCaches(): void

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

createHandlerBoundToURL()

workbox-precaching.createHandlerBoundToURL(
  url: string,
): RouteHandlerCallback

دالة مساعدة تستدعي PrecacheController#createHandlerBoundToURL على مثيل PrecacheController التلقائي.

إذا كنت بصدد إنشاء PrecacheController، يمكنك استدعاء PrecacheController#createHandlerBoundToURL في تلك الحالة، بدلاً من استخدام هذه الدالة.

المعلمات

  • url

    سلسلة

    عنوان URL المحفوظ مسبقًا الذي سيتم استخدامه للبحث عن Response.

المرتجعات

getCacheKeyForURL()

workbox-precaching.getCacheKeyForURL(
  url: string,
): string | undefined

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

في حال تقديم عنوان URL نسبي، سيتم استخدام الموقع الجغرافي لملف الخدمة العاملة كقاعدة.

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

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

المعلمات

  • url

    سلسلة

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

المرتجعات

  • سلسلة | غير محدّدة

    مفتاح ذاكرة التخزين المؤقت الذي يتوافق مع عنوان URL هذا.

matchPrecache()

workbox-precaching.matchPrecache(
  request: string | Request,
): Promise<Response | undefined>

دالة مساعدة تستدعي PrecacheController#matchPrecache على مثيل PrecacheController التلقائي.

إذا كنت بصدد إنشاء PrecacheController، يمكنك استدعاء PrecacheController#matchPrecache في تلك الحالة، بدلاً من استخدام هذه الدالة.

المعلمات

  • طلب

    سلسلة | طلب

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

المرتجعات

  • Promise<Response | undefined>

precache()

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

تُضيف العناصر إلى قائمة التخزين المؤقت المُسبَق، وتزيل أي نُسخ مكرّرة، و"تخزِّن الملفات في ملف التخزين المؤقت" عند تثبيت عامل تدخُّل الخدمة.

يمكن استدعاء هذه الطريقة عدة مرات.

يُرجى العِلم أنّ هذه الطريقة لن تعرِض لك أيًا من الملفات المخزّنة مؤقتًا. لا يتم تخزين سوى الملفات مسبقًا. للردّ على طلب شبكة، اضغط على workbox-precaching.addRoute.

إذا كانت لديك صفيف واحد من الملفات لتخزينها مؤقتًا مسبقًا، يمكنك ببساطة استدعاء workbox-precaching.precacheAndRoute.

المعلمات

precacheAndRoute()

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

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

هذه طريقة سهلة ستؤدي إلى استدعاء workbox-precaching.precache و workbox-precaching.addRoute في مكالمة واحدة.

المعلمات

  • الإدخالات

    (string | PrecacheEntry)[]

    مصفوفة الإدخالات التي سيتم تخزينها مؤقتًا مسبقًا

  • الخيارات

    ‫PrecacheRouteOptions اختياري