مهاجرت از Workbox v2 به v3، مهاجرت از Workbox v2 به v3

این راهنما بر روی شکستن تغییرات ارائه شده در Workbox v3 متمرکز شده است، با نمونه هایی از تغییراتی که باید هنگام ارتقاء از تنظیمات Workbox v2 ایجاد کنید.

اگر در حال حاضر از ترکیب قدیمی sw-precache / sw-toolbox استفاده می کنید و برای اولین بار به دنبال انتقال به Workbox هستید، در اینجا یک راهنمای انتقال متفاوت وجود دارد که به شما کمک خواهد کرد.

v3 پس زمینه

نسخه نسخه 3 Workbox نشان‌دهنده بازسازی قابل توجهی از پایگاه کد موجود است. اهداف اصلی عبارتند از:

• اندازه صندوق کار را به حداقل برسانید. مقدار کد زمان اجرا سرویس کارگری که دانلود و اجرا شده است کاهش یافته است. به جای انتخاب همه افراد در یک بسته یکپارچه، فقط کد برای ویژگی‌های خاصی که استفاده می‌کنید در زمان اجرا وارد می‌شود.
• Workbox یک CDN دارد. ما میزبانی CDN مبتنی بر Google Cloud Storage را به‌عنوان گزینه‌ای متعارف برای دسترسی به کتابخانه‌های زمان اجرا Workbox ارائه می‌کنیم که راه‌اندازی و اجرای آن را با Workbox آسان‌تر می‌کند.
• اشکال زدایی بهتر و سیاهههای مربوط. تجربه اشکال زدایی و ورود به سیستم بسیار بهبود یافته است. هر زمان که Workbox از مبدا localhost استفاده می شود و همه گزارش ها و ادعاها از بیلدهای تولید حذف می شوند، گزارش های اشکال زدایی به طور پیش فرض فعال می شوند.
• پلاگین بسته وب بهبود یافته. workbox-webpack-plugin نزدیک‌تر با فرآیند ساخت پک وب ادغام می‌شود و زمانی که می‌خواهید تمام دارایی‌های موجود در خط لوله ساخت را پیش کش کنید، امکان استفاده با پیکربندی صفر را فراهم می‌کند.

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

شکستن تغییرات

پیکربندی ساخت

تغییرات زیر بر رفتار همه ابزارهای ساخت ما تأثیر می گذارد ( workbox-build ، workbox-cli ، workbox-webpack-plugin )، که مجموعه مشترکی از گزینه های پیکربندی را به اشتراک می گذارند.

• نام کنترل‌کننده 'fastest' قبلاً معتبر بود، و هنگام پیکربندی runtimeCaching ، به‌عنوان نام مستعار 'staleWhileRevalidate' در نظر گرفته می‌شد. دیگر معتبر نیست و توسعه‌دهندگان باید مستقیماً از 'staleWhileRevalidate' استفاده کنند.
• چندین نام ویژگی runtimeCaching.options به‌روزرسانی شده‌اند، و اعتبارسنجی پارامتر اضافی وجود دارد که در صورت استفاده از پیکربندی نامعتبر، باعث می‌شود یک ساخت با شکست مواجه شود. برای فهرستی از گزینه های پشتیبانی شده در حال حاضر به مستندات مربوط به runtimeCaching مراجعه کنید.

جعبه کار-پس زمینه-همگام سازی

• پارامتر پیکربندی maxRetentionTime اکنون به جای چند میلی ثانیه به عنوان تعداد دقیقه تفسیر می شود.
• اکنون یک رشته مورد نیاز وجود دارد که نشان دهنده نام صف است که باید به عنوان اولین پارامتر هنگام ساخت کلاس Plugin یا مستقل ارسال شود. (قبلاً به عنوان یکی از ویژگی‌های گزینه‌ها ارسال شده بود.) با اسناد سطح به‌روزرسانی‌شده API مشورت کنید.

Workbox-broadcast-cache-به روزرسانی

