جعبه کار ساخت

ماژول workbox-build در یک فرآیند ساخت مبتنی بر گره ادغام می‌شود و می‌تواند کل یک سرویس ورکر را تولید کند، یا فقط لیستی از دارایی‌ها را برای پیش‌ذخیره‌سازی (precache) ایجاد کند که می‌توانند در یک سرویس ورکر موجود استفاده شوند.

دو حالتی که اکثر توسعه‌دهندگان از آن‌ها استفاده می‌کنند generateSW و injectManifest هستند. پاسخ به سوالات زیر می‌تواند به شما در انتخاب حالت و پیکربندی مناسب برای استفاده کمک کند.

از کدام حالت استفاده کنیم

generateSW

حالت generateSW یک فایل سرویس ورکر برای شما ایجاد می‌کند که از طریق گزینه‌های پیکربندی سفارشی‌سازی شده و آن را روی دیسک می‌نویسد.

چه زمانی از generateSW استفاده کنیم

  • شما می‌خواهید فایل‌ها را از قبل ذخیره کنید.
  • شما نیازهای ساده‌ای در زمینه ذخیره‌سازی موقت (caching) دارید.

چه زمانی از generateSW استفاده نکنیم

  • شما می‌خواهید از سایر ویژگی‌های Service Worker (مثلاً Web Push ) استفاده کنید.
  • شما می‌خواهید اسکریپت‌های اضافی را وارد کنید، یا منطق اضافی برای استراتژی‌های ذخیره‌سازی سفارشی اضافه کنید.

injectManifest

حالت injectManifest فهرستی از URLها را برای precache ایجاد می‌کند و آن precache manifest را به یک فایل service worker موجود اضافه می‌کند. در غیر این صورت، فایل را به همان شکل باقی می‌گذارد.

چه زمانی از injectManifest استفاده کنیم؟

  • شما می‌خواهید کنترل بیشتری روی سرویس ورکر خود داشته باشید.
  • شما می‌خواهید فایل‌ها را از قبل ذخیره کنید.
  • شما باید مسیریابی و استراتژی‌ها را سفارشی کنید.
  • شما می‌خواهید از سرویس ورکر خود با سایر ویژگی‌های پلتفرم (مثلاً Web Push ) استفاده کنید.

چه زمانی نباید از injectManifest استفاده کرد؟

  • شما ساده‌ترین راه برای اضافه کردن یک سرویس ورکر به سایت خود را می‌خواهید.

حالت generateSW

شما می‌توانید از حالت generateSW در یک اسکریپت ساخت مبتنی بر گره، با استفاده از رایج‌ترین گزینه‌های پیکربندی ، مانند موارد زیر، استفاده کنید:

// Inside of build.js:
const {generateSW} = require('workbox-build');

// These are some common options, and not all are required.
// Consult the docs for more info.
generateSW({
  dontCacheBustURLsMatching: [new RegExp('...')],
  globDirectory: '...',
  globPatterns: ['...', '...'],
  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: ...,
  swDest: '...',
}).then(({count, size, warnings}) => {
  if (warnings.length > 0) {
    console.warn(
      'Warnings encountered while generating a service worker:',
      warnings.join('\n')
    );
  }

  console.log(`Generated a service worker, which will precache ${count} files, totaling ${size} bytes.`);
});

این کار یک سرویس ورکر با تنظیمات پیش‌ذخیره‌سازی برای تمام فایل‌هایی که توسط پیکربندی شما انتخاب شده‌اند و قوانین ذخیره‌سازی زمان اجرا ارائه شده، ایجاد می‌کند.

مجموعه کاملی از گزینه‌های پیکربندی را می‌توانید در مستندات مرجع بیابید.

حالت injectManifest

شما می‌توانید از حالت injectManifest در یک اسکریپت ساخت مبتنی بر گره، با استفاده از رایج‌ترین گزینه‌های پیکربندی ، مانند موارد زیر، استفاده کنید:

// Inside of build.js:
const {injectManifest} = require('workbox-build');

// These are some common options, and not all are required.
// Consult the docs for more info.
injectManifest({
  dontCacheBustURLsMatching: [new RegExp('...')],
  globDirectory: '...',
  globPatterns: ['...', '...'],
  maximumFileSizeToCacheInBytes: ...,
  swDest: '...',
  swSrc: '...',
}).then(({count, size, warnings}) => {
  if (warnings.length > 0) {
    console.warn(
      'Warnings encountered while injecting the manifest:',
      warnings.join('\n')
    );
  }

  console.log(`Injected a manifest which will precache ${count} files, totaling ${size} bytes.`);
});

