browser.alarms

תיאור

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

הרשאות

alarms

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

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

מושגים ושימוש

כדי להבטיח התנהגות אמינה, כדאי להבין איך ה-API פועל.

מצב שינה במכשיר

ההתראות ממשיכות לפעול כשהמכשיר במצב שינה. עם זאת, השעון המעורר לא יפעיל את המכשיר. כשהמכשיר יתעורר, כל ההתראות שפספסתם יופעלו. התראות חוזרות יופעלו פעם אחת לכל היותר, ואז יתוזמנו מחדש לפי פרק הזמן שצוין, החל מהרגע שבו המכשיר יוצא ממצב שינה, בלי להתחשב בזמן שכבר חלף מאז שההתראה הוגדרה במקור לפעול.

התמדה

אתם יכולים לשלוט בהתמדה של התראה בזמן היצירה באמצעות הדגל persistAcrossSessions. אפשר להגדיר את המדיניות הזו לערך true (נשמר עד שהתוסף מתעדכן) או לערך false (נמחק אם התוסף נטען מחדש או שהדפדפן מופעל מחדש, ובכל פעם שהתוסף מתעדכן).

דפדפנים אחרים וגרסאות קודמות של Chrome

המאפיין הזה לא נתמך בדפדפנים אחרים (בעיה) או בגרסאות של Chrome לפני Chrome 150, שבהן ההתנהגות יכולה להיות בלתי צפויה. לכן, מומלץ לוודא שהתראות חשובות קיימות בכל פעם ש-Service Worker מופעל. לדוגמה:

async function checkAlarmState() {
  const alarm = await browser.alarms.get("my-alarm");

  if (!alarm) {
    await browser.alarms.create("my-alarm", { periodInMinutes: 1 });
  }
}

checkAlarmState();

אם ההתראה נוצרת באופן דינמי על סמך פעולת המשתמש, יכול להיות שתרצו לאחסן את ההתראה שנוצרה במקום אחר כדי שתוכלו ליצור אותה מחדש במקרה הצורך.

דוגמאות

בדוגמאות הבאות מוסבר איך להשתמש בהתראה ולהגיב לה. כדי לנסות את ה-API הזה, מתקינים את הדוגמה של Alarm API ממאגר chrome-extension-samples.

הגדרת התראה

בדוגמה הבאה מוגדרת התראה ב-service worker כשמותקנת גרסה חדשה של התוסף:

service-worker.js:

browser.runtime.onInstalled.addListener(async ({ reason }) => {
  // Create an alarm so we have something to look at in the demo
  await browser.alarms.create('demo-default-alarm', {
    delayInMinutes: 1,
    periodInMinutes: 1,
    persistAcrossSessions: true
  });
});

איך מגיבים להתראה

בדוגמה הבאה, סמל סרגל הכלים של הפעולה מוגדר על סמך השם של ההתראה שהופעלה.

service-worker.js:

browser.alarms.onAlarm.addListener((alarm) => {
  browser.action.setIcon({
    path: getIconPath(alarm.name),
  });
});

סוגים

Alarm

מאפיינים

  • שם

    מחרוזת

    השם של ההתראה הזו.

  • periodInMinutes

    מספר אופציונלי

    אם הערך הוא לא null, ההתראה היא התראה חוזרת והיא תופעל שוב בעוד periodInMinutes דקות.

  • persistAcrossSessions

    בוליאני

    ‫Chrome מגרסה 150 ואילך

    האם ההתראה צריכה להישמר בין סשנים (הפעלות מחדש של הדפדפן).

  • scheduledTime

    number

    השעה שבה ההתראה הזו תוכננה לפעול, באלפיות השנייה אחרי תחילת התקופה (למשל Date.now() + n). מסיבות שקשורות לביצועים, יכול להיות שההתראה עוכבה לפרק זמן שרירותי מעבר לכך.

AlarmCreateInfo

מאפיינים

  • delayInMinutes

    מספר אופציונלי

    משך הזמן בדקות שאחריו האירוע onAlarm אמור לפעול.

  • שם

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

    ‫Chrome מגרסה 152 ואילך

    השם של ההתראה הזו.

  • periodInMinutes

    מספר אופציונלי

    אם ההגדרה הזו מוגדרת, האירוע onAlarm אמור לפעול כל periodInMinutes דקות אחרי האירוע הראשוני שצוין על ידי when או delayInMinutes. אם לא מגדירים את זה, ההתראה תופעל רק פעם אחת.

  • persistAcrossSessions

    בוליאני אופציונלי

    ‫Chrome מגרסה 150 ואילך

    האם ההתראה צריכה להישמר בין סשנים (הפעלות מחדש של הדפדפן). ב-Chrome, ערך ברירת המחדל הוא true כדי להתאים להתנהגות ההיסטורית, אבל כדאי להגדיר את זה באופן מפורש כדי למקסם את התאימות בין דפדפנים.

  • מתי

    מספר אופציונלי

    השעה שבה ההתראה אמורה לפעול, באלפיות השנייה אחרי תחילת התקופה (למשל Date.now() + n).

Methods

clear()

chrome.alarms.clear(
  name?: string,
): Promise<boolean>

מחיקת ההתראה עם השם שצוין.

פרמטרים

  • שם

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

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

החזרות

  • Promise<boolean>

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

clearAll()

chrome.alarms.clearAll(): Promise<boolean | undefined>

מחיקת כל ההתראות.

החזרות

  • Promise<boolean | undefined>

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

create()

chrome.alarms.create(
  name?: string,
  alarmInfo: AlarmCreateInfo,
): Promise<void>

יצירת התראה. בסמוך לזמנים שצוינו על ידי alarmInfo, האירוע onAlarm מופעל. אם יש התראה אחרת עם אותו שם (או בלי שם, אם לא צוין שם), היא תבוטל ותוחלף בהתראה הזו.

כדי להפחית את העומס על המחשב של המשתמש, Chrome מגביל את ההתראות לפעם אחת בשנייה לכל היותר, אבל יכול להיות שהן יתעכבו עוד קצת. כלומר, אם מגדירים את delayInMinutes או את periodInMinutes לערך נמוך משנייה אחת, המערכת תתעלם מההגדרה ותציג אזהרה. אפשר להגדיר את when לפחות משנייה אחת אחרי "עכשיו" בלי אזהרה, אבל ההתראה לא תופעל בפועל למשך שנייה אחת לפחות.

פרמטרים

  • שם

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

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

  • alarmInfo

    AlarmCreateInfo

    מתאר מתי השעון המעורר אמור לפעול. צריך לציין את השעה הראשונית באמצעות when או delayInMinutes (אבל לא את שניהם). אם מוגדר periodInMinutes, ההתראה תחזור על עצמה כל periodInMinutes דקות אחרי האירוע הראשוני. אם לא מגדירים את when או את delayInMinutes בשעון מעורר חוזר, המערכת משתמשת ב-periodInMinutes כברירת המחדל של delayInMinutes.

החזרות

  • Promise<void>

    ‫Chrome מגרסה 111 ואילך

    אובייקט Promise שמופעל כשההתראה נוצרת.

get()

chrome.alarms.get(
  name?: string,
): Promise<Alarm | undefined>

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

פרמטרים

  • שם

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

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

החזרות

  • Promise<Alarm | undefined>

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

getAll()

chrome.alarms.getAll(): Promise<Alarm[]>

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

החזרות

  • Promise<Alarm[]>

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

אירועים

onAlarm

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

מופעל כשמגיע הזמן של התראה. שימושי לדפי אירועים.

פרמטרים

  • callback

    פונקציה

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

    (alarm: Alarm) => void