• اکنون یک رشته مورد نیاز وجود دارد که نشان دهنده نام کانال است که باید به عنوان اولین پارامتر هنگام ساخت کلاس Plugin یا مستقل ارسال شود.

به عنوان مثال، در v2 کلاس Plugin را به صورت زیر مقداردهی اولیه می کنید:

new workbox.broadcastCacheUpdate.BroadcastCacheUpdatePlugin({
  channelName: 'cache-updates',
  headersToCheck: ['etag'],
});

استفاده معادل در V3:

new workbox.broadcastUpdate.Plugin('cache-updates', {headersToCheck: ['etag']});

با اسناد سطح API به روز شده مشورت کنید.

جعبه کار ساخت

• به‌طور پیش‌فرض، تطبیق الگوی glob اکنون با گزینه‌های follow: true (که به دنبال پیوندهای نمادین می‌آید) و strict: true (که نسبت به خطاهای «غیر معمول» کمتر تحمل می‌کند). با تنظیم globFollow: false و/یا globStrict: false در پیکربندی ساخت، می‌توانید هر یک را غیرفعال کنید و به رفتار قبلی بازگردید.
• توابع در workbox-build همگی یک ویژگی اضافی، warnings ، در پاسخ هایی که برمی گردانند، برمی گردانند. برخی از سناریوهایی که در نسخه 2 به عنوان خطاهای مهلک تلقی می شدند اکنون مجاز هستند، اما از طریق warnings ، که آرایه ای از رشته ها است، گزارش می شوند.

در نسخه 2، شما ممکن است generateSW فراخوانی کنید:

const workboxBuild = require('workbox-build');

workboxBuild.generateSW({...})
  .then(({count, size}) => console.log(`Precached ${count} files, totaling ${size} bytes.`))
  .catch((error) => console.error(`Something went wrong: ${error}`));

در حالی که می توانید از همان کد در نسخه 3 استفاده کنید، بهتر است هر گونه warnings را بررسی کرده و آنها را ثبت کنید:

const workboxBuild = require('workbox-build');

workboxBuild.generateSW({...})
  .then(({count, size, warnings}) => {
    for (const warning of warnings) {
      console.warn(warning);
    }
    console.log(`Precached ${count} files, totalling ${size} bytes.`);
  })
  .catch((error) => console.error(`Something went wrong: ${error}`));

• توسعه دهندگانی که توابع ManifestTransform سفارشی خود را در نسخه 2 نوشته اند باید آرایه مانیفست را در یک شی برگردانند (یعنی به جای return manifestArray; باید از return {manifest warnings return {manifest: manifestArray}; استفاده کنید). باید آرایه ای از رشته ها حاوی اطلاعات هشدار غیر کشنده باشد.

اگر در نسخه 2 یک ManifestTransform سفارشی می‌نوشتید، کدی مانند:

const cdnTransform = manifestEntries => {
  return manifestEntries.map(entry => {
    const cdnOrigin = 'https://example.com';
    if (entry.url.startsWith('/assets/')) {
      entry.url = cdnOrigin + entry.url;
    }
    return entry;
  });
};

دارای معادل v3 از:

const cdnTransform = manifestEntries => {
  const manifest = manifestEntries.map(entry => {
    const cdnOrigin = 'https://example.com';
    if (entry.url.startsWith('/assets/')) {
      entry.url = cdnOrigin + entry.url;
    }
    return entry;
  });
  return {manifest, warnings: []};
};

• تابع getFileManifestEntries() به getManifest() ) تغییر نام داده است، و وعده بازگشتی اکنون شامل اطلاعات اضافی در مورد URLهایی است که از پیش ذخیره شده اند.

کد مانند زیر در v2:

const manifestEntries = await workboxBuild.getFileManifestEntries({...});

را می توان در نسخه 3 به صورت زیر بازنویسی کرد:

const {manifestEntries, count, size, warnings} = await workboxBuild.getManifest({...});

// Use manifestEntries like before.
// Optionally, log the new info returned in count, size, warnings.

