نواة إطار العمل

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

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

توفّر هذه الوحدة بعض الوظائف للمطوّرين، ولكن بالإضافة إلى مستويات log والتخزين المؤقت، يوفّر workbox-core منطقًا داخليًا لكل وحدة، بدلاً من المطوّر النهائي.

عرض أسماء ذاكرة التخزين المؤقت التلقائية وتغييرها

تحدِّد Workbox ذاكرات التخزين المؤقت الخاصة بها من خلال cacheNames:

import {cacheNames} from 'workbox-core';

console.log(cacheNames.precache);
console.log(cacheNames.runtime);
console.log(cacheNames.googleAnalytics);

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

<prefix>-<cache-id>-<suffix>

يمكنك تغيير هذه الأسماء التلقائية من خلال تغيير كل القيم أو بعضها التي تم تمريرها إلى setCacheNameDetails().

import {cacheNames, setCacheNameDetails} from 'workbox-core';

setCacheNameDetails({
  prefix: 'my-app',
  suffix: 'v1',
  precache: 'install-time',
  runtime: 'run-time',
  googleAnalytics: 'ga',
});

// Will print 'my-app-install-time-v1'
console.log(cacheNames.precache);

// Will print 'my-app-run-time-v1'
console.log(cacheNames.runtime);

// Will print 'my-app-ga-v1'
console.log(cacheNames.googleAnalytics);

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

مطالبة العملاء

يريد بعض المطوّرين أن يتمكّنوا من نشر عامل خدمة جديد وجعله يتحكّم في صفحات الويب المفتوحة حاليًا فور تفعيله، ولن يحدث ذلك تلقائيًا.

إذا أردت هذا السلوك، يوفّر workbox-core طريقة مساعدة:

import {clientsClaim} from 'workbox-core';

// This clientsClaim() should be at the top level
// of your service worker, not inside of, e.g.,
// an event handler.
clientsClaim();

تُضيف طريقة clientsClaim() في workbox-core تلقائيًا activate أداة معالجة أحداث إلى عامل الخدمة، وتُجري داخلها مكالمة self.clients.claim(). سيؤدي استدعاء self.clients.claim() قبل تنشيط عامل تدفق الخدمة الحالي إلى استثناء وقت التشغيل، ويساعد الغلاف workbox-core في ضمان استدعائه في الوقت المناسب.

تم إيقاف حزمة skipWaiting

قبل الإصدار 6 من Workbox، كان المطوّرون ينصحون أيضًا باستخدام skipWaiting() الطريقة من workbox-core. ومع ذلك، لم توفّر هذه الطريقة قيمة كبيرة مقارنةً بما يحصل عليه المطوّرون عند استدعاء self.skipWaiting() صراحةً.

بما أنّ حزمة workbox-core القديمة المسجّلة أيضًا مسجّلة كمعالج حدث install تم استدعاء self.skipWaiting() فيه، لن تتصرّف الحزمة على النحو المتوقّع إذا تم استدعاؤها داخل معالج حدث آخر، مثل message، بعد اكتمال التركيب.

لهذه الأسباب، تم إيقاف skipWaiting() في workbox-core نهائيًا، وعلى المطوّرين الانتقال إلى الاتصال بـ self.skipWaiting() مباشرةً. على عكس self.clients.claim()، لن يُلقي self.skipWaiting() استثناءً في حال تم استدعاؤه في الوقت "الخاطئ"، لذا ليس من الضروري تضمينه في معالِج أحداث.

الأنواع

CacheDidUpdateCallback()

workbox-core.CacheDidUpdateCallback(
  param: CacheDidUpdateCallbackParam,
)

المعلمات

المرتجعات

  • Promise<void>

CacheDidUpdateCallbackParam

الخصائص

  • cacheName

    سلسلة

  • حدث

    ExtendableEvent

  • newResponse

    الردّ

  • oldResponse

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

  • طلب

    الطلب

  • الولاية

    MapLikeObject اختياري

CachedResponseWillBeUsedCallback()

workbox-core.CachedResponseWillBeUsedCallback(
  param: CachedResponseWillBeUsedCallbackParam,
)

