رویدادهای کارگران خدماتی

سرویس‌دهنده‌های افزونه از رویدادهای استاندارد سرویس‌دهنده و بسیاری از رویدادهای موجود در APIهای افزونه پشتیبانی می‌کنند. این بخش موارد موجود را شرح می‌دهد و نکاتی برای استفاده از آنها ارائه می‌دهد.

رویدادهای افزونه را اعلام کنید

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

browser.storage.local.get(["badgeText"], ({ badgeText }) => {
  browser.action.setBadgeText({ text: badgeText });
  browser.action.onClicked.addListener(handleActionClick);
});

browser.action.onClicked.addListener(handleActionClick);

browser.storage.local.get(["badgeText"], ({ badgeText }) => {
  browser.action.setBadgeText({ text: badgeText });
});

رویدادهای رایج

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

browser.action

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

browser.management

رویدادهای مربوط به نصب، حذف نصب، فعال و غیرفعال کردن افزونه‌ها را ارائه می‌دهد.

browser.notifications

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

browser.permissions

نشان می‌دهد که چه زمانی مجوزهای افزونه توسط کاربر اعطا یا لغو می‌شود.

browser.runtime

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

browser.storage.onChanged

هر زمان که هر شیء StorageArea پاک شود یا مقدار یک کلید تغییر یابد یا تنظیم شود، اجرا می‌شود. توجه داشته باشید که هر نمونه StorageArea رویداد onChanged مخصوص به خود را دارد.

browser.webNavigation

اطلاعاتی در مورد وضعیت درخواست‌های ناوبری در حین پرواز ارائه می‌دهد.

فیلترها

برای محدود کردن رویدادها به موارد استفاده خاص یا حذف فراخوانی‌های غیرضروری رویدادها، از APIهایی استفاده کنید که از فیلترهای رویداد پشتیبانی می‌کنند. برای مثال، افزونه‌ای را در نظر بگیرید که به رویداد tabs.onUpdated گوش می‌دهد تا تشخیص دهد چه زمانی کاربر به یک وب‌سایت خاص هدایت می‌شود. این رویداد در هر ناوبری در هر تب فراخوانی می‌شود. در عوض، webNavigation.onCompleted به همراه یک فیلتر استفاده کنید. برای مثال:

const filter = {
  url: [
    {
      urlMatches: 'https://www.google.com/',
    },
  ],
};

browser.webNavigation.onCompleted.addListener(() => {
  console.info("The user has loaded my favorite website!");
}, filter);

رویدادهای کارگر سرویس وب

کارکنان خدمات ترویجی از رویدادهای چرخه حیات که در جای دیگر توضیح داده شده است، پشتیبانی بیشتری می‌کنند.

ServiceWorkerGlobal.fetch

زمانی که چیزی از بسته افزونه بازیابی می‌شود یا زمانی که fetch() و XMLHttpRequest() از یک افزونه یا اسکریپت پاپ‌آپ فراخوانی می‌شوند، اجرا می‌شود. (فراخوانی‌های اسکریپت‌های محتوا توسط سرویس ورکر fetch handler رهگیری نمی‌شوند.) در موارد اخیر، باید URLهای صفحاتی را که می‌خواهید واکشی کنید به کلید "host_permissions" در manifest.json اضافه کنید.

پیام ServiceWorkerGlobal

ارسال پیام توسط سرویس ورکر علاوه بر ارسال پیام توسط افزونه در دسترس است، اما این دو سیستم با هم سازگار نیستند. این بدان معناست که پیام‌های ارسالی با استفاده از sendMessage() (که از چندین API افزونه در دسترس است) توسط کنترل‌کننده‌های پیام سرویس ورکر رهگیری نمی‌شوند. به همین ترتیب، پیام‌های ارسالی با استفاده از postMessage() توسط کنترل‌کننده‌های پیام افزونه رهگیری نمی‌شوند. هر دو نوع کنترل‌کننده پیام - یعنی ServiceWorkerGlobal.message و browser.runtime.onMessage - در سرویس ورکرهای افزونه پشتیبانی می‌شوند.

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