• تابع generateFileManifest() حذف شده است. توسعه دهندگان تشویق می شوند به جای آن getManifest() فراخوانی کنند و از پاسخ آن برای نوشتن داده ها بر روی دیسک با فرمت مناسب استفاده کنند.

جعبه کار-کش-انقضا

• API افزونه ثابت مانده است، این حالتی است که اکثر توسعه دهندگان در نهایت از آن استفاده می کنند. با این حال تغییرات قابل توجهی در API وجود دارد که بر توسعه دهندگانی که از آن به عنوان یک کلاس مستقل استفاده می کنند تأثیر می گذارد. با اسناد سطح API به روز شده مشورت کنید.

workbox-cli

توسعه دهندگان می توانند CLI را با پرچم --help برای مجموعه کاملی از پارامترهای پشتیبانی شده اجرا کنند.

• پشتیبانی از نام مستعار workbox-cli برای اسکریپت باینری حذف شده است. باینری اکنون فقط به عنوان workbox قابل دسترسی است.
• دستورات v2 generate:sw و inject:manifest به generateSW و injectManifest در v3 تغییر نام داده اند.
• در نسخه 2، فایل پیکربندی پیش‌فرض (مورد استفاده در زمانی که به صراحت ارائه نشده بود) به عنوان workbox-cli-config.js در فهرست فعلی در نظر گرفته شد. در نسخه 3، workbox-config.js است.

در مجموع، این بدان معنی است که در v2:

$ workbox inject:manifest

فرآیند ساخت "inject manifest" را با استفاده از پیکربندی خوانده شده از workbox-cli-config.js و در نسخه 3 اجرا می کند:

$ workbox injectManifest

همین کار را انجام خواهد داد، اما پیکربندی را از workbox-config.js بخوانید.

جعبه کار-پیش کش

• متد precache() قبلاً هم اصلاحات کش را انجام می داد و هم مسیریابی را برای سرویس دهی ورودی های کش تنظیم می کرد. اکنون، precache() فقط ورودی‌های حافظه پنهان را تغییر می‌دهد، و یک روش جدید، addRoute() برای ثبت مسیری برای ارائه پاسخ‌های کش شده در معرض دید قرار گرفته است. توسعه دهندگانی که عملکرد قبلی و دو در یک را می خواهند می توانند به فراخوانی precacheAndRoute() تغییر دهند.
• چندین گزینه که قبلاً از طریق سازنده WorkboxSW پیکربندی می‌شدند اکنون به عنوان پارامتر options در workbox.precaching.precacheAndRoute([...], options) ارسال می‌شوند. پیش‌فرض‌های آن گزینه‌ها، وقتی پیکربندی نشده باشند، در اسناد مرجع فهرست شده‌اند.
• به طور پیش‌فرض، URL‌هایی که فاقد هر گونه پسوند فایل هستند، به‌طور خودکار برای مطابقت با ورودی حافظه پنهان حاوی .html بررسی می‌شوند. به عنوان مثال، اگر درخواستی برای /path/to/index (که از پیش ذخیره نشده است) انجام شود و یک ورودی از پیش کش برای /path/to/index.html وجود داشته باشد، آن ورودی از پیش ذخیره شده استفاده خواهد شد. توسعه‌دهندگان می‌توانند این رفتار جدید را با تنظیم {cleanUrls: false} هنگام انتقال گزینه‌ها به workbox.precaching.precacheAndRoute() غیرفعال کنند.
• workbox-broadcast-update دیگر به طور خودکار برای اعلام به‌روزرسانی‌های حافظه پنهان برای دارایی‌های از پیش ذخیره‌شده پیکربندی نمی‌شود.

کد زیر در v2:

const workboxSW = new self.WorkboxSW({
  directoryIndex: 'index.html',
  ignoreUrlParametersMatching: [/^utm_/],
  precacheChannelName: 'precache-updates',
});
workboxSW.precache([...]);

دارای معادل v3 از:

workbox.precaching.addPlugins([
    new workbox.broadcastUpdate.Plugin('precache-updates')
]);

