جعبه کار-پنجره

بسته workbox-window مجموعه‌ای از ماژول‌ها است که در چارچوب window اجرا می‌شوند، یعنی در داخل صفحات وب شما. آنها مکملی برای بسته های جعبه کاری دیگر هستند که در سرویس کار اجرا می شوند.

ویژگی‌ها/اهداف کلیدی workbox-window عبارتند از:

• برای ساده‌سازی فرآیند ثبت‌نام و به‌روزرسانی‌های کارگر خدماتی با کمک به توسعه‌دهندگان برای شناسایی بحرانی‌ترین لحظات در چرخه عمر کارمند خدمات ، و آسان‌تر کردن پاسخگویی به آن لحظات.
• برای کمک به جلوگیری از مرتکب شدن رایج ترین اشتباهات توسط توسعه دهندگان.
• برای فعال کردن ارتباط راحت‌تر بین کدهای در حال اجرا در سرویس‌کار و کدهای در حال اجرا در پنجره.

وارد کردن و استفاده از workbox-window

نقطه ورود اولیه برای بسته workbox-window کلاس Workbox است و می‌توانید آن را در کد خود از CDN ما یا با استفاده از هر یک از ابزارهای بسته‌بندی محبوب جاوا اسکریپت وارد کنید.

با استفاده از CDN ما

ساده ترین راه برای وارد کردن کلاس Workbox در سایت شما از CDN ما است:

<script type="module">
  import {Workbox} from 'https://storage.googleapis.com/workbox-cdn/releases/6.4.1/workbox-window.prod.mjs';

  if ('serviceWorker' in navigator) {
    const wb = new Workbox('/sw.js');

    wb.register();
  }
</script>

توجه داشته باشید که این مثال از <script type="module"> و دستور import برای بارگیری کلاس Workbox استفاده می کند. اگرچه ممکن است فکر کنید که باید این کد را ترجمه کنید تا در مرورگرهای قدیمی کار کند، اما در واقع این کار ضروری نیست.

همه مرورگرهای اصلی که از Worker Service پشتیبانی می‌کنند، از ماژول‌های جاوا اسکریپت بومی نیز پشتیبانی می‌کنند ، بنابراین ارائه این کد به هر مرورگر بسیار خوب است (مرورگرهای قدیمی‌تر فقط آن را نادیده می‌گیرند).

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

در حالی که برای استفاده از workbox-window مطلقاً هیچ ابزاری لازم نیست، اگر زیرساخت توسعه شما قبلاً شامل بسته‌ای مانند webpack یا Rollup است که با وابستگی‌های npm کار می‌کند، می‌توانید از آن‌ها برای بارگیری workbox-window استفاده کنید.

اولین گام این است که workbox-window به عنوان وابستگی برنامه خود نصب کنید :

npm install workbox-window

سپس، در یکی از فایل های جاوا اسکریپت برنامه خود، جعبه کاری را با ارجاع به نام بسته workbox-window import :

import {Workbox} from 'workbox-window';

if ('serviceWorker' in navigator) {
  const wb = new Workbox('/sw.js');

  wb.register();
}

اگر بسته‌کننده شما از تقسیم کد از طریق عبارت‌های واردات پویا پشتیبانی می‌کند، می‌توانید به صورت مشروط workbox-window بارگیری کنید، که به کاهش اندازه بسته اصلی صفحه شما کمک می‌کند.

با وجود اینکه workbox-window بسیار کوچک است، دلیلی وجود ندارد که با منطق برنامه اصلی سایت شما بارگذاری شود، زیرا کارگران خدمات، به دلیل ماهیت خود، یک پیشرفت پیشرونده هستند.

if ('serviceWorker' in navigator) {
  const {Workbox} = await import('workbox-window');

  const wb = new Workbox('/sw.js');
  wb.register();
}

مفاهیم بسته بندی پیشرفته

برخلاف بسته‌های Workbox که در سرویس‌کار اجرا می‌شوند، فایل‌های ساختی که توسط فیلدهای main و module workbox-window در package.json ارجاع می‌شوند به ES5 منتقل می‌شوند. این باعث می‌شود که آنها با ابزارهای ساخت امروزی سازگار باشند—بعضی از آنها به توسعه‌دهندگان اجازه نمی‌دهند تا چیزی از وابستگی‌های node_module خود را تغییر دهند.