این دستور یک مانیفست precache بر اساس فایل‌هایی که توسط پیکربندی شما جمع‌آوری شده‌اند ایجاد می‌کند و آن را به فایل service worker موجود شما تزریق می‌کند.

مجموعه کاملی از گزینه‌های پیکربندی را می‌توانید در مستندات مرجع بیابید.

حالت‌های اضافی

ما انتظار داریم که generateSW یا injectManifest نیازهای اکثر توسعه‌دهندگان را برآورده کند. با این حال، یک حالت دیگر نیز وجود دارد که توسط workbox-build پشتیبانی می‌شود و ممکن است برای موارد استفاده خاص مناسب باشد.

حالت getManifest

این از نظر مفهومی شبیه به حالت injectManifest است، اما به جای اضافه کردن manifest به فایل سرویس ورکر منبع، آرایه‌ای از ورودی‌های manifest را به همراه اطلاعاتی در مورد تعداد ورودی‌ها و اندازه کل، برمی‌گرداند.

شما می‌توانید از حالت injectManifest در یک اسکریپت ساخت مبتنی بر گره، با استفاده از رایج‌ترین گزینه‌های پیکربندی ، مانند موارد زیر، استفاده کنید:

// Inside of build.js:
const {getManifest} = require('workbox-build');

// These are some common options, and not all are required.
// Consult the docs for more info.
getManifest({
  dontCacheBustURLsMatching: [new RegExp('...')],
  globDirectory: '...',
  globPatterns: ['...', '...'],
  maximumFileSizeToCacheInBytes: ...,
}).then(({manifestEntries, count, size, warnings}) => {
  if (warnings.length > 0) {
    console.warn(
      'Warnings encountered while getting the manifest:',
      warnings.join('\n')
    );
  }

  // Do something with the manifestEntries, and potentially log count and size.
});

مجموعه کاملی از گزینه‌های پیکربندی را می‌توانید در مستندات مرجع بیابید.

انواع

BasePartial

خواص

  • ورودی‌های اضافی مانیفست

    (رشته | ManifestEntry )[] اختیاری

    فهرستی از ورودی‌هایی که باید از قبل ذخیره شوند، علاوه بر هر ورودی که به عنوان بخشی از پیکربندی ساخت ایجاد می‌شود.

  • dontCacheBustURLsMatching

    RegExp اختیاری

    دارایی‌هایی که با این مورد مطابقت دارند، از طریق URL خود به صورت منحصر به فرد نسخه‌بندی می‌شوند و از عملیات معمول HTTP cache-busting که هنگام پر کردن precache انجام می‌شود، معاف هستند. اگرچه الزامی نیست، اما توصیه می‌شود اگر فرآیند ساخت موجود شما از قبل یک مقدار [hash] را در هر نام فایل وارد می‌کند، یک RegExp ارائه دهید که آن را تشخیص دهد، زیرا پهنای باند مصرفی هنگام precaching را کاهش می‌دهد.

  • مانیفست ترنسفورمز

    تبدیل مانیفست [] اختیاری

    یک یا چند تابع که به ترتیب روی مانیفست تولید شده اعمال می‌شوند. اگر modifyURLPrefix یا dontCacheBustURLsMatching نیز مشخص شده باشند، تبدیل‌های مربوط به آنها ابتدا اعمال می‌شوند.

  • حداکثر اندازه فایل برای حافظه پنهان به بایت

    شماره اختیاری

    مقدار پیش‌فرض: ۲۰۹۷۱۵۲

    این مقدار می‌تواند برای تعیین حداکثر اندازه فایل‌هایی که precached می‌شوند، استفاده شود. این کار از precached ناخواسته فایل‌های بسیار بزرگی که ممکن است به طور تصادفی با یکی از الگوهای شما مطابقت داشته باشند، جلوگیری می‌کند.

  • پیشوند modifyURL

    شیء اختیاری

    یک شیء، پیشوندهای رشته‌ای را به مقادیر رشته‌ای جایگزین نگاشت می‌کند. این می‌تواند برای مثال، حذف یا اضافه کردن یک پیشوند مسیر از یک ورودی مانیفست در صورتی که تنظیمات میزبانی وب شما با تنظیمات سیستم فایل محلی شما مطابقت نداشته باشد، استفاده شود. به عنوان یک جایگزین با انعطاف‌پذیری بیشتر، می‌توانید از گزینه manifestTransforms استفاده کنید و تابعی را ارائه دهید که ورودی‌های مانیفست را با استفاده از هر منطقی که ارائه می‌دهید، تغییر دهد.

    مثال استفاده:

    // Replace a '/dist/' prefix with '/', and also prepend