workbox.precaching.precacheAndRoute([...], {
  cleanUrls: false,
  directoryIndex: 'index.html',
  ignoreUrlParametersMatching: [/^utm_/],
});

مسیریابی جعبه کار

• برنامه‌نویسانی که قبلاً از workbox-routing از طریق فضای نام workbox.router.* یک WorkboxSW استفاده می‌کردند، باید به فضای نام جدید، workbox.routing.* تغییر مکان دهند.
• مسیرها اکنون به ترتیب اولین ثبت نام-برنده ارزیابی می شوند. این ترتیب مخالف ارزیابی Route است که در v2 استفاده شد، جایی که آخرین Route ثبت‌شده در اولویت قرار می‌گیرد.
• کلاس ExpressRoute و پشتیبانی از حروف عام "سبک اکسپرس" حذف شده است . این امر اندازه workbox-routing را به میزان قابل توجهی کاهش می دهد. رشته‌هایی که به‌عنوان اولین پارامتر برای workbox.routing.registerRoute() استفاده می‌شوند، اکنون به‌عنوان منطبق دقیق تلقی می‌شوند. منطبق‌های عام یا جزئی باید توسط RegExp مدیریت شوند—استفاده از هر RegExp که با بخشی یا تمام URL درخواست مطابقت دارد می‌تواند یک مسیر را راه‌اندازی کند.
• متد کمکی addFetchListener() از کلاس Router حذف شده است. توسعه دهندگان می توانند به طور صریح fetch خود را اضافه کنند یا از رابط ارائه شده توسط workbox.routing استفاده کنند که به طور ضمنی یک کنترل کننده fetch برای آنها ایجاد می کند.
• متدهای registerRoutes() و unregisterRoutes() حذف شدند. نسخه‌های آن روش‌هایی که در یک Route کار می‌کنند تغییری نکرده‌اند، و توسعه‌دهندگانی که نیاز دارند چندین مسیر را به‌طور هم‌زمان ثبت یا لغو ثبت کنند، باید به‌جای آن، یک سری تماس با registerRoute() یا unregisterRoute() برقرار کنند.

کد زیر در v2:

const workboxSW = new self.WorkboxSW();

workboxSW.router.registerRoute(
  '/path/with/.*/wildcard/',
  workboxSW.strategies.staleWhileRevalidate()
);

workboxSW.router.registerRoute(
  new RegExp('^https://example.com/'),
  workboxSW.strategies.networkFirst()
);

دارای معادل v3 از:

workbox.routing.registerRoute(
  new RegExp('^https://example.com/'),
  workbox.strategies.networkFirst()
);

workbox.routing.registerRoute(
  new RegExp('^/path/with/.*/wildcard'),
  workbox.strategies.staleWhileRevalidate()
);

workbox-strategies (که قبلا به عنوان workbox-runtime-caching شناخته می شد)

• ماژول workbox-runtime-caching اکنون رسما به عنوان workbox-strategies شناخته می شود و با نام جدید خود در npm منتشر شده است.
• استفاده از انقضای کش در یک استراتژی بدون ارائه نام کش دیگر معتبر نیست. در نسخه 2 این امکان وجود داشت:

workboxSW.strategies.staleWhileRevalidate({
  cacheExpiration: {maxEntries: 50},
});

این منجر به منقضی شدن ورودی‌ها در حافظه پنهان پیش‌فرض می‌شود که غیرمنتظره است. در نسخه 3، یک نام کش مورد نیاز است:

workboxSW.strategies.staleWhileRevalidate({
  cacheName: 'my-cache',
  plugins: [new workbox.expiration.Plugin({maxEntries: 50})],
});

• روش چرخه حیات cacheWillMatch به cachedResponseWillBeUsed تغییر نام داده است. این نباید یک تغییر قابل مشاهده برای توسعه دهندگان باشد مگر اینکه افزونه های خود را بنویسند که به cacheWillMatch واکنش نشان می دهد.
• نحو تعیین پلاگین ها هنگام پیکربندی استراتژی تغییر کرده است. هر افزونه باید به صراحت در ویژگی plugins پیکربندی استراتژی فهرست شود.