اگر سیستم ساخت شما به شما این امکان را می دهد که وابستگی های خود را ترانسپایل کنید (یا اگر نیازی به ترانسپایل کردن کدهای خود ندارید)، بهتر است به جای خود بسته، یک فایل منبع خاص را وارد کنید.

در اینجا روش‌های مختلفی که می‌توانید Workbox وارد کنید، همراه با توضیحی در مورد آنچه که هر کدام برمی‌گردانند آورده شده است:

// Imports a UMD version with ES5 syntax
// (pkg.main: "build/workbox-window.prod.umd.js")
const {Workbox} = require('workbox-window');

// Imports the module version with ES5 syntax
// (pkg.module: "build/workbox-window.prod.es5.mjs")
import {Workbox} from 'workbox-window';

// Imports the module source file with ES2015+ syntax
import {Workbox} from 'workbox-window/Workbox.mjs';

نمونه ها

هنگامی که کلاس Workbox را وارد کردید، می توانید از آن برای ثبت نام و تعامل با سرویس دهنده خود استفاده کنید. در اینجا چند نمونه از روش هایی وجود دارد که می توانید از Workbox در برنامه خود استفاده کنید:

یک سرویس‌کار را ثبت کنید و اولین بار که سرویس‌کار فعال است به کاربر اطلاع دهید

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

const wb = new Workbox('/sw.js');

wb.addEventListener('activated', event => {
  // `event.isUpdate` will be true if another version of the service
  // worker was controlling the page when this version was registered.
  if (!event.isUpdate) {
    console.log('Service worker activated for the first time!');

    // If your service worker is configured to precache assets, those
    // assets should all be available now.
  }
});

// Register the service worker after event listeners have been added.
wb.register();

اگر سرویس‌کار نصب کرده است اما منتظر فعال‌سازی است، به کاربر اطلاع دهید

هنگامی که صفحه ای که توسط یک سرویس دهنده موجود کنترل می شود، یک سرویس دهنده جدید را ثبت می کند، به طور پیش فرض آن سرویس دهنده فعال نمی شود تا زمانی که همه مشتریان تحت کنترل سرویس دهنده اولیه به طور کامل بارگیری نشده باشند.

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

برای کمک به به حداقل رساندن سردرگمی و روشن شدن زمان وقوع این وضعیت، کلاس Workbox یک رویداد waiting ارائه می‌کند که می‌توانید به آن گوش دهید:

const wb = new Workbox('/sw.js');

wb.addEventListener('waiting', event => {
  console.log(
    `A new service worker has installed, but it can't activate` +
      `until all tabs running the current version have fully unloaded.`
  );
});

// Register the service worker after event listeners have been added.
wb.register();

کاربر را از به‌روزرسانی‌های حافظه پنهان از بسته workbox-broadcast-update مطلع کنید

بسته workbox-broadcast-update یک راه عالی برای ارائه محتوا از حافظه پنهان (برای تحویل سریع) است و در عین حال می‌توانید کاربر را از به‌روزرسانی‌های آن محتوا مطلع کنید (با استفاده از استراتژی کهنه در حالی که اعتبار مجدد دارد ).

برای دریافت آن به‌روزرسانی‌ها از پنجره، می‌توانید به رویدادهای message از نوع CACHE_UPDATED گوش دهید:

const wb = new Workbox('/sw.js');

wb.addEventListener('message', event => {
  if (event.data.type === 'CACHE_UPDATED') {
    const {updatedURL} = event.data.payload;

    console.log(`A newer version of ${updatedURL} is available!`);
  }
});

// Register the service worker after event listeners have been added.
wb.register();

لیستی از URL ها را به سرویس کش ارسال کنید

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

برای برنامه‌های دسته دوم، ممکن است منطقی باشد که فقط دارایی‌هایی را که کاربر برای صفحه خاصی که بازدید کرده است، در حافظه پنهان نگه دارند. هنگام استفاده از بسته workbox-routing ، می‌توانید فهرستی از URL‌ها را به روتر خود ارسال کنید و آن URL‌ها را طبق قوانینی که روی خود روتر تعریف شده است ذخیره می‌کند.

