תיאור
אפשר להשתמש ב-API של chrome.alarms כדי לתזמן קוד כך שירוץ מדי פעם או בתאריך מוגדר בעתיד.
הרשאות
alarmsכדי להשתמש ב-API chrome.alarms, צריך להצהיר על ההרשאה "alarms" במניפסט:
{
"name": "My extension",
...
"permissions": [
"alarms"
],
...
}
מושגים ושימוש
כדי להבטיח התנהגות אמינה, כדאי להבין איך ה-API פועל.
מצב שינה במכשיר
ההתראות ממשיכות לפעול כשהמכשיר במצב שינה. עם זאת, לא תוצג התראה להוציא את המכשיר ממצב שינה. כשהמכשיר יתעורר, ההתראות שפספסת יופעלו. התראות חוזרות יופעלו פעם אחת לכל היותר ואז תתוזמן מחדש באמצעות פרק זמן ספציפי החל מהתאריך שבו המכשיר מתעורר, ללא התייחסות כל זמן שכבר חלף מאז שההתראה הוגדרה במקור להפעלה.
התמדה
התראות נמשכות בדרך כלל עד לעדכון תוסף. עם זאת, אין התחייבות לכך, והתראות יכולה להימחק על ידי הפעלה מחדש של הדפדפן. לכן כדאי להגדיר ערך לאחסון לאחר יצירת התראה, ולאחר מכן לוודא שהיא קיימת בכל פעם שה-Service Worker מופעל. לדוגמה:
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 הזה להתקין את הדוגמה של Alert API מchrome-extension-samples. של מאגר הנתונים.
הגדרת התראה
הדוגמה הבאה מגדירה התראה ב-Service Worker כשהתוסף מותקן:
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
מספר אופציונלי
אם הערך הוא לא null, זוהי התראה חוזרת ותופעל שוב בעוד
periodInMinutesדקות. -
scheduledTime
number
השעה שבה ההתראה הזו תוזמנה לפעול, באלפיות השנייה אחרי תחילת התקופה (למשל,
Date.now() + n). מסיבות שקשורות לביצועים, יכול להיות שהתראה תידחה בכמות שרירותית מעבר למגבלה הזו.
AlarmCreateInfo
מאפיינים
-
delayInMinutes
מספר אופציונלי
משך הזמן בדקות שאחריו האירוע
onAlarmאמור לפעול. -
periodInMinutes
מספר אופציונלי
אם מוגדר, האירוע on alarm אמור לפעול כל
periodInMinutesדקות אחרי האירוע הראשוני שצוין על ידיwhenאוdelayInMinutes. אם המדיניות לא מוגדרת, ההתראה תופעל רק פעם אחת. -
מתי
מספר אופציונלי
השעה שבה ההתראה צריכה לפעול, באלפיות שנייה אחרי הזמן שחלף (למשל,
Date.now() + n).
שיטות
clear()
chrome.alarms.clear(
name?: string,
callback?: function,
)
ניקוי ההתראה עם השם הנתון.
פרמטרים
-
שם
מחרוזת אופציונלי
שם ההתראה שיש למחוק. ברירת המחדל היא המחרוזת הריקה.
-
קריאה חוזרת (callback)
פונקציה אופציונלית
הפרמטר
callbackנראה כך:(wasCleared: boolean) => void
-
wasCleared
בוליאני
-
החזרות
-
Promise<boolean>
Chrome מגרסה 91 ואילךהבטחות נתמכות במניפסט מגרסה V3 ואילך, אבל ניתנות קריאות חוזרות (callback) בשביל תאימות לאחור. לא ניתן להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה הזו מצליחה לפתור את הבעיה באותו סוג שמועבר לקריאה החוזרת.
clearAll()
chrome.alarms.clearAll(
callback?: function,
)
ניקוי כל ההתראות
פרמטרים
-
קריאה חוזרת (callback)
פונקציה אופציונלית
הפרמטר
callbackנראה כך:(wasCleared: boolean) => void
-
wasCleared
בוליאני
-
החזרות
-
Promise<boolean>
Chrome מגרסה 91 ואילךהבטחות נתמכות במניפסט מגרסה V3 ואילך, אבל ניתנות קריאות חוזרות (callback) בשביל תאימות לאחור. לא ניתן להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה הזו מצליחה לפתור את הבעיה באותו סוג שמועבר לקריאה החוזרת.
create()
chrome.alarms.create(
name?: string,
alarmInfo: AlarmCreateInfo,
callback?: function,
)
יצירת התראה. ליד השעות שצוינו על ידי alarmInfo, האירוע onAlarm מופעל. אם יש התראה נוספת באותו שם (או ללא שם אם לא צוין שם), היא תבוטל ותוחלף על ידי ההתראה הזו.
כדי להפחית את העומס על המחשב של המשתמש, Chrome מגביל את ההתראות פעם אחת לכל 30 שניות לכל היותר, אך עשוי לעכב אותן בכמות שרירותית יותר. כלומר, הגדרה של delayInMinutes או periodInMinutes כערך נמוך מ-0.5 לא תכובד ותגרום לאזהרה. ניתן להגדיר את when למשך פחות מ-30 שניות אחרי הערך 'עכשיו' ללא אזהרה, אך למעשה לא תגרום להפעלת ההתראה למשך 30 שניות לפחות.
כדי לעזור לכם לנפות באגים באפליקציה או בתוסף, אחרי שטענתם אותם במצב פרודוקטיבי, אין הגבלה על תדירות ההפעלה של ההתראה.
פרמטרים
-
שם
מחרוזת אופציונלי
שם אופציונלי לזיהוי ההתראה הזו. ברירת המחדל היא המחרוזת הריקה.
-
alarmInfo
מיועד לציין מתי האזעקה צריכה לפעול. צריך לציין את הזמן הראשוני על ידי
whenאו על ידיdelayInMinutes(אבל לא על ידי שניהם). אם המדיניותperiodInMinutesמוגדרת, ההתראה תחזור על עצמה כלperiodInMinutesדקות אחרי האירוע הראשוני. אם לא הוגדרוwhenאוdelayInMinutesלהתראה חוזרת,periodInMinutesישמש כברירת המחדל בשבילdelayInMinutes. -
קריאה חוזרת (callback)
פונקציה אופציונלית
Chrome 111 ואילךהפרמטר
callbackנראה כך:() => void
החזרות
-
הבטחה<Empty>
Chrome 111 ואילךהבטחות נתמכות במניפסט מגרסה V3 ואילך, אבל ניתנות קריאות חוזרות (callback) בשביל תאימות לאחור. לא ניתן להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה הזו מצליחה לפתור את הבעיה באותו סוג שמועבר לקריאה החוזרת.
get()
chrome.alarms.get(
name?: string,
callback?: function,
)
אחזור פרטים על ההתראה שצוינה.
פרמטרים
החזרות
-
Promise<Alarm | לא מוגדר>
Chrome מגרסה 91 ואילךהבטחות נתמכות במניפסט מגרסה V3 ואילך, אבל ניתנות קריאות חוזרות (callback) בשביל תאימות לאחור. לא ניתן להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה הזו מצליחה לפתור את הבעיה באותו סוג שמועבר לקריאה החוזרת.
getAll()
chrome.alarms.getAll(
callback?: function,
)
מקבל מערך של כל ההתראות.
פרמטרים
החזרות
-
מבטיח<התראה[]>
Chrome מגרסה 91 ואילךהבטחות נתמכות במניפסט מגרסה V3 ואילך, אבל ניתנות קריאות חוזרות (callback) בשביל תאימות לאחור. לא ניתן להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה הזו מצליחה לפתור את הבעיה באותו סוג שמועבר לקריאה החוזרת.