// '/static' to every URL.
modifyURLPrefix: {
  '/dist/': '/',
  '': '/static',
}

BuildResult

نوع

حذف< GetManifestResult "manifestEntries"
> و شیء

خواص

  • مسیرهای فایل

    رشته[]

GeneratePartial

خواص

  • babelPresetEnvTargets

    رشته[] اختیاری

    مقدار پیش‌فرض: ["chrome >= 56"]

    اهدافی که هنگام transpile کردن بسته‌ی service worker باید به babel-preset-env ارسال شوند.

  • شناسه حافظه پنهان

    رشته اختیاری

    یک شناسه اختیاری که باید به نام‌های حافظه پنهان اضافه شود. این در درجه اول برای توسعه محلی مفید است که در آن چندین سایت ممکن است از همان مبدا http://localhost:port سرویس‌دهی شوند.

  • پاکسازیحافظه‌های نهان قدیمی

    بولی اختیاری

    مقدار پیش‌فرض: نادرست

    اینکه آیا Workbox باید تلاش کند تا هرگونه precaches ایجاد شده توسط نسخه‌های قدیمی‌تر و ناسازگار را شناسایی و حذف کند یا خیر.

  • مشتریانادعا

    بولی اختیاری

    مقدار پیش‌فرض: نادرست

    اینکه آیا سرویس ورکر باید به محض فعال شدن، کنترل کلاینت‌های موجود را شروع کند یا خیر.

  • فهرست دایرکتوری

    رشته اختیاری

    اگر درخواست ناوبری برای URL ای که به / ختم می‌شود با یک URL از پیش ذخیره شده مطابقت نداشته باشد، این مقدار به URL اضافه می‌شود و برای تطابق با precache بررسی می‌شود. این مقدار باید با آنچه وب سرور شما برای فهرست دایرکتوری خود استفاده می‌کند، تنظیم شود.

  • غیرفعال کردن DevLogs

    بولی اختیاری

    مقدار پیش‌فرض: نادرست

  • نادیده گرفتن پارامترهای URL

    عبارت منظم[] اختیاری

    هر نام پارامتر جستجو که با یکی از RegExp های این آرایه مطابقت داشته باشد، قبل از جستجوی تطابق precache حذف خواهد شد. این در صورتی مفید است که کاربران شما ممکن است URL هایی را درخواست کنند که حاوی، به عنوان مثال، پارامترهای URL مورد استفاده برای ردیابی منبع ترافیک باشند. در صورت عدم ارائه، مقدار پیش فرض [/^utm_/, /^fbclid$/] است.

  • اسکریپت‌های وارداتی

    رشته[] اختیاری

    فهرستی از فایل‌های جاوا اسکریپت که باید به importScripts() درون فایل تولید شده‌ی سرویس ورکر ارسال شوند. این مورد زمانی مفید است که می‌خواهید به Workbox اجازه دهید فایل سرویس ورکر سطح بالای شما را ایجاد کند، اما می‌خواهید کد اضافی مانند یک شنونده‌ی رویداد push را نیز در آن بگنجانید.

  • inlineWorkboxRuntime

    بولی اختیاری

    مقدار پیش‌فرض: نادرست

    اینکه آیا کد زمان اجرا برای کتابخانه Workbox باید در سرویس ورکر سطح بالا گنجانده شود یا به یک فایل جداگانه تقسیم شود که باید در کنار سرویس ورکر مستقر شود. جدا نگه داشتن زمان اجرا به این معنی است که کاربران مجبور نیستند هر بار که سرویس ورکر سطح بالای شما تغییر می‌کند، کد Workbox را دوباره دانلود کنند.

  • حالت

    رشته اختیاری

    مقدار پیش‌فرض: "تولید"

    اگر روی «production» تنظیم شود، یک بسته‌ی بهینه‌شده‌ی سرویس ورکر که اطلاعات اشکال‌زدایی را شامل نمی‌شود، تولید خواهد شد. اگر به صراحت در اینجا پیکربندی نشده باشد، از مقدار process.env.NODE_ENV استفاده می‌شود و در غیر این صورت، به 'production' برمی‌گردد.

  • پیمایشبازگشت

    رشته اختیاری

    مقدار پیش‌فرض: تهی

    در صورت مشخص شدن، تمام درخواست‌های ناوبری برای URLهایی که از قبل ذخیره نشده‌اند، با HTML موجود در URL ارائه شده انجام می‌شوند. شما باید URL یک سند HTML را که در مانیفست precache شما فهرست شده است، ارسال کنید. این برای استفاده در سناریوی برنامه تک صفحه‌ای در نظر گرفته شده است، که در آن می‌خواهید همه ناوبری‌ها از HTML پوسته برنامه مشترک استفاده کنند.

  • فهرست مجاز پیمایش

    عبارت منظم[] اختیاری

    یک آرایه اختیاری از عبارات منظم که مشخص می‌کند رفتار پیکربندی‌شده‌ی navigateFallback روی کدام URLها اعمال شود. این مورد زمانی مفید است که فقط زیرمجموعه‌ای از URLهای سایت شما باید به عنوان بخشی از یک برنامه‌ی تک‌صفحه‌ای در نظر گرفته شوند. اگر هر دو navigateFallbackDenylist و navigateFallbackAllowlist پیکربندی شده باشند، لیست denylist اولویت دارد.

    نکته : این RegExpها ممکن است در طول پیمایش، در برابر هر URL مقصد ارزیابی شوند. از استفاده از RegExpهای پیچیده خودداری کنید، در غیر این صورت ممکن است کاربران شما هنگام پیمایش سایت شما با تأخیر مواجه شوند.

  • پیمایشبازگشتبه‌عقبردلیست

    عبارت منظم[] اختیاری

    یک آرایه اختیاری از عبارات منظم که مشخص می‌کند رفتار پیکربندی‌شده‌ی navigateFallback روی کدام URLها اعمال شود. این مورد زمانی مفید است که فقط زیرمجموعه‌ای از URLهای سایت شما باید به عنوان بخشی از یک برنامه‌ی تک‌صفحه‌ای در نظر گرفته شوند. اگر هر دو navigateFallbackDenylist و navigateFallbackAllowlist پیکربندی شده باشند، لیست لغو اولویت دارد.

    نکته : این RegExpها ممکن است در طول پیمایش، در برابر هر URL مقصد ارزیابی شوند. از استفاده از RegExpهای پیچیده خودداری کنید، در غیر این صورت ممکن است کاربران شما هنگام پیمایش سایت شما با تأخیر مواجه شوند.

  • ناوبریپیش‌بارگذاری

    بولی اختیاری

    مقدار پیش‌فرض: نادرست

    فعال کردن یا نکردن پیش‌بارگذاری ناوبری در سرویس ورکر تولید شده. وقتی روی true تنظیم شود، باید از runtimeCaching نیز برای تنظیم یک استراتژی پاسخ مناسب که با درخواست‌های ناوبری مطابقت دارد و از پاسخ از پیش بارگذاری شده استفاده می‌کند، استفاده کنید.

  • آفلاینگوگل آنالیتیکس

    بولی | GoogleAnalyticsInitializeOptions اختیاری

    مقدار پیش‌فرض: نادرست

    کنترل می‌کند که آیا پشتیبانی از گوگل آنالیتیکس آفلاین را شامل شود یا خیر. وقتی true ، فراخوانی تابع initialize() در workbox-google-analytics به سرویس ورکر تولید شده شما اضافه می‌شود. وقتی روی یک Object تنظیم شود، آن شیء به فراخوانی initialize() ارسال می‌شود و به شما امکان می‌دهد رفتار را سفارشی کنید.

  • ذخیره سازی در زمان اجرا

    ذخیره سازی در زمان اجرا [] اختیاری

    هنگام استفاده از ابزارهای ساخت Workbox برای تولید سرویس ورکر خود، می‌توانید یک یا چند پیکربندی ذخیره‌سازی زمان اجرا را مشخص کنید. سپس این پیکربندی‌ها با استفاده از پیکربندی match و handler که تعریف می‌کنید، به فراخوانی‌های workbox-routing.registerRoute ترجمه می‌شوند.

    برای مشاهده‌ی تمام گزینه‌ها، به مستندات workbox-build.RuntimeCaching مراجعه کنید. مثال زیر یک پیکربندی معمول را نشان می‌دهد که در آن دو مسیر زمان اجرا تعریف شده است:

  • انتظار کشیدن

    بولی اختیاری

    مقدار پیش‌فرض: نادرست

    آیا یک فراخوانی بی‌قید و شرط برای skipWaiting() به سرویس ورکر تولید شده اضافه شود یا خیر. اگر false ، یک شنونده message به جای آن اضافه می‌شود و به صفحات کلاینت اجازه می‌دهد تا با فراخوانی postMessage({type: 'SKIP_WAITING'}) روی یک سرویس ورکر در حال انتظار، skipWaiting() فعال کنند.

  • منبع مپ

    بولی اختیاری

    مقدار پیش‌فرض: درست

    آیا برای فایل‌های تولید شده‌ی سرویس ورکر، یک نقشه منبع (sourcemap) ایجاد شود یا خیر.

