chrome. Alarms

توضیحات

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

مجوزها

alarms

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

{
  "name": "My extension",
  ...
  "permissions": [
    "alarms"
  ],
  ...
}
مفاهیم و کاربردها

برای اطمینان از رفتار قابل اعتماد، درک نحوه رفتار API مفید است.

خواب دستگاه

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

پشتکار

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

async function checkAlarmState() {
  const alarm = await chrome.alarms.get("my-alarm");

  if (!alarm) {
    await chrome.alarms.create("my-alarm", { periodInMinutes: 1 });
  }
}

checkAlarmState();
مثال‌ها

مثال‌های زیر نحوه استفاده و پاسخ به یک هشدار را نشان می‌دهند. برای امتحان کردن این 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
  });
});
پاسخ به زنگ هشدار

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

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

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

پارامترها
  • نام

    رشته اختیاری

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

بازگشت‌ها

  • قول <boolean>

    کروم ۹۱+
clearAll() 
chrome.alarms.clearAll(): Promise<boolean>

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

بازگشت‌ها

  • قول <boolean>

    کروم ۹۱+
create() 
chrome.alarms.create(
  name?: string,
  alarmInfo: AlarmCreateInfo,
): Promise<void>

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

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

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

پارامترها
  • نام

    رشته اختیاری

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

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

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

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

بازگشت‌ها

  • قول<void>

    کروم ۱۱۱+

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

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

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

پارامترها
  • نام

    رشته اختیاری

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

بازگشت‌ها

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

    کروم ۹۱+
getAll() 
chrome.alarms.getAll(): Promise<Alarm[]>

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

بازگشت‌ها
رویدادها
onAlarm 
chrome.alarms.onAlarm.addListener(
  callback: function,
)

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

پارامترها
  • تماس برگشتی

    تابع

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

    (alarm: Alarm) => void