توضیحات
از 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دقیقه فعال میشود. - persistAcrossSessions
بولی
در حال بررسیاینکه آیا زنگ هشدار باید در طول جلسات (با شروع مجدد مرورگر) ادامه یابد یا خیر.
- زمان برنامهریزیشده
شماره
زمانی که قرار بود این آلارم در آن فعال شود، بر حسب میلیثانیه پس از دوره (مثال:
Date.now() + n). به دلایل عملکردی، ممکن است آلارم به میزان دلخواهی بیش از این به تأخیر افتاده باشد.
AlarmCreateInfo
خواص
- تأخیر در دقیقه
شماره اختیاری
مدت زمانی بر حسب دقیقه که پس از آن رویداد
onAlarmباید اجرا شود. - دوره در دقیقه
شماره اختیاری
اگر تنظیم شود، رویداد onAlarm باید هر
periodInMinutesدقیقه پس از رویداد اولیه مشخص شده توسطwhenیاdelayInMinutesاجرا شود. اگر تنظیم نشود، هشدار فقط یک بار اجرا میشود. - persistAcrossSessions
بولی اختیاری
در حال بررسیاینکه آیا هشدار باید در طول جلسات (ریاستارت شدن مرورگر) ادامه یابد یا خیر. در کروم، این مقدار به صورت پیشفرض روی true تنظیم شده تا با رفتار تاریخی مطابقت داشته باشد، اما شما باید این مقدار را به طور صریح تنظیم کنید تا سازگاری بین مرورگرها به حداکثر برسد.
- چه زمانی
شماره اختیاری
زمانی که آلارم باید فعال شود، بر حسب میلیثانیه پس از دوره (مثال:
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>
جزئیات مربوط به هشدار مشخص شده را بازیابی میکند.
پارامترها
- نام
رشته اختیاری
نام آلارمی که قرار است دریافت شود. مقدار پیشفرض آن رشتهی خالی است.
بازگشتها
قول< هشدار | نامشخص>
کروم ۹۱+
بازگشتها
قول< هشدار []>
کروم ۹۱+