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

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

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

يتطلب Workbox الكثير من الأعباء الشاقة من التخزين المؤقت من خلال تبسيط واجهة برمجة التطبيقات وضمان تنزيل الأصول بكفاءة.

طريقة عمل التخزين المؤقت لمربعات العمل

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

ينفّذ "workbox-precaching" كل هذه الإجراءات خلال فعالية install التي ينظّمها مشغّل الخدمات.

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

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

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

عرض استجابات التخزين المؤقت مسبقًا

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

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

الترتيب الذي تتصل به precacheAndRoute() أو addRoute() مهم. عادةً ما تحتاج إلى الاتصال به في وقت مبكر في ملف مشغّل الخدمات، قبل تسجيل أي مسارات إضافية باستخدام 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: هذه حزمة عقدة يمكن استخدامها في مهمة gulp أو كنص برمجي للتشغيل npm.
• workbox-webpack-plugin: يمكن لمستخدمي حزمة الويب استخدام هذا المكوّن الإضافي.
• 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 "pretty"). يعني هذا أنّه ستتم معالجة طلب مثل /about من خلال الإدخال المخزن مؤقتًا بشكل مسبق لـ /about.html.

يمكنك إيقاف هذا السلوك من خلال ضبط سياسة cleanUrls:

import {precacheAndRoute} from 'workbox-precaching';

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

أساليب معالجة مخصّصة

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

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 v3 وWorkbox v4).

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

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

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

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

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

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,
)