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