المعلمات

المرتجعات

  • Promise<void | Response>

CachedResponseWillBeUsedCallbackParam

الخصائص

  • cacheName

    سلسلة

  • cachedResponse

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

  • حدث

    ExtendableEvent

  • matchOptions

    CacheQueryOptions اختياري

  • طلب

    الطلب

  • الولاية

    MapLikeObject اختياري

CacheKeyWillBeUsedCallback()

workbox-core.CacheKeyWillBeUsedCallback(
  param: CacheKeyWillBeUsedCallbackParam,
)

المعلمات

المرتجعات

  • Promise<string | Request>

CacheKeyWillBeUsedCallbackParam

الخصائص

  • حدث

    ExtendableEvent

  • الوضع

    سلسلة

  • params

    أيّ اختيارية

  • طلب

    الطلب

  • الولاية

    MapLikeObject اختياري

CacheWillUpdateCallback()

workbox-core.CacheWillUpdateCallback(
  param: CacheWillUpdateCallbackParam,
)

المعلمات

المرتجعات

  • Promise<void | Response>

CacheWillUpdateCallbackParam

الخصائص

  • حدث

    ExtendableEvent

  • طلب

    الطلب

  • رد

    الردّ

  • الولاية

    MapLikeObject اختياري

FetchDidFailCallback()

workbox-core.FetchDidFailCallback(
  param: FetchDidFailCallbackParam,
)

المعلمات

المرتجعات

  • Promise<void>

FetchDidFailCallbackParam

الخصائص

  • خطأ

    خطأ

  • حدث

    ExtendableEvent

  • originalRequest

    الطلب

  • طلب

    الطلب

  • الولاية

    MapLikeObject اختياري

FetchDidSucceedCallback()

workbox-core.FetchDidSucceedCallback(
  param: FetchDidSucceedCallbackParam,
)

المعلمات

المرتجعات

  • Promise<Response>

FetchDidSucceedCallbackParam

الخصائص

  • حدث

    ExtendableEvent

  • طلب

    الطلب

  • رد

    الردّ

  • الولاية

    MapLikeObject اختياري

HandlerCallbackOptions

Enum

RouteHandlerCallbackOptions

ManualHandlerCallbackOptions

HandlerDidCompleteCallback()

workbox-core.HandlerDidCompleteCallback(
  param: HandlerDidCompleteCallbackParam,
)

المعلمات

المرتجعات

  • Promise<void>

HandlerDidCompleteCallbackParam

الخصائص

  • خطأ

    خطأ اختياري

  • حدث

    ExtendableEvent

  • طلب

    الطلب

  • رد

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

  • الولاية

    MapLikeObject اختياري

HandlerDidErrorCallback()

workbox-core.HandlerDidErrorCallback(
  param: HandlerDidErrorCallbackParam,
)

المعلمات

المرتجعات

  • Promise<Response>

HandlerDidErrorCallbackParam

الخصائص

  • خطأ

    خطأ

  • حدث

    ExtendableEvent

  • طلب

    الطلب

  • الولاية

    MapLikeObject اختياري

HandlerDidRespondCallback()

workbox-core.HandlerDidRespondCallback(
  param: HandlerDidRespondCallbackParam,
)

المعلمات

المرتجعات

  • Promise<void>

HandlerDidRespondCallbackParam

الخصائص

  • حدث

    ExtendableEvent

  • طلب

    الطلب

  • رد

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

  • الولاية

    MapLikeObject اختياري

HandlerWillRespondCallback()

workbox-core.HandlerWillRespondCallback(
  param: HandlerWillRespondCallbackParam,
)

المعلمات

المرتجعات

  • Promise<Response>

HandlerWillRespondCallbackParam

الخصائص

  • حدث

    ExtendableEvent

  • طلب

    الطلب

  • رد

    الردّ

  • الولاية

    MapLikeObject اختياري

HandlerWillStartCallback()

workbox-core.HandlerWillStartCallback(
  param: HandlerWillStartCallbackParam,
)

المعلمات

المرتجعات

  • Promise<void>

HandlerWillStartCallbackParam

