refresh date: 2026-09-25 robots: noindex
شرح
از میانای برنامه‌سازی کاربردی chrome.alarms برای زمان‌بندی کد برای اجرا به‌صورت دوره‌ای یا در زمان مشخصی در آینده استفاده کنید.
اجازه‌ها
alarmsمانیفست
برای استفاده از «میانای برنامه‌سازی کاربردی» chrome.alarms، اجازه "alarms" را در مانیفست اعلام کنید:
{
"name": "My extension",
...
"permissions": [
"alarms"
],
...
}
مثال‌ها
مثال‌های زیر نحوه استفاده و پاسخ دادن به زنگ ساعت را نشان می‌دهد. برای امتحان کردن این میانای برنامه‌سازی کاربردی، نمونه 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
شماره اختیاری
اگر پوچ نباشد، زنگ ساعت تکرارشونده است و
periodInMinutesدقیقه دیگر دوباره به‌صدا درمی‌آید. -
persistAcrossSessions
بولی
Chrome نسخه ۱۵۰ به بالاآیا زنگ هشدار باید در جلسات (بازراه‌اندازی مرورگر) باقی بماند یا نه.
-
scheduledTime
شماره
زمانی که این زنگ ساعت برای به‌صدا درآمدن زمان‌بندی شده است، برحسب میلی‌ثانیه پس‌از مبدأ (مثلاً
Date.now() + n). به‌دلایل عملکردی، ممکن است زنگ ساعت به‌مدت دلخواهی پس‌از این زمان به‌تأخیر افتاده باشد.
AlarmCreateInfo
مشخصات
-
delayInMinutes
شماره اختیاری
مدت زمان برحسب دقیقه که پس‌از آن رویداد
onAlarmباید اجرا شود. -
نام
رشته اختیاری
Chrome نسخه ۱۵۲ و بالاترنام این زنگ ساعت.
-
periodInMinutes
شماره اختیاری
درصورت تنظیم، رویداد onAlarm باید هر
periodInMinutesدقیقه پس‌از رویداد اولیه مشخص‌شده توسطwhenیاdelayInMinutesاجرا شود. اگر تنظیم نشده باشد، زنگ ساعت فقط یک‌بار به‌صدا درمی‌آید. -
persistAcrossSessions
بولی اختیاری
Chrome نسخه ۱۵۰ و بالاترآیا زنگ هشدار باید در جلسات (بازراه‌اندازی مرورگر) باقی بماند یا نه. در Chrome، این مقدار به‌طور پیش‌فرض روی true تنظیم شده است تا با رفتار گذشته مطابقت داشته باشد، اما باید آن را به‌طور صریح تنظیم کنید تا سازگاری بین مرورگرها به حداکثر برسد.
-
چه زمانی
شماره اختیاری
زمانی که زنگ ساعت باید به‌صدا درآید، برحسب میلی‌ثانیه پس‌از مبدأ تاریخ (مثلاً
Date.now() + n).
روش‌ها
clear()
chrome.alarms.clear(
name?: string,
callback?: function,
): Promise<boolean>
زنگ ساعت با نام ارائه‌شده را پاک می‌کند.
پارامترها
-
نام
رشته اختیاری
نام زنگ ساعتی که باید پاک شود. به‌طور پیش‌فرض روی رشته خالی تنظیم می‌شود.
-
تماس برگشتی
تابع اختیاری
پارامتر
callbackبه‌صورت زیر است:(wasCleared: boolean) => void
-
wasCleared
بولی
-
بازگشتی‌ها
-
Promise<boolean>
Chrome نسخه ۹۱ به بالاPromises فقط برای «مانیفست نسخه ۳» و نسخه‌های جدیدتر پشتیبانی می‌شود، پلاتفرم‌های دیگر باید از callbacks استفاده کنند.
clearAll()
chrome.alarms.clearAll(
callback?: function,
): Promise<boolean | undefined>
همه زنگ‌های ساعت را پاک می‌کند.
پارامترها
-
تماس برگشتی
تابع اختیاری
پارامتر
callbackبه‌صورت زیر است:(wasCleared?: boolean) => void
-
wasCleared
بولی اختیاری
-
بازگشتی‌ها
-
Promise<boolean | undefined>
Chrome نسخه ۹۱ به بالاPromises فقط برای «مانیفست نسخه ۳» و نسخه‌های جدیدتر پشتیبانی می‌شود، پلاتفرم‌های دیگر باید از callbacks استفاده کنند.
create()
chrome.alarms.create(
name?: string,
alarmInfo: AlarmCreateInfo,
callback?: function,
): Promise<void>
زنگ ساعتی ایجاد می‌کند. نزدیک زمان(های) مشخص‌شده توسط alarmInfo، رویداد onAlarm اجرا می‌شود. اگر زنگ ساعت دیگری با همین نام (یا بدون نام، اگر نامی مشخص نشده باشد) وجود داشته باشد، لغو می‌شود و این زنگ ساعت جایگزین آن می‌شود.
برای کاهش بار روی دستگاه کاربر، Chrome هشدارها را به حداکثر یک بار در ثانیه محدود می‌کند اما ممکن است آن‌ها را به‌اندازه دلخواه بیشتر به‌تأخیر بیندازد. یعنی تنظیم delayInMinutes یا periodInMinutes روی کمتر از ۱ ثانیه پذیرفته نخواهد شد و باعث ایجاد هشدار می‌شود. when را می‌توان بدون هشدار روی کمتر از ۱ ثانیه بعداز «اکنون» تنظیم کرد، اما درواقع باعث نمی‌شود زنگ ساعت حداقل تا ۱ ثانیه به‌صدا درآید.
پارامترها
-
نام
رشته اختیاری
نام اختیاری برای شناسایی این زنگ هشدار. به‌طور پیش‌فرض روی رشته خالی تنظیم می‌شود.
-
alarmInfo
توضیح می‌دهد زنگ ساعت چه زمانی باید به‌صدا درآید. زمان اولیه باید با
whenیاdelayInMinutes(اما نه هر دو) مشخص شود. اگرperiodInMinutesتنظیم شده باشد، زنگ ساعت هرperiodInMinutesدقیقه پس‌از رویداد اولیه تکرار خواهد شد. اگر هیچ‌کدام ازwhenیاdelayInMinutesبرای زنگ ساعت تکرارشونده تنظیم نشده باشد،periodInMinutesبه‌عنوان پیش‌فرض برایdelayInMinutesاستفاده می‌شود. -
تماس برگشتی
تابع اختیاری
Chrome نسخه ۱۱۱ به بالاپارامتر
callbackبه‌صورت زیر است:() => void
بازگشتی‌ها
-
Promise<void>
Chrome نسخه ۱۱۱ به بالاPromise که وقتی زنگ هشدار ایجاد شد حل‌وفصل می‌شود.
Promises فقط برای «مانیفست نسخه ۳» و نسخه‌های جدیدتر پشتیبانی می‌شود، پلاتفرم‌های دیگر باید از callbacks استفاده کنند.
get()
chrome.alarms.get(
name?: string,
callback?: function,
): Promise<Alarm | undefined>
جزئیات مربوط به زنگ مشخص‌شده را بازیابی می‌کند.
پارامترها
بازگشتی‌ها
-
Promise<Alarm | undefined>
Chrome نسخه ۹۱ به بالاPromises فقط برای «مانیفست نسخه ۳» و نسخه‌های جدیدتر پشتیبانی می‌شود، پلاتفرم‌های دیگر باید از callbacks استفاده کنند.
getAll()
chrome.alarms.getAll(
callback?: function,
): Promise<Alarm[]>
آرایه‌ای از همه زنگ‌های ساعت را دریافت می‌کند.
پارامترها
بازگشتی‌ها
-
Promise<Alarm[]>
Chrome نسخه ۹۱ به بالاPromises فقط برای «مانیفست نسخه ۳» و نسخه‌های جدیدتر پشتیبانی می‌شود، پلاتفرم‌های دیگر باید از callbacks استفاده کنند.