chrome. Alarms

توضیحات

از chrome.alarms API برای برنامه‌ریزی کد برای اجرای دوره‌ای یا در زمان مشخصی در آینده استفاده کنید.

مجوزها

alarms

آشکار

برای استفاده از chrome.alarms API، مجوز "alarms" در مانیفست اعلام کنید:

{
  "name": "My extension",
  ...
  "permissions": [
    "alarms"
  ],
  ...
}

نمونه ها

مثال های زیر نحوه استفاده و پاسخ به زنگ هشدار را نشان می دهد. برای امتحان این API، مثال Alarm API را از مخزن chrome-extension-samples نصب کنید.

یک زنگ هشدار تنظیم کنید

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

service-worker.js:

chrome.runtime.onInstalled.addListener(async ({ reason }) => {
  if (reason !== 'install') {
    return;
  }

  // Create an alarm so we have something to look at in the demo
  await chrome.alarms.create('demo-default-alarm', {
    delayInMinutes: 1,
    periodInMinutes: 1
  });
});

توجه: از Chrome 117، تعداد هشدارهای فعال به 500 محدود است. پس از رسیدن به این محدودیت، chrome.alarms.create() ناموفق خواهد بود. هنگام استفاده از پاسخ به تماس، chrome.runtime.lastError تنظیم می شود. هنگام استفاده از قول، قول رد می شود.

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

مثال زیر نماد نوار ابزار عمل را بر اساس نام زنگ هشدار تنظیم می کند.

service-worker.js:

chrome.alarms.onAlarm.addListener((alarm) => {
  chrome.action.setIcon({
    path: getIconPath(alarm.name),
  });
});

انواع

Alarm

خواص

• نام

  رشته

  نام این زنگ هشدار

• دوره در دقیقه

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

  اگر تهی نباشد، زنگ هشدار یک زنگ تکراری است و در periodInMinutes دقیقه دوباره فعال می شود.

• زمان برنامه ریزی شده

  شماره

  زمانی که این زنگ هشدار برنامه ریزی شده بود، در میلی ثانیه گذشته از دوره (به عنوان مثال Date.now() + n ). به دلایل عملکرد، ممکن است هشدار مقدار دلخواه بیشتر از این به تاخیر افتاده باشد.

AlarmCreateInfo

خواص

• تاخیر در دقیقه

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

  مدت زمانی در دقیقه که پس از آن رویداد onAlarm باید فعال شود.

• دوره در دقیقه

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

  در صورت تنظیم، رویداد onAlarm باید هر periodInMinutes دقیقه بعد از رویداد اولیه مشخص شده توسط when یا delayInMinutes فعال شود. اگر تنظیم نشود، زنگ هشدار فقط یک بار فعال می شود.

• چه زمانی

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

  زمانی که در آن زنگ هشدار باید به صدا درآید، در میلی ثانیه گذشته از دوره (مثلاً Date.now() + n ).

روش ها

clear()

قول بده

chrome.alarms.clear(
  name?: string,
  callback?: function,
)

زنگ هشدار را با نام مشخص شده پاک می کند.

پارامترها

• نام

  رشته اختیاری

  نام زنگ هشدار برای پاک کردن. پیش‌فرض رشته خالی است.

• پاسخ به تماس

  عملکرد اختیاری

  پارامتر callback به نظر می رسد:

  (wasCleared: boolean) => void

  • پاک شد

    بولی

برمی گرداند

• وعده<boolean>

  Chrome 91+

  Promises فقط برای Manifest V3 و نسخه‌های جدیدتر پشتیبانی می‌شود، پلتفرم‌های دیگر باید از callback استفاده کنند.

clearAll()

قول بده

chrome.alarms.clearAll(
  callback?: function,
)

همه آلارم ها را پاک می کند.

پارامترها

• پاسخ به تماس

  عملکرد اختیاری

  پارامتر callback به نظر می رسد:

  (wasCleared: boolean) => void

  • پاک شد

    بولی

برمی گرداند

• وعده<boolean>

  Chrome 91+

  Promises فقط برای Manifest V3 و نسخه‌های جدیدتر پشتیبانی می‌شود، پلتفرم‌های دیگر باید از callback استفاده کنند.

create()

قول بده

chrome.alarms.create(
  name?: string,
  alarmInfo: AlarmCreateInfo,
  callback?: function,
)

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

برای کاهش بار روی دستگاه کاربر، Chrome آلارم‌ها را حداکثر در هر 30 ثانیه یک بار محدود می‌کند اما ممکن است مقدار دلخواه بیشتری را به تأخیر بیندازد. یعنی تنظیم delayInMinutes یا periodInMinutes روی کمتر از 0.5 رعایت نمی شود و باعث اخطار می شود. when می توان بدون هشدار روی کمتر از 30 ثانیه بعد از "اکنون" تنظیم کرد، اما در واقع باعث نمی شود که زنگ هشدار حداقل برای 30 ثانیه روشن شود.

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

پارامترها

• نام

  رشته اختیاری

  نام اختیاری برای شناسایی این زنگ. پیش‌فرض رشته خالی است.

• اطلاعات هشدار

  AlarmCreateInfo

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

• پاسخ به تماس

  عملکرد اختیاری

  Chrome 111+

  پارامتر callback به نظر می رسد:

  () => void

برمی گرداند

• قول<باطل>

  Chrome 111+

  Promises فقط برای Manifest V3 و نسخه‌های جدیدتر پشتیبانی می‌شود، پلتفرم‌های دیگر باید از callback استفاده کنند.

get()

قول بده

chrome.alarms.get(
  name?: string,
  callback?: function,
)

جزئیات مربوط به آلارم مشخص شده را بازیابی می کند.

پارامترها

• نام

  رشته اختیاری

  نام زنگ برای دریافت. پیش‌فرض رشته خالی است.

• پاسخ به تماس

  عملکرد اختیاری

  پارامتر callback به نظر می رسد:

  (alarm?: Alarm) => void

  • زنگ هشدار

    هشدار اختیاری

برمی گرداند

• وعده< زنگ هشدار | تعریف نشده>

  Chrome 91+

  Promises فقط برای Manifest V3 و نسخه‌های جدیدتر پشتیبانی می‌شود، پلتفرم‌های دیگر باید از callback استفاده کنند.

getAll()

قول بده

chrome.alarms.getAll(
  callback?: function,
)

آرایه ای از همه آلارم ها را دریافت می کند.

پارامترها

• پاسخ به تماس

  عملکرد اختیاری

  پارامتر callback به نظر می رسد:

  (alarms: Alarm[]) => void

  • آلارم ها

    زنگ هشدار []

برمی گرداند

• وعده< زنگ هشدار []>

  Chrome 91+

  Promises فقط برای Manifest V3 و نسخه‌های جدیدتر پشتیبانی می‌شود، پلتفرم‌های دیگر باید از callback استفاده کنند.

رویدادها

onAlarm

chrome.alarms.onAlarm.addListener(
  callback: function,
)

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

پارامترها

• پاسخ به تماس

  تابع

  پارامتر callback به نظر می رسد:

  (alarm: Alarm) => void

  • زنگ هشدار

    زنگ هشدار