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

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

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

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

تم إيقاف برنامج تضمين الطفرة بدون تكلفة

قبل استخدام الإصدار 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

    سلسلة

  • event

    ExtendableEvent

  • newResponse

    الإجابة

  • oldResponse

    الردّ اختياري

  • طلب

    الطلب

  • state

    MapLikeObject اختيارية

CachedResponseWillBeUsedCallback()

workbox-core.CachedResponseWillBeUsedCallback(
  param: CachedResponseWillBeUsedCallbackParam,
)

المَعلمات

المرتجعات

  • Promise<void | Response>

CachedResponseWillBeUsedCallbackParam

أماكن إقامة

  • cacheName

    سلسلة

  • cachedResponse

    الردّ اختياري

  • event

    ExtendableEvent

  • matchOptions

    CacheQueryOptions اختياري

  • طلب

    الطلب

  • state

    MapLikeObject اختيارية

CacheKeyWillBeUsedCallback()

workbox-core.CacheKeyWillBeUsedCallback(
  param: CacheKeyWillBeUsedCallbackParam,
)

المَعلمات

المرتجعات

  • Promise<string | Request>

CacheKeyWillBeUsedCallbackParam

أماكن إقامة

  • event

    ExtendableEvent

  • الوضع

    سلسلة

  • params

    أي اختياري

  • طلب

    الطلب

  • state

    MapLikeObject اختيارية

CacheWillUpdateCallback()

workbox-core.CacheWillUpdateCallback(
  param: CacheWillUpdateCallbackParam,
)

المَعلمات

المرتجعات

  • Promise<void | Response>

CacheWillUpdateCallbackParam

أماكن إقامة

  • event

    ExtendableEvent

  • طلب

    الطلب

  • رد

    الإجابة

  • state

    MapLikeObject اختيارية

FetchDidFailCallback()

workbox-core.FetchDidFailCallback(
  param: FetchDidFailCallbackParam,
)

المَعلمات

المرتجعات

  • Promise<void>

FetchDidFailCallbackParam

أماكن إقامة

  • خطأ

    خطأ

  • event

    ExtendableEvent

  • originalRequest

    الطلب

  • طلب

    الطلب

  • state

    MapLikeObject اختيارية

FetchDidSucceedCallback()

workbox-core.FetchDidSucceedCallback(
  param: FetchDidSucceedCallbackParam,
)

المَعلمات

المرتجعات

  • وعد<الرد>

FetchDidSucceedCallbackParam

أماكن إقامة

  • event

    ExtendableEvent

  • طلب

    الطلب

  • رد

    الإجابة

  • state

    MapLikeObject اختيارية

HandlerCallbackOptions

التعداد

RouteHandlerCallbackOptions

ManualHandlerCallbackOptions

HandlerDidCompleteCallback()

workbox-core.HandlerDidCompleteCallback(
  param: HandlerDidCompleteCallbackParam,
)

المَعلمات

المرتجعات

  • Promise<void>

HandlerDidCompleteCallbackParam

أماكن إقامة

  • خطأ

    الخطأ اختياري

  • event

    ExtendableEvent

  • طلب

    الطلب

  • رد

    الردّ اختياري

  • state

    MapLikeObject اختيارية

HandlerDidErrorCallback()

workbox-core.HandlerDidErrorCallback(
  param: HandlerDidErrorCallbackParam,
)

المَعلمات

المرتجعات

  • وعد<الرد>

HandlerDidErrorCallbackParam

أماكن إقامة

  • خطأ

    خطأ

  • event

    ExtendableEvent

  • طلب

    الطلب

  • state

    MapLikeObject اختيارية

HandlerDidRespondCallback()

workbox-core.HandlerDidRespondCallback(
  param: HandlerDidRespondCallbackParam,
)

المَعلمات

المرتجعات

  • Promise<void>

HandlerDidRespondCallbackParam

أماكن إقامة

  • event

    ExtendableEvent

  • طلب

    الطلب

  • رد

    الردّ اختياري

  • state

    MapLikeObject اختيارية