این مثال لیستی از URL های بارگذاری شده توسط صفحه را هر زمان که یک سرویس دهنده جدید فعال شود به روتر ارسال می کند. توجه داشته باشید، ارسال همه URL ها خوب است زیرا فقط URL هایی که با یک مسیر تعریف شده در سرویس دهنده مطابقت دارند، در حافظه پنهان ذخیره می شوند:

const wb = new Workbox('/sw.js');

wb.addEventListener('activated', event => {
  // Get the current page URL + all resources the page loaded.
  const urlsToCache = [
    location.href,
    ...performance.getEntriesByType('resource').map(r => r.name),
  ];
  // Send that list of URLs to your router in the service worker.
  wb.messageSW({
    type: 'CACHE_URLS',
    payload: {urlsToCache},
  });
});

// Register the service worker after event listeners have been added.
wb.register();

لحظات مهم چرخه عمر کارگر خدمات

چرخه عمر کارگر خدماتی پیچیده است و درک کامل آن می تواند چالشی باشد. بخشی از دلیل پیچیده بودن آن این است که باید تمام موارد لبه را برای همه استفاده‌های احتمالی کارگر خدماتی (مانند ثبت نام بیش از یک کارگر خدماتی، ثبت نام سرویس‌کاران مختلف در چارچوب‌های مختلف، ثبت نام کارگران خدماتی با نام‌های مختلف و غیره) انجام دهد.

اما اکثر توسعه دهندگانی که سرویس worker را پیاده سازی می کنند نباید نگران همه این موارد لبه باشند زیرا استفاده از آنها بسیار ساده است. اکثر توسعه دهندگان فقط یک سرویس دهنده را در هر بارگذاری صفحه ثبت می کنند و نام فایل Service Worker که در سرور خود مستقر می کنند را تغییر نمی دهند .

کلاس Workbox این نمای ساده‌تر را برای چرخه عمر کارگر خدماتی با تقسیم کردن تمام ثبت‌های سرویس‌کار به دو دسته می‌پذیرد: سرویس‌کار ثبت‌شده خود نمونه و کارگر خدمات خارجی:

• Registered Service Worker : یک سرویس‌کار که نصب را در نتیجه‌ی مثال Workbox فراخوانی register() شروع کرده است یا اگر با register() تماس می‌گیرد رویداد updatefound را در ثبت نام راه‌اندازی نمی‌کند.
• External Service Worker: یک سرویس‌کار که نصب را مستقل از Workbox register() شروع کرده است. این معمولاً زمانی اتفاق می‌افتد که کاربر نسخه جدیدی از سایت شما را در برگه دیگری باز کند. هنگامی که یک رویداد از یک سرویس دهنده خارجی منشا می گیرد، ویژگی isExternal رویداد روی true تنظیم می شود.

با در نظر گرفتن این دو نوع کارمند خدماتی، در اینجا خلاصه‌ای از تمام لحظات مهم چرخه عمر سرویس‌دهنده، همراه با توصیه‌های توسعه‌دهنده برای نحوه رسیدگی به آنها آورده شده است:

اولین باری که یک سرویسکار نصب می شود

احتمالاً می خواهید با اولین باری که یک سرویس دهنده نصب می کند، با نحوه برخورد شما با تمام به روز رسانی های آینده متفاوت رفتار کنید.

در workbox-window ، می‌توانید با بررسی ویژگی isUpdate در هر یک از رویدادهای زیر، بین اولین نصب نسخه و به‌روزرسانی‌های بعدی تفاوت قائل شوید. برای اولین نصب، isUpdate false خواهد بود.

const wb = new Workbox('/sw.js');

wb.addEventListener('installed', event => {
  if (!event.isUpdate) {
    // First-installed code goes here...
  }
});

wb.register();

هنگامی که نسخه به روز شده سرویس کارگر پیدا می شود

وقتی یک سرویس‌کار جدید شروع به نصب می‌کند اما نسخه موجود در حال حاضر صفحه را کنترل می‌کند، ویژگی isUpdate همه رویدادهای زیر true خواهد بود.

نحوه واکنش شما در این شرایط معمولاً با اولین نصب متفاوت است زیرا باید مدیریت کنید که کاربر چه زمانی و چگونه این به‌روزرسانی را دریافت کند.

هنگامی که یک نسخه غیرمنتظره از Service Worker پیدا شد

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

سناریویی را در نظر بگیرید که در آن تب A نسخه 1 سایت شما را اجرا می کند و تب B نسخه 2 را اجرا می کند. وقتی برگه B بارگیری می‌شود، توسط نسخه سرویسکار شما که با v1 ارسال شده کنترل می‌شود، اما صفحه بازگردانده شده توسط سرور (اگر از استراتژی ذخیره‌سازی اول شبکه برای درخواست‌های ناوبری شما استفاده می‌کند) شامل تمام دارایی‌های v2 شما خواهد بود.

این معمولاً برای تب B مشکلی ندارد، زیرا زمانی که کد v2 خود را نوشتید، از نحوه عملکرد کد v1 خود آگاه بودید. با این حال، ممکن است برای برگه A مشکل ایجاد کند، زیرا کد v1 شما احتمالاً نمی‌تواند پیش‌بینی کند که کد v2 شما چه تغییراتی را ایجاد می‌کند.

برای کمک به مدیریت این موقعیت‌ها، workbox-window همچنین رویدادهای چرخه حیات را هنگامی که به‌روزرسانی از یک سرویس‌دهنده «خارجی» تشخیص می‌دهد، ارسال می‌کند، که در آن خارجی فقط به معنای هر نسخه‌ای است که نسخه‌ای نیست که نمونه Workbox فعلی ثبت شده است.

از Workbox نسخه 6 به بعد، این رویدادها معادل رویدادهای مستند شده در بالا هستند، با افزودن یک ویژگی isExternal: true بر روی هر شی رویداد. اگر برنامه وب شما نیاز به پیاده‌سازی منطق خاصی برای مدیریت یک سرویس‌کار «خارجی» دارد، می‌توانید آن ویژگی را در کنترل‌کننده‌های رویداد خود بررسی کنید.

اجتناب از اشتباهات رایج

یکی از مفیدترین ویژگی‌هایی که Workbox ارائه می‌کند، ثبت برنامه‌نویس آن است. و این به ویژه برای workbox-window صادق است.

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

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

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

علاوه بر این، یک اشتباه رایج که توسعه دهندگان در اولین استفاده از Service Worker مرتکب می شوند این است که یک سرویس دهنده را در محدوده اشتباه ثبت نام می کنند.

برای جلوگیری از این اتفاق، اگر صفحه ثبت‌کننده سرویس‌کار در محدوده آن سرویس‌کار نباشد، کلاس Workbox به شما هشدار می‌دهد. همچنین در مواردی که سرویس دهنده شما فعال است اما هنوز صفحه را کنترل نکرده است به شما هشدار می دهد:

پنجره ای برای خدمات ارتباط کارگر

بیشتر استفاده از سرویس‌کار پیشرفته شامل پیام‌های زیادی بین کارمند سرویس و پنجره است. کلاس Workbox نیز با ارائه یک متد messageSW() به این امر کمک می‌کند، که سرویس‌کار ثبت‌شده نمونه postMessage() می‌کند و منتظر پاسخ می‌ماند.

در حالی که می‌توانید داده‌ها را در هر قالبی برای سرویس‌کار ارسال کنید، فرمت به اشتراک‌گذاشته‌شده توسط همه بسته‌های Workbox یک شی با سه ویژگی است (دو مورد آخر اختیاری است):

پیام هایی که از طریق متد messageSW() ارسال می شوند از MessageChannel استفاده می کنند تا گیرنده بتواند به آنها پاسخ دهد. برای پاسخ دادن به یک پیام، می توانید در شنونده رویداد پیام خود event.ports[0].postMessage(response) را فراخوانی کنید. متد messageSW() قولی را برمی‌گرداند که به هر response که با آن پاسخ دهید حل می‌شود.

در اینجا نمونه ای از ارسال پیام از پنجره به سرویس دهنده و دریافت پاسخ است. بلوک کد اول شنونده پیام در سرویس کارگر است و بلوک دوم از کلاس Workbox برای ارسال پیام و منتظر پاسخ استفاده می کند:

کد در sw.js:

const SW_VERSION = '1.0.0';

addEventListener('message', event => {
  if (event.data.type === 'GET_VERSION') {
    event.ports[0].postMessage(SW_VERSION);
  }
});

کد در main.js (در حال اجرا در پنجره):

const wb = new Workbox('/sw.js');
wb.register();

const swVersion = await wb.messageSW({type: 'GET_VERSION'});
console.log('Service Worker version:', swVersion);

مدیریت ناسازگاری های نسخه

مثال بالا نشان می دهد که چگونه می توانید بررسی نسخه service worker را از پنجره اجرا کنید. این مثال به این دلیل استفاده می‌شود که وقتی در حال ارسال پیام‌ها بین پنجره و سرویس‌دهنده هستید، بسیار مهم است که توجه داشته باشید که سرویس‌کار شما ممکن است همان نسخه‌ای از سایت شما را اجرا نکند که کد صفحه شما اجرا می‌کند، و راه حل برای مقابله با این مشکل بسته به اینکه صفحات خود را در شبکه اول یا حافظه پنهان ارائه می دهید متفاوت است.

اول شبکه

هنگامی که ابتدا شبکه صفحات خود را سرویس می دهید، کاربران شما همیشه آخرین نسخه HTML شما را از سرور شما دریافت می کنند. با این حال، اولین باری که کاربر از سایت شما بازدید مجدد می‌کند (پس از به‌روزرسانی شما)، HTML دریافتی مربوط به آخرین نسخه خواهد بود، اما سرویس‌کارگر که در مرورگر او اجرا می‌شود، نسخه‌ای است که قبلاً نصب شده است (احتمالاً بسیاری از نسخه‌های قدیمی) .

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

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

به عنوان مثال، در کد بالا، اگر نسخه service worker که توسط آن فراخوانی messageSW() برگردانده شده است قدیمی‌تر از نسخه مورد انتظار باشد، عاقلانه است که منتظر بمانید تا یک به‌روزرسانی پیدا شود (که باید هنگام فراخوانی register() اتفاق بیفتد. در آن مرحله می‌توانید به کاربر یا به‌روزرسانی اطلاع دهید، یا می‌توانید به صورت دستی از مرحله انتظار رد شوید تا فوراً سرویس‌کار جدید فعال شود.

ابتدا کش

بر خلاف زمانی که صفحات را در ابتدا به شبکه سرویس می دهید، هنگام سرویس کشی صفحات خود ابتدا، می دانید که صفحه شما در ابتدا همیشه همان نسخه سرویس دهنده شما خواهد بود (زیرا این همان چیزی است که به آن سرویس می دهد). و در نتیجه، استفاده از messageSW() بلافاصله بی خطر است.

با این حال، اگر یک نسخه به‌روزرسانی‌شده از service worker شما پیدا شود و زمانی که صفحه شما register() تماس می‌گیرد فعال می‌شود (یعنی عمداً از مرحله انتظار رد می‌شوید )، ممکن است دیگر ارسال پیام به آن امن نباشد.

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

رد شدن از انتظار یاری

یک قرارداد متداول برای پیام‌رسانی کارگر پنجره به سرویس، ارسال یک پیام {type: 'SKIP_WAITING'} است تا به سرویس‌کار نصب شده دستور دهید مرحله انتظار را رد کند و فعال شود.

با شروع با Workbox v6، از متد messageSkipWaiting() می‌توان برای ارسال پیام {type: 'SKIP_WAITING'} به کارگر خدمات انتظار مرتبط با ثبت نام کارگر فعلی استفاده کرد. اگر یک کارگر منتظر وجود نداشته باشد، بی سر و صدا هیچ کاری انجام نمی دهد.

workbox-window.messageSW(
  sw: ServiceWorker,
  data: object,
)