chrome. Alarms

توضیحات

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

مجوزها

alarms

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

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

مفاهیم و کاربرد

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

خواب دستگاه

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

ماندگاری

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

const STORAGE_KEY = "user-preference-alarm-enabled";

async function checkAlarmState() {
  const { alarmEnabled } = await chrome.storage.get(STORAGE_KEY);

  if (alarmEnabled) {
    const alarm = await chrome.alarms.get("my-alarm");

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

checkAlarmState();

نمونه ها

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

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

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

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 و نسخه های جدیدتر پشتیبانی می شود، اما callbacks برای سازگاری به عقب ارائه شده است. شما نمی توانید از هر دو در یک فراخوانی تابع استفاده کنید. وعده با همان نوعی که به callback ارسال می شود حل می شود.

clearAll()

قول بده
chrome.alarms.clearAll(
  callback?: function,
)

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

پارامترها

  • پاسخ به تماس

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

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

    (wasCleared: boolean) => void

    • پاک شد

      بولی

برمی گرداند

  • وعده<boolean>

    Chrome 91+

    Promises در Manifest V3 و نسخه های جدیدتر پشتیبانی می شود، اما callbacks برای سازگاری به عقب ارائه شده است. شما نمی توانید از هر دو در یک فراخوانی تابع استفاده کنید. وعده با همان نوعی که به 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 و نسخه های جدیدتر پشتیبانی می شود، اما callbacks برای سازگاری به عقب ارائه شده است. شما نمی توانید از هر دو در یک فراخوانی تابع استفاده کنید. وعده با همان نوعی که به callback ارسال می شود حل می شود.

get()

قول بده
chrome.alarms.get(
  name?: string,
  callback?: function,
)

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

پارامترها

  • نام

    رشته اختیاری

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

  • پاسخ به تماس

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

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

    (alarm?: Alarm) => void

برمی گرداند

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

    Chrome 91+

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

getAll()

قول بده
chrome.alarms.getAll(
  callback?: function,
)

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

پارامترها

  • پاسخ به تماس

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

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

    (alarms: Alarm[]) => void

برمی گرداند

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

    Chrome 91+

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

رویدادها

onAlarm

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

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

پارامترها

  • پاسخ به تماس

    تابع

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

    (alarm: Alarm) => void