الخصائص

  • حدث

    ExtendableEvent

  • طلب

    الطلب

  • الولاية

    MapLikeObject اختياري

ManualHandlerCallback()

workbox-core.ManualHandlerCallback(
  options: ManualHandlerCallbackOptions,
)

يتمّ استدعاء دالة "المعالج" لمعاودة الاتصال كلّما تطابق Router مع عنوان URL/طلب مع Route من خلال RouteMatchCallback. يجب أن يُعيد أسلوب الاستدعاء هذا للمعالج قيمة Promise يتم حلّها باستخدام Response.

إذا تم عرض مصفوفة أو عنصر غير فارغ من خلال RouteMatchCallback، سيتم تمريره كوسيطة options.params لهذا المعالِج.

المعلمات

المرتجعات

  • Promise<Response>

ManualHandlerCallbackOptions

الخيارات التي يتم تمريرها إلى دالة ManualHandlerCallback

الخصائص

  • حدث

    ExtendableEvent

  • طلب

    سلسلة | طلب

MapLikeObject

PluginState

يتم حاليًا استخدام MapLikeObjectعادي، ولكن يمكن أن يتم تمديد هذا الرمز أو تقييده في المستقبل.

النوع

MapLikeObject

RequestWillFetchCallback()

workbox-core.RequestWillFetchCallback(
  param: RequestWillFetchCallbackParam,
)

المعلمات

المرتجعات

  • Promise<Request>

RequestWillFetchCallbackParam

الخصائص

  • حدث

    ExtendableEvent

  • طلب

    الطلب

  • الولاية

    MapLikeObject اختياري

RouteHandler

إما RouteHandlerCallback أو RouteHandlerObject إنّ معظم واجهات برمجة التطبيقات في workbox-routing التي تقبل معالجات المسارات تأخذ أيًا مما يلي:

Enum

RouteHandlerCallback

RouteHandlerObject

RouteHandlerCallback()

workbox-core.RouteHandlerCallback(
  options: RouteHandlerCallbackOptions,
)

يتمّ استدعاء دالة "المعالج" لمعاودة الاتصال كلّما تطابق Router مع عنوان URL/طلب مع Route من خلال RouteMatchCallback. يجب أن يُعيد أسلوب الاستدعاء هذا للمعالج قيمة Promise يتم حلّها باستخدام Response.

إذا تم عرض مصفوفة أو عنصر غير فارغ من خلال RouteMatchCallback، سيتم تمريره كوسيطة options.params لهذا المعالِج.

المعلمات

المرتجعات

  • Promise<Response>

RouteHandlerCallbackOptions

الخيارات التي يتم تمريرها إلى دالة RouteHandlerCallback

الخصائص

  • حدث

    ExtendableEvent

  • params

    MapLikeObject | string[] اختياري

  • طلب

    الطلب

  • url

    عنوان URL

RouteHandlerObject

عنصر يحتوي على طريقة handle من النوع RouteHandlerCallback

يمكن إنشاء عنصر Route باستخدام دالة RouteHandlerCallback أو عنصر RouteHandler هذا. تتمثل فائدة RouteHandler في إمكانية تمديدها (كما تفعل حزمة workbox-strategies).

الخصائص

RouteMatchCallback()

workbox-core.RouteMatchCallback(
  options: RouteMatchCallbackOptions,
)

يتم استخدام دالة "match" لتحديد ما إذا كان يجب تطبيق Route على عنوان URL وطلب معيّنَين. عند حدوث المطابقة استجابةً لحدث جلب من العميل، يتم أيضًا تقديم العنصر event. ومع ذلك، بما أنّه يمكن استدعاء callback المطابقة خارج حدث الجلب، يجب ألا يفترض منطق المطابقة أنّ عنصر event سيكون متاحًا دائمًا. إذا عرضت وظيفة الاستدعاء الخاصة بالمطابقة قيمة صحيحة، سيتم استدعاء RouteHandlerCallback المسار المطابق على الفور. إذا كانت القيمة المعروضة مصفوفة أو عنصرًا غير فارغَين، سيتم ضبط هذه القيمة على وسيطة options.params في معالِج الحدث.

