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