browser.alarms

شرح

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

اجازه‌ها

alarms

برای استفاده از «میانای برنامه‌سازی کاربردی» browser.alarms، اجازه "alarms" را در مانیفست اعلام کنید:

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

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

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

خواب دستگاه

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

پایداری

می‌توانید پایداری زنگ هشدار را در زمان ایجاد بااستفاده از پرچم persistAcrossSessions کنترل کنید. این مقدار می‌تواند روی true (تا زمانی که افزونه به‌روز شود باقی می‌ماند) یا false (اگر افزونه مجدداً بار شود یا مرورگر بازراه‌اندازی شود، و هر زمان که افزونه به‌روز شود پاک می‌شود) تنظیم شود.

مرورگرهای دیگر و نسخه‌های قدیمی‌تر Chrome

این ویژگی در مرورگرهای دیگر (مشکل) یا در نسخه‌های Chrome قبل‌از Chrome 150 پشتیبانی نمی‌شود، که در آن‌ها رفتار می‌تواند غیرقابل‌پیش‌بینی باشد. بنابراین، بهتر است مطمئن شوید که هربار که کارگر سرویس شما راه‌اندازی می‌شود، هشدارهای مهم وجود دارند. برای مثال:

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

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

checkAlarmState();

اگر زنگ ساعت شما به‌طور پویا براساس کنش کاربر ایجاد شده است، شاید بخواهید ذخیره کنید که زنگ ساعت در جای دیگری ایجاد شده است تا بدانید درصورت نیاز آن را دوباره ایجاد کنید.

مثال‌ها

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

تنظیم زنگ ساعت

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

service-worker.js:

browser.runtime.onInstalled.addListener(async ({ reason }) => {
  // Create an alarm so we have something to look at in the demo
  await browser.alarms.create('demo-default-alarm', {
    delayInMinutes: 1,
    periodInMinutes: 1,
    persistAcrossSessions: true
  });
});

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

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

service-worker.js:

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

انواع

Alarm

مشخصات

  • نام

    رشته

    نام این زنگ ساعت.

  • periodInMinutes

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

    اگر پوچ نباشد، زنگ ساعت تکرارشونده است و periodInMinutes دقیقه دیگر دوباره به‌صدا درمی‌آید.

  • persistAcrossSessions

    بولی

    Chrome نسخه ۱۵۰ و بالاتر

    آیا زنگ هشدار باید در جلسات (بازراه‌اندازی مرورگر) باقی بماند یا نه.

  • scheduledTime

    شماره

    زمانی که این زنگ ساعت برای به‌صدا درآمدن زمان‌بندی شده است، برحسب میلی‌ثانیه پس‌از مبدأ (مثلاً Date.now() + n). به‌دلایل عملکردی، ممکن است زنگ ساعت به‌مدت دلخواهی پس‌از این زمان به‌تأخیر افتاده باشد.

AlarmCreateInfo

مشخصات

  • delayInMinutes

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

    مدت زمان برحسب دقیقه که پس‌از آن رویداد onAlarm باید اجرا شود.

  • نام

    رشته اختیاری

    Chrome نسخه ۱۵۲ و بالاتر

    نام این زنگ ساعت.

  • periodInMinutes

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

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

  • persistAcrossSessions

    بولی اختیاری

    Chrome نسخه ۱۵۰ و بالاتر

    آیا زنگ هشدار باید در جلسات (بازراه‌اندازی مرورگر) باقی بماند یا نه. در Chrome، این مقدار به‌طور پیش‌فرض روی true تنظیم شده است تا با رفتار گذشته مطابقت داشته باشد، اما باید آن را به‌طور صریح تنظیم کنید تا سازگاری بین مرورگرها به حداکثر برسد.

  • چه زمانی

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

    زمانی که زنگ ساعت باید به‌صدا درآید، برحسب میلی‌ثانیه پس‌از مبدأ تاریخ (مثلاً Date.now() + n).

روش‌ها

clear()

browser.alarms.clear(
  name?: string,
): Promise<boolean>

زنگ ساعت با نام ارائه‌شده را پاک می‌کند.

پارامترها

  • نام

    رشته اختیاری

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

بازگشتی‌ها

  • Promise<boolean>

    Chrome نسخه ۹۱ و بالاتر browser.* از Chrome نسخه ۱۴۸

clearAll()

browser.alarms.clearAll(): Promise<boolean | undefined>

همه زنگ‌های ساعت را پاک می‌کند.

بازگشتی‌ها

  • Promise<boolean | undefined>

    Chrome نسخه ۹۱ و بالاتر browser.* از Chrome نسخه ۱۴۸

create()

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

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

برای کاهش بار روی دستگاه کاربر، Chrome هشدارها را به حداکثر یک بار در ثانیه محدود می‌کند اما ممکن است آن‌ها را به‌اندازه دلخواه بیشتر به‌تأخیر بیندازد. یعنی تنظیم delayInMinutes یا periodInMinutes روی کمتر از ۱ ثانیه پذیرفته نخواهد شد و باعث ایجاد هشدار می‌شود. when را می‌توان بدون هشدار روی کمتر از ۱ ثانیه بعداز «اکنون» تنظیم کرد، اما درواقع باعث نمی‌شود زنگ ساعت حداقل تا ۱ ثانیه به‌صدا درآید.

پارامترها

  • نام

    رشته اختیاری

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

  • alarmInfo

    AlarmCreateInfo

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

بازگشتی‌ها

  • Promise<void>

    Chrome 111+ browser.* از Chrome 148

    Promise که وقتی زنگ هشدار ایجاد شد حل‌وفصل می‌شود.

get()

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

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

پارامترها

  • نام

    رشته اختیاری

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

بازگشتی‌ها

  • Promise<Alarm | undefined>

    Chrome نسخه ۹۱ و بالاتر browser.* از Chrome نسخه ۱۴۸

getAll()

browser.alarms.getAll(): Promise<Alarm[]>

آرایه‌ای از همه زنگ‌های ساعت را دریافت می‌کند.

بازگشتی‌ها

  • Promise<Alarm[]>

    Chrome نسخه ۹۱ و بالاتر browser.* از Chrome نسخه ۱۴۸

رویدادها

onAlarm

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

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

پارامترها

  • تماس برگشتی

    عملکرد

    پارامتر callback به‌صورت زیر است: 

    (alarm: Alarm) => void