المعلمات

المرتجعات

  • أي واحد

RouteMatchCallbackOptions

الخيارات التي يتم تمريرها إلى دالة RouteMatchCallback

الخصائص

  • حدث

    ExtendableEvent

  • طلب

    الطلب

  • sameOrigin

    قيمة منطقية

  • url

    عنوان URL

WorkboxPlugin

عنصر يتضمّن سمات ردّ اتصال اختيارية لمراحل النشاط لعمليّات الجلب والتخزين المؤقت

الخصائص

WorkboxPluginCallbackParam

الخصائص

الخصائص

cacheNames

الحصول على أسماء ذاكرة التخزين المؤقت الحالية والبادئة/اللاحقة المستخدَمة من قِبل Workbox

تُستخدَم cacheNames.precache للأصول التي تم تخزينها مؤقتًا، ويستخدم workbox-google-analytics cacheNames.googleAnalytics لحفظ analytics.js، ويستخدم cacheNames.runtime كل شيء آخر.

يمكن استخدام cacheNames.prefix لاسترداد قيمة البادئة الحالية فقط. يمكن استخدام cacheNames.suffix لاسترداد قيمة اللاحقة الحالية فقط.

النوع

عنصر

الخصائص

  • googleAnalytics

    سلسلة

  • precache

    سلسلة

  • بادئة

    سلسلة

  • وقت التشغيل

    سلسلة

  • لاحقة

    سلسلة

الطُرق

clientsClaim()

workbox-core.clientsClaim()

يمكنك الحصول على أي عملاء متاحين حاليًا بعد أن يصبح عامل الخدمة نشطًا. ويُستخدَم هذا عادةً مع skipWaiting().

copyResponse()

workbox-core.copyResponse(
  response: Response,
  modifier?: function,
)

يسمح للمطوّرين بنسخ استجابة وتعديل قيم headers أو status أو statusText (القيم التي يمكن ضبطها من خلال عنصر [ResponseInit]https://developer.mozilla.org/en-US/docs/Web/API/Response/Response#Syntax في أداة الإنشاء). لتعديل هذه القيم، عليك تمرير دالة كوسيطة ثانية. وسيتم استدعاء هذه الدالة باستخدام عنصر واحد يتضمّن سمات الاستجابة {headers, status, statusText}. سيتم استخدام القيمة المعروضة لهذه الدالة كـ ResponseInit للعنصر Response الجديد. لتغيير القيم، يمكنك تعديل المَعلمات المُرسَلة وإعادتها، أو إعادة كائن جديد تمامًا.

تقتصر هذه الطريقة عن قصد على الردود من المصدر نفسه، بغض النظر عمّا إذا تم استخدام سياسة مشاركة الموارد المتعددة المصادر (CORS) أم لا.

المعلمات

  • رد

    الردّ

  • عنصر تعديل

    الدالة اختيارية

    تظهر المَعلمة modifier على النحو التالي: 

    (responseInit: ResponseInit) => ResponseInit

    • responseInit

      ResponseInit

    • returns

      ResponseInit

المرتجعات

  • Promise<Response>

registerQuotaErrorCallback()

workbox-core.registerQuotaErrorCallback(
  callback: Function,
)

تُضيف دالة إلى مجموعة quotaErrorCallbacks التي سيتم تنفيذها في حال حدث خطأ في الحصة.

المعلمات

  • callback

    وظيفة

setCacheNameDetails()

workbox-core.setCacheNameDetails(
  details: PartialCacheNameDetails,
)

لتعديل أسماء ذاكرة التخزين المؤقت التلقائية التي تستخدمها حِزم Workbox يتم إنشاء أسماء ذاكرة التخزين المؤقت على النحو التالي: <prefix>-<Cache Name>-<suffix>.

المعلمات

  • التفاصيل

    PartialCacheNameDetails

skipWaiting()

workbox-core.skipWaiting()

تم إيقاف هذه الطريقة نهائيًا، وستتم إزالتها في الإصدار 7 من Workbox.

إنّ استدعاء self.skipWaiting() هو إجراء مكافئ، ويجب استخدامه بدلاً من ذلك.