chrome. Alarms

توضیحات

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

مجوزها

alarms

مانیفست

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

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

مثال‌ها

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

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

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

سرویس-ورکر.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.alarms.create() با شکست مواجه می‌شود. هنگام استفاده از callback، chrome.runtime.lastError تنظیم می‌شود. هنگام استفاده از promiseها، promise رد می‌شود.

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

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

سرویس-ورکر.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,
): Promise<boolean>

آلارم مربوط به نام داده شده را پاک می‌کند.

پارامترها

• نام

  رشته اختیاری

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

• تماس برگشتی

  تابع اختیاری

  پارامتر callback به شکل زیر است:

  (wasCleared: boolean) => void

  • پاک شد

    بولی

بازگشت‌ها

• قول <boolean>

  کروم ۹۱+

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

clearAll()

وعده

chrome.alarms.clearAll(
  callback?: function,
): Promise<boolean>

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

پارامترها

• تماس برگشتی

  تابع اختیاری

  پارامتر callback به شکل زیر است:

  (wasCleared: boolean) => void

  • پاک شد

    بولی

بازگشت‌ها

• قول <boolean>

  کروم ۹۱+

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

create()

وعده

chrome.alarms.create(
  name?: string,
  alarmInfo: AlarmCreateInfo,
  callback?: function,
): Promise<void>

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

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

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

پارامترها

• نام

  رشته اختیاری

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

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

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

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

• تماس برگشتی

  تابع اختیاری

  کروم ۱۱۱+

  پارامتر callback به شکل زیر است:

  () => void

بازگشت‌ها

• قول<void>

  کروم ۱۱۱+

  قولی که پس از ایجاد هشدار، برطرف می‌شود.

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

get()

وعده

chrome.alarms.get(
  name?: string,
  callback?: function,
): Promise<Alarm | undefined>

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

پارامترها

• نام

  رشته اختیاری

  نام آلارمی که قرار است دریافت شود. مقدار پیش‌فرض آن رشته‌ی خالی است.

• تماس برگشتی

  تابع اختیاری

  پارامتر callback به شکل زیر است:

  (alarm?: Alarm) => void

  • زنگ هشدار

    زنگ هشدار اختیاری

بازگشت‌ها

• قول< هشدار | نامشخص>

  کروم ۹۱+

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

getAll()

وعده

chrome.alarms.getAll(
  callback?: function,
): Promise<Alarm[]>

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

پارامترها

• تماس برگشتی

  تابع اختیاری

  پارامتر callback به شکل زیر است:

  (alarms: Alarm[]) => void

  • آلارم ها

    زنگ هشدار []

بازگشت‌ها

• قول< هشدار []>

  کروم ۹۱+

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

رویدادها

onAlarm

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

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

پارامترها

• تماس برگشتی

  تابع

  پارامتر callback به شکل زیر است:

  (alarm: Alarm) => void

  • زنگ هشدار

    زنگ هشدار