chrome.alarms

refresh date: 2026-09-25 robots: noindex

תיאור

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

הרשאות

alarms

מניפסט

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

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

דוגמאות

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

מאפיינים

  • שם

    מחרוזת

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

  • 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()

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

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

פרמטרים

  • שם

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

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

  • callback

    function optional

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

    (wasCleared: boolean) => void

    • wasCleared

      בוליאני

החזרות

  • Promise<boolean>

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

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

clearAll()

Promise 
chrome.alarms.clearAll(
  callback?: function,
): Promise<boolean | undefined>

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

פרמטרים

  • callback

    function optional

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

    (wasCleared?: boolean) => void

    • wasCleared

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

החזרות

  • Promise<boolean | undefined>

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

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

create()

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

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

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

פרמטרים

  • שם

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

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

  • alarmInfo

    AlarmCreateInfo

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

  • callback

    function optional

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

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

    () => void

החזרות

  • Promise<void>

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

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

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

get()

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

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

פרמטרים

  • שם

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

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

  • callback

    function optional

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

    (alarm?: Alarm) => void

    • שעון מעורר

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

החזרות

  • Promise<Alarm | undefined>

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

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

getAll()

Promise 
chrome.alarms.getAll(
  callback?: function,
): Promise<Alarm[]>

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

פרמטרים

  • callback

    function optional

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

    (alarms: Alarm[]) => void

החזרות

  • Promise<Alarm[]>

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

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

אירועים

onAlarm

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

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

פרמטרים

  • callback

    פונקציה

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

    (alarm: Alarm) => void