کد زیر در v2:

const workboxSW = new self.WorkboxSW();

const networkFirstStrategy = workboxSW.strategies.networkFirst({
  cacheName: 'my-cache',
  networkTimeoutSeconds: 5,
  cacheExpiration: {
    maxEntries: 50,
  },
  cacheableResponse: {
    statuses: [0, 200],
  },
});

دارای معادل v3 از:

const networkFirstStrategy = workbox.strategies.networkFirst({
  cacheName: 'my-cache',
  networkTimeoutSeconds: 5,
  plugins: [
    new workbox.expiration.Plugin({maxEntries: 50}),
    new workbox.cacheableResponse.Plugin({statuses: [0, 200]}),
  ],
});

در راهنمای " استفاده از افزونه ها " می توانید اطلاعات بیشتری کسب کنید.

جعبه کار-sw

• در زیر هود، workbox-sw بازنویسی شده است تا یک رابط سبک وزن «لودر» باشد که برخی از پیکربندی‌های اولیه را می‌گیرد و مسئول کشیدن سایر ماژول‌هایی است که در زمان اجرا مورد نیاز هستند. به‌جای ساختن نمونه‌ای جدید از کلاس WorkboxSW ، توسعه‌دهندگان با یک نمونه موجود که به‌طور خودکار در فضای نام جهانی نمایش داده می‌شود، تعامل خواهند داشت.

قبلا در نسخه 2:

importScripts('<path to workbox-sw>/importScripts/workbox-sw.prod.v2.1.3.js');

const workbox = new WorkboxSW({
  skipWaiting: true,
  clientsClaim: true,
  // etc.
});

workbox.router.registerRoute(...);

در نسخه 3، شما فقط باید اسکریپت workbox-sw.js را وارد کنید، و یک نمونه آماده به طور خودکار در فضای نام جهانی به عنوان workbox در دسترس خواهد بود:

importScripts('<path to workbox-sw>/3.0.0/workbox-sw.js');

// workbox is implicitly created and ready for use.
workbox.routing.registerRoute(...);

• skipWaiting و clientsClaim دیگر گزینه‌هایی نیستند که به سازنده WorkboxSW منتقل شوند. در عوض، آنها به متدهای workbox.clientsClaim() و workbox.skipWaiting() تغییر یافته‌اند.
• گزینه handleFetch که قبلاً در سازنده v2 پشتیبانی می شد دیگر در نسخه 3 پشتیبانی نمی شود. توسعه‌دهندگانی که برای آزمایش کارمند خدمات خود بدون فراخوانی واکشی نیاز به عملکرد مشابه دارند، می‌توانند از گزینه « Bypass for network » موجود در ابزارهای برنامه‌نویس Chrome استفاده کنند.

workbox-webpack-plugin

این افزونه بطور قابل ملاحظه ای بازنویسی شده است و در بسیاری از موارد می توان از آن در حالت "پیکربندی صفر" استفاده کرد. با اسناد سطح API به روز شده مشورت کنید.

• API اکنون دو کلاس GenerateSW و InjectManifest را در معرض نمایش قرار می دهد. این تغییر حالت‌ها را در مقابل رفتار v2 که در آن رفتار براساس وجود swSrc تغییر می‌کند، واضح می‌سازد.
• به طور پیش‌فرض، دارایی‌های موجود در خط لوله کامپایل پک وب از پیش ذخیره می‌شوند و دیگر نیازی به پیکربندی globPatterns نیست. تنها دلیل برای ادامه استفاده از globPatterns این است که نیاز به پیش کش کردن دارایی هایی دارید که در ساخت بسته وب شما گنجانده نشده اند. به طور کلی، هنگام مهاجرت به پلاگین v3، باید با حذف تمام تنظیمات مبتنی بر glob قبلی خود شروع کنید و فقط در صورت نیاز مجدداً آن را اضافه کنید.

کمک گرفتن

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