HandlerWillRespondCallback()

workbox-core.HandlerWillRespondCallback(
  param: HandlerWillRespondCallbackParam,
)

المَعلمات

المرتجعات

  • وعد<الرد>

HandlerWillRespondCallbackParam

أماكن إقامة

  • event

    ExtendableEvent

  • طلب

    الطلب

  • رد

    الإجابة

  • state

    MapLikeObject اختيارية

HandlerWillStartCallback()

workbox-core.HandlerWillStartCallback(
  param: HandlerWillStartCallbackParam,
)

المَعلمات

المرتجعات

  • Promise<void>

HandlerWillStartCallbackParam

أماكن إقامة

  • event

    ExtendableEvent

  • طلب

    الطلب

  • state

    MapLikeObject اختيارية

ManualHandlerCallback()

workbox-core.ManualHandlerCallback(
  options: ManualHandlerCallbackOptions,
)

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

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

المَعلمات

المرتجعات

  • وعد<الرد>

ManualHandlerCallbackOptions

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

أماكن إقامة

  • event

    ExtendableEvent

  • طلب

    سلسلة | طلب

MapLikeObject

PluginState

يتم استخدام MapLikeObject عادي في الوقت الحالي، ولكن يمكن تمديد هذا الإجراء أو فرض قيود عليه في المستقبل.

النوع

MapLikeObject

RequestWillFetchCallback()

workbox-core.RequestWillFetchCallback(
  param: RequestWillFetchCallbackParam,
)

المَعلمات

المرتجعات

  • تقديم وعد<الطلب>

RequestWillFetchCallbackParam

أماكن إقامة

  • event

    ExtendableEvent

  • طلب

    الطلب

  • state

    MapLikeObject اختيارية

RouteHandler

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

التعداد

RouteHandlerCallback

RouteHandlerObject

RouteHandlerCallback()

workbox-core.RouteHandlerCallback(
  options: RouteHandlerCallbackOptions,
)

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

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

المَعلمات

المرتجعات

  • وعد<الرد>

RouteHandlerCallbackOptions

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

أماكن إقامة

  • event

    ExtendableEvent

  • params

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

  • طلب

    الطلب

  • url

    عنوان URL

RouteHandlerObject

عنصر بالطريقة handle من النوع RouteHandlerCallback

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

أماكن إقامة

RouteMatchCallback()

workbox-core.RouteMatchCallback(
  options: RouteMatchCallbackOptions,
)

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

المَعلمات

المرتجعات

  • أي فلتر

RouteMatchCallbackOptions

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

أماكن إقامة

  • event

    ExtendableEvent

  • طلب

    الطلب

  • sameOrigin

    boolean

  • url

    عنوان URL

WorkboxPlugin

كائن يشتمل على خصائص اختيارية لمعاودة الاتصال في دورة الحياة لعمليات الجلب والتخزين المؤقت.

أماكن إقامة

WorkboxPluginCallbackParam

أماكن إقامة

أماكن إقامة

cacheNames

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

يتم استخدام cacheNames.precache لمواد العرض المخزنة مؤقتًا بشكل مسبق، بينما يتم استخدام cacheNames.googleAnalytics في workbox-google-analytics لتخزين analytics.js ويستخدم cacheNames.runtime في كل شيء آخر.

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

النوع

عنصر

أماكن إقامة

  • googleAnalytics

    سلسلة

  • التخزين المؤقت المسبق

    سلسلة

  • بادئة

    سلسلة

  • وقت التشغيل

    سلسلة

  • لاحقة

    سلسلة

الطُرق

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

المرتجعات

  • وعد<الرد>

registerQuotaErrorCallback()

workbox-core.registerQuotaErrorCallback(
  callback: Function,
)

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

المَعلمات

  • معاودة الاتصال

    الوظيفة

setCacheNameDetails()

workbox-core.setCacheNameDetails(
  details: PartialCacheNameDetails,
)

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

المَعلمات

  • التفاصيل

    PartialCacheNameDetails

skipWaiting()

workbox-core.skipWaiting()

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

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