chrome.alarms

תיאור

אפשר להשתמש ב-API של chrome.alarms כדי לתזמן קוד כך שירוץ מדי פעם או בתאריך מוגדר בעתיד.

הרשאות

alarms

מניפסט

כדי להשתמש ב-API chrome.alarms, צריך להצהיר על ההרשאה "alarms" במניפסט:

{
  "name": "My extension",
  ...
  "permissions": [
    "alarms"
  ],
  ...
}

דוגמאות

בדוגמאות הבאות אפשר לראות איך להשתמש בהתראה ואיך להגיב אליה. כדי לנסות את ה-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

    AlarmCreateInfo

    מיועד לציין מתי האזעקה צריכה לפעול. צריך לציין את הזמן הראשוני על ידי 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,
)

אחזור פרטים על ההתראה שצוינה.

פרמטרים

  • שם

    מחרוזת אופציונלי

    שם ההתראה לקבל. ברירת המחדל היא המחרוזת הריקה.

  • קריאה חוזרת (callback)

    פונקציה אופציונלית

    הפרמטר callback נראה כך: 

    (alarm?: Alarm) => void

החזרות

  • Promise&lt;Alarm | לא מוגדר>

    Chrome מגרסה 91 ואילך

    הבטחות נתמכות רק במניפסט מגרסה V3 ואילך, בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callback).

getAll()

הבטחה 
chrome.alarms.getAll(
  callback?: function,
)

מקבל מערך של כל ההתראות.

פרמטרים

  • קריאה חוזרת (callback)

    פונקציה אופציונלית

    הפרמטר callback נראה כך: 

    (alarms: Alarm[]) => void

החזרות

  • מבטיח<התראה[]>

    Chrome מגרסה 91 ואילך

    הבטחות נתמכות רק במניפסט מגרסה V3 ואילך, בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callback).

אירועים

onAlarm

chrome.alarms.onAlarm.addListener(
  callback: function,
)

מופעל כשחלה התראה. שימושי לדפי אירועים.

פרמטרים

  • קריאה חוזרת (callback)

    פונקציה

    הפרמטר callback נראה כך: 

    (alarm: Alarm) => void