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

بسته 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();
لحظه رویداد اقدام توصیه شده
یک سرویسکار جدید نصب شده است (برای اولین بار) installed

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

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

کارگر خدمات کنترل صفحه را شروع کرده است controlling

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

توجه داشته باشید که اولین باری که یک سرویس‌کار را نصب می‌کنید، شروع به کنترل صفحه فعلی نمی‌کند مگر اینکه آن سرویس‌گر در رویداد فعال سازی clients.claim() فراخوانی کند. رفتار پیش فرض این است که منتظر بمانید تا بارگذاری صفحه بعدی شروع به کنترل کنید.

از منظر workbox-window ، این بدان معناست که رویداد controlling فقط در مواردی ارسال می شود که کارگر سرویس clients.claim() فراخوانی می کند. اگر صفحه قبل از ثبت نام کنترل شده باشد، این رویداد ارسال نمی شود.

کارمند خدمات فعال سازی را به پایان رسانده است activated

همانطور که در بالا ذکر شد، اولین باری که یک سرویس دهنده فعال کردن آن را تمام می کند ممکن است (یا ممکن است) کنترل صفحه را شروع کرده باشد.

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

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

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

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

لحظه رویداد اقدام توصیه شده
یک سرویس‌کار جدید نصب کرده است (در حال به‌روزرسانی سرویس قبلی) installed

اگر این اولین نصب سرویس کارگر نیست ( event.isUpdate === true )، به این معنی است که نسخه جدیدتری از service worker پیدا و نصب شده است (یعنی نسخه متفاوتی از نسخه ای که در حال حاضر صفحه را کنترل می کند).

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

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

یک سرویسکار نصب کرده است اما در مرحله انتظار گیر کرده است waiting

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

هشدار! معمولاً توسعه‌دهندگان از کاربران درخواست می‌کنند که برای دریافت به‌روزرسانی، بارگذاری مجدد کنند، اما در بسیاری از موارد بازخوانی صفحه، کارگر نصب‌شده را فعال نمی‌کند . اگر کاربر صفحه را بازخوانی کند و سرویس‌کار همچنان منتظر باشد، رویداد waiting دوباره فعال می‌شود و ویژگی event.wasWaitingBeforeRegister درست خواهد بود. توجه داشته باشید، ما قصد داریم این تجربه را در نسخه بعدی بهبود دهیم. شماره 1848 را برای به روز رسانی دنبال کنید.

گزینه دیگر این است که از کاربر درخواست کنید و بپرسید که آیا می‌خواهد به‌روزرسانی را دریافت کند یا به انتظار ادامه دهد. اگر دریافت به‌روزرسانی را انتخاب کنید، می‌توانید از postMessage() استفاده کنید تا به سرویس‌گر بگویید skipWaiting() اجرا کند. برای نمونه ای از آن، دستور العمل پیشرفته را ببینید که بارگذاری مجدد صفحه برای کاربران ارائه می شود .

کارگر خدمات کنترل صفحه را شروع کرده است controlling

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

توجه: اگر skipWaiting() در سرویس کار خود فراخوانی نکنید، رویداد controlling فعال نمی شود.

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

هنگامی که یک نسخه غیرمنتظره از 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 ، از تمام تغییرات حالت چرخه حیات در کنسول توسعه‌دهنده مطلع می‌شوید، که می‌تواند به رفع اشکال‌زدایی کمک کند که چرا همه چیز آنطور که انتظار دارید نیست.

هشدار کنسول workbox-window برای کارگر منتظر

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

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

هشدار کنسول workbox-window برای کارگر غیر کنترل کننده

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

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

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

اموال مورد نیاز؟ تایپ کنید توضیحات
type بله string

یک رشته منحصر به فرد، شناسایی این پیام.

طبق قرارداد، انواع همه با حروف بزرگ و زیرخط جداکننده کلمات هستند. اگر یک نوع نشان دهنده اقدامی است که باید انجام شود، باید دستوری در زمان حال باشد (مانند CACHE_URLS )، اگر نوع نشان دهنده اطلاعات گزارش شده است، باید در زمان گذشته باشد (مثلا URLS_CACHED ).

meta نه string در Workbox این همیشه نام بسته Workbox ارسال پیام است. هنگام ارسال پیام خود، می توانید این ویژگی را حذف کنید یا آن را روی هر چیزی که دوست دارید تنظیم کنید.
payload نه * داده در حال ارسال معمولاً این یک شی است، اما لازم نیست که باشد.

پیام هایی که از طریق متد 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

کلاسی برای کمک به رسیدگی به ثبت نام، به‌روزرسانی‌ها، و واکنش به رویدادهای چرخه عمر کارکنان خدمات.

خواص

  • سازنده

    باطل

    یک نمونه Workbox جدید با یک URL اسکریپت و گزینه های Service Worker ایجاد می کند. URL و گزینه‌های اسکریپت همان مواردی است که هنگام فراخوانی navigator.serviceWorker.register (scriptURL، گزینه‌ها) استفاده می‌شود.

    تابع constructor به صورت زیر است:

    (scriptURL: string | TrustedScriptURL, registerOptions?: object) => {...}

    • scriptURL

      رشته | TrustedScriptURL

      اسکریپت Service Worker مرتبط با این نمونه. استفاده از TrustedScriptURL پشتیبانی می شود.

    • ثبت گزینه ها

      شی اختیاری

  • فعال

    Promise<ServiceWorker>

  • کنترل کردن

    Promise<ServiceWorker>

  • getSW

    باطل

    با ارجاع به یک سرویس دهنده که با URL اسکریپت این نمونه مطابقت دارد، به محض در دسترس بودن حل می شود.

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

    تابع getSW به نظر می رسد:

    () => {...}

    • برمی گرداند

      Promise<ServiceWorker>

  • پیام SW

    باطل

    شی داده ارسال شده را به سرویس‌کار ثبت‌شده توسط این نمونه ارسال می‌کند (از طریق workbox-window.Workbox#getSW ) و با یک پاسخ (در صورت وجود) حل می‌شود.

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

    تابع messageSW به شکل زیر است:

    (data: object) => {...}

    • داده ها

      شی

      یک شی برای ارسال به کارگر خدمات

    • برمی گرداند

      قول <هر>

  • پیامSkipWaiting

    باطل

    یک پیام {type: 'SKIP_WAITING'} به کارمند خدماتی که در حال حاضر در حالت waiting مرتبط با ثبت نام فعلی است، ارسال می کند.

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

    تابع messageSkipWaiting به نظر می رسد:

    () => {...}

  • ثبت نام کنید

    باطل

    یک سرویس‌کار را برای این نمونه‌ها URL اسکریپت و گزینه‌های Service Worker ثبت می‌کند. به طور پیش فرض این روش ثبت نام را تا زمانی که پنجره بارگذاری شده به تاخیر می اندازد.

    تابع register به صورت زیر است:

    (options?: object) => {...}

    • گزینه ها

      شی اختیاری

      • فوری

        بولی اختیاری

    • برمی گرداند

      Promise<ServiceWorkerRegistration>

  • به روز رسانی کنید

    باطل

    به‌روزرسانی‌های کارگر خدمات ثبت‌شده را بررسی می‌کند.

    عملکرد update به نظر می رسد:

    () => {...}

    • برمی گرداند

      قول<باطل>

WorkboxEventMap

WorkboxLifecycleEvent

خواص

  • خارجی است

    بولی اختیاری

  • isUpdate

    بولی اختیاری

  • رویداد اصلی

    رویداد اختیاری است

  • sw

    ServiceWorker اختیاری است

  • هدف

    WorkboxEventTarget اختیاری است

  • نوع

    typeOperator

WorkboxLifecycleEventMap

WorkboxLifecycleWaitingEvent

خواص

  • خارجی است

    بولی اختیاری

  • isUpdate

    بولی اختیاری

  • رویداد اصلی

    رویداد اختیاری است

  • sw

    ServiceWorker اختیاری است

  • هدف

    WorkboxEventTarget اختیاری است

  • نوع

    typeOperator

  • Waiting قبل از ثبت نام بود

    بولی اختیاری

WorkboxMessageEvent

خواص

  • داده ها

    هر

  • خارجی است

    بولی اختیاری

  • رویداد اصلی

    رویداد

  • پورت ها

    typeOperator

  • sw

    ServiceWorker اختیاری است

  • هدف

    WorkboxEventTarget اختیاری است

  • نوع

    "پیام"

روش ها

messageSW()

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

یک شی داده را از طریق postMessage به یک سرویس دهنده ارسال می کند و با یک پاسخ (در صورت وجود) حل می شود.

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

پارامترها

  • sw

    ServiceWorker

    کارگر خدمات برای ارسال پیام به.

  • داده ها

    شی

    یک شی برای ارسال به کارگر خدمات.

برمی گرداند

  • قول <هر>