GenerateSWOptions

نوع

BasePartial و GlobPartial و GeneratePartial و RequiredSWDestPartial و OptionalGlobDirectoryPartial

GetManifestOptions

نوع

BasePartial و GlobPartial و RequiredGlobDirectoryPartial

GetManifestResult

خواص

  • بشمار

    شماره

  • مانیفست ورودی‌ها

    ورودی مانیفست []

  • اندازه

    شماره

  • هشدارها

    رشته[]

GlobPartial

خواص

  • دنبال کردن

    بولی اختیاری

    مقدار پیش‌فرض: درست

    تعیین می‌کند که آیا هنگام تولید مانیفست precache، پیوندهای نمادین دنبال شوند یا خیر. برای اطلاعات بیشتر، به تعریف follow در مستندات glob مراجعه کنید.

  • نادیده گرفتن‌های جهانی

    رشته[] اختیاری

    مقدار پیش‌فرض: ["**\/node_modules\/**\/*"]

    مجموعه‌ای از الگوها که با فایل‌هایی که همیشه هنگام تولید مانیفست precache حذف می‌شوند، مطابقت دارند. برای اطلاعات بیشتر، به تعریف ignore در مستندات glob مراجعه کنید.

  • الگوهای جهانی

    رشته[] اختیاری

    مقدار پیش‌فرض: ["**\/*.{js,wasm,css,html}"]

    فایل‌هایی که با هر یک از این الگوها مطابقت داشته باشند، در مانیفست precache گنجانده خواهند شد. برای اطلاعات بیشتر، به پرایمر glob مراجعه کنید.

  • قالب‌های URL

    شیء اختیاری

    اگر یک URL بر اساس منطق سمت سرور رندر شود، محتوای آن ممکن است به چندین فایل یا به مقدار رشته‌ای منحصر به فرد دیگری وابسته باشد. کلیدهای موجود در این شیء، URLهای رندر شده توسط سرور هستند. اگر مقادیر آرایه‌ای از رشته‌ها باشند، به عنوان الگوهای glob تفسیر می‌شوند و محتوای هر فایلی که با این الگوها مطابقت داشته باشد، برای نسخه‌بندی منحصر به فرد URL استفاده می‌شود. اگر با یک رشته واحد استفاده شود، به عنوان اطلاعات نسخه‌بندی منحصر به فردی که برای یک URL مشخص ایجاد کرده‌اید، تفسیر می‌شود.

InjectManifestOptions

نوع

BasePartial و GlobPartial و InjectPartial و RequiredSWDestPartial و RequiredGlobDirectoryPartial

InjectPartial

خواص

  • نقطه تزریق

    رشته اختیاری

    مقدار پیش‌فرض: "self.__WB_MANIFEST"

    رشته‌ای که باید درون فایل swSrc پیدا شود. پس از پیدا شدن، با precache manifest تولید شده جایگزین خواهد شد.

  • swSrc

    رشته

    مسیر و نام فایل سرویس ورکر که در طول فرآیند ساخت، نسبت به دایرکتوری کاری فعلی خوانده خواهد شد.

ManifestEntry

خواص

  • صداقت

    رشته اختیاری

  • تجدید نظر

    رشته

  • آدرس اینترنتی

    رشته

ManifestTransform()

workbox-build.ManifestTransform(
  manifestEntries: (ManifestEntry & object)[],
  compilation?: unknown,
): Promise<ManifestTransformResult> | ManifestTransformResult

نوع

تابع

پارامترها

  • مانیفست ورودی‌ها

    ( ورودی مانیفست و شیء)[]

    • اندازه

      شماره

  • تدوین

    اختیاری ناشناخته

بازگشت‌ها

ManifestTransformResult

خواص

OptionalGlobDirectoryPartial

خواص

  • دایرکتوری جهانی

    رشته اختیاری

    دایرکتوری محلی که می‌خواهید globPatterns با آن مطابقت دهید. این مسیر نسبت به دایرکتوری فعلی است.

RequiredGlobDirectoryPartial

خواص

  • دایرکتوری جهانی

    رشته

    دایرکتوری محلی که می‌خواهید globPatterns با آن مطابقت دهید. این مسیر نسبت به دایرکتوری فعلی است.

RequiredSWDestPartial

خواص

  • swDest

    رشته

    مسیر و نام فایل سرویس ورکر که توسط فرآیند ساخت ایجاد می‌شود، نسبت به دایرکتوری کاری فعلی. باید به '.js' ختم شود.

RuntimeCaching

خواص