سرویس‌دهنده‌های افزونه از رویدادهای استاندارد سرویس‌دهنده و بسیاری از رویدادهای موجود در APIهای افزونه پشتیبانی می‌کنند. این بخش موارد موجود را شرح می‌دهد و نکاتی برای استفاده از آنها ارائه می‌دهد.

رویدادهای افزونه را اعلام کنید

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

browser.storage.local.get(["badgeText"], ({ badgeText }) => {
  browser.action.setBadgeText({ text: badgeText });
  browser.action.onClicked.addListener(handleActionClick);
});

browser.action.onClicked.addListener(handleActionClick);

browser.storage.local.get(["badgeText"], ({ badgeText }) => {
  browser.action.setBadgeText({ text: badgeText });
});

رویدادهای رایج

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

browser.action

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

browser.management

رویدادهای مربوط به نصب، حذف نصب، فعال و غیرفعال کردن افزونه‌ها را ارائه می‌دهد.

browser.notifications

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

browser.permissions

نشان می‌دهد که چه زمانی مجوزهای افزونه توسط کاربر اعطا یا لغو می‌شود.

browser.runtime

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

browser.storage.onChanged

هر زمان که هر شیء StorageArea پاک شود یا مقدار یک کلید تغییر یابد یا تنظیم شود، اجرا می‌شود. توجه داشته باشید که هر نمونه StorageArea رویداد onChanged مخصوص به خود را دارد.

browser.webNavigation

اطلاعاتی در مورد وضعیت درخواست‌های ناوبری در حین پرواز ارائه می‌دهد.

فیلترها

برای محدود کردن رویدادها به موارد استفاده خاص یا حذف فراخوانی‌های غیرضروری رویدادها، از APIهایی استفاده کنید که از فیلترهای رویداد پشتیبانی می‌کنند. برای مثال، افزونه‌ای را در نظر بگیرید که به رویداد tabs.onUpdated گوش می‌دهد تا تشخیص دهد چه زمانی کاربر به یک وب‌سایت خاص هدایت می‌شود. این رویداد در هر ناوبری در هر تب فراخوانی می‌شود. در عوض، webNavigation.onCompleted به همراه یک فیلتر استفاده کنید. برای مثال:

const filter = {
  url: [
    {
      urlMatches: 'https://www.google.com/',
    },
  ],
};

browser.webNavigation.onCompleted.addListener(() => {
  console.info("The user has loaded my favorite website!");
}, filter);

رویدادهای کارگر سرویس وب

کارکنان خدمات ترویجی از رویدادهای چرخه حیات که در جای دیگر توضیح داده شده است، پشتیبانی بیشتری می‌کنند.

ServiceWorkerGlobal.fetch

زمانی که چیزی از بسته افزونه بازیابی می‌شود یا زمانی که fetch() و XMLHttpRequest() از یک افزونه یا اسکریپت پاپ‌آپ فراخوانی می‌شوند، اجرا می‌شود. (فراخوانی‌های اسکریپت‌های محتوا توسط سرویس ورکر fetch handler رهگیری نمی‌شوند.) در موارد اخیر، باید URLهای صفحاتی را که می‌خواهید واکشی کنید به کلید "host_permissions" در manifest.json اضافه کنید.

پیام ServiceWorkerGlobal

ارسال پیام توسط سرویس ورکر علاوه بر ارسال پیام توسط افزونه در دسترس است، اما این دو سیستم با هم سازگار نیستند. این بدان معناست که پیام‌های ارسالی با استفاده از sendMessage() (که از چندین API افزونه در دسترس است) توسط کنترل‌کننده‌های پیام سرویس ورکر رهگیری نمی‌شوند. به همین ترتیب، پیام‌های ارسالی با استفاده از postMessage() توسط کنترل‌کننده‌های پیام افزونه رهگیری نمی‌شوند. هر دو نوع کنترل‌کننده پیام - یعنی ServiceWorkerGlobal.message و browser.runtime.onMessage - در سرویس ورکرهای افزونه پشتیبانی می‌شوند.

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

سرویس‌دهنده‌های افزونه از رویدادهای استاندارد سرویس‌دهنده و بسیاری از رویدادهای موجود در APIهای افزونه پشتیبانی می‌کنند. این بخش موارد موجود را شرح می‌دهد و نکاتی برای استفاده از آنها ارائه می‌دهد.

رویدادهای افزونه را اعلام کنید

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

browser.storage.local.get(["badgeText"], ({ badgeText }) => {
  browser.action.setBadgeText({ text: badgeText });
  browser.action.onClicked.addListener(handleActionClick);
});

browser.action.onClicked.addListener(handleActionClick);

browser.storage.local.get(["badgeText"], ({ badgeText }) => {
  browser.action.setBadgeText({ text: badgeText });
});

رویدادهای رایج

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

browser.action

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

browser.management

رویدادهای مربوط به نصب، حذف نصب، فعال و غیرفعال کردن افزونه‌ها را ارائه می‌دهد.

browser.notifications

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

browser.permissions

نشان می‌دهد که چه زمانی مجوزهای افزونه توسط کاربر اعطا یا لغو می‌شود.

browser.runtime

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

browser.storage.onChanged

هر زمان که هر شیء StorageArea پاک شود یا مقدار یک کلید تغییر یابد یا تنظیم شود، اجرا می‌شود. توجه داشته باشید که هر نمونه StorageArea رویداد onChanged مخصوص به خود را دارد.

browser.webNavigation

اطلاعاتی در مورد وضعیت درخواست‌های ناوبری در حین پرواز ارائه می‌دهد.

فیلترها

برای محدود کردن رویدادها به موارد استفاده خاص یا حذف فراخوانی‌های غیرضروری رویدادها، از APIهایی استفاده کنید که از فیلترهای رویداد پشتیبانی می‌کنند. برای مثال، افزونه‌ای را در نظر بگیرید که به رویداد tabs.onUpdated گوش می‌دهد تا تشخیص دهد چه زمانی کاربر به یک وب‌سایت خاص هدایت می‌شود. این رویداد در هر ناوبری در هر تب فراخوانی می‌شود. در عوض، webNavigation.onCompleted به همراه یک فیلتر استفاده کنید. برای مثال:

const filter = {
  url: [
    {
      urlMatches: 'https://www.google.com/',
    },
  ],
};

browser.webNavigation.onCompleted.addListener(() => {
  console.info("The user has loaded my favorite website!");
}, filter);

رویدادهای کارگر سرویس وب

کارکنان خدمات ترویجی از رویدادهای چرخه حیات که در جای دیگر توضیح داده شده است، پشتیبانی بیشتری می‌کنند.

ServiceWorkerGlobal.fetch

زمانی که چیزی از بسته افزونه بازیابی می‌شود یا زمانی که fetch() و XMLHttpRequest() از یک افزونه یا اسکریپت پاپ‌آپ فراخوانی می‌شوند، اجرا می‌شود. (فراخوانی‌های اسکریپت‌های محتوا توسط سرویس ورکر fetch handler رهگیری نمی‌شوند.) در موارد اخیر، باید URLهای صفحاتی را که می‌خواهید واکشی کنید به کلید "host_permissions" در manifest.json اضافه کنید.

پیام ServiceWorkerGlobal

ارسال پیام توسط سرویس ورکر علاوه بر ارسال پیام توسط افزونه در دسترس است، اما این دو سیستم با هم سازگار نیستند. این بدان معناست که پیام‌های ارسالی با استفاده از sendMessage() (که از چندین API افزونه در دسترس است) توسط کنترل‌کننده‌های پیام سرویس ورکر رهگیری نمی‌شوند. به همین ترتیب، پیام‌های ارسالی با استفاده از postMessage() توسط کنترل‌کننده‌های پیام افزونه رهگیری نمی‌شوند. هر دو نوع کنترل‌کننده پیام - یعنی ServiceWorkerGlobal.message و browser.runtime.onMessage - در سرویس ورکرهای افزونه پشتیبانی می‌شوند.

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