chrome.alarms

תיאור

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

הרשאות

alarms

מניפסט

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

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

דוגמאות

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

    מספר

    הזמן שבו ההתראה הזו תוזמנה לפעול, באלפיות שנייה לאחר התקופה של זמן מערכת (לדוגמה, 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

    AlarmCreateInfo

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

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

פרמטרים

  • name

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

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

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

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

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

    (alarm?: Alarm)=>void

החזרות

  • הבטחה<התראה|לא מוגדר>

    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