chrome.alarms

תיאור

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

הרשאות

alarms

מניפסט

כדי להשתמש ב-chrome.alarms API, צריך להצהיר על ההרשאה "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 דקות.

  • scheduledTime

    number

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

AlarmCreateInfo

מאפיינים

  • delayInMinutes

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

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

  • periodInMinutes

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

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

  • מתי

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

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

Methods

clear()

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

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

פרמטרים

  • שם

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

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

  • callback

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

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

    (wasCleared: boolean) => void

    • wasCleared

      בוליאני

החזרות

  • Promise<boolean>

    ‫Chrome 91 ואילך

    ההבטחות נתמכות רק ב-Manifest V3 ובגרסאות מאוחרות יותר. בפלטפורמות אחרות צריך להשתמש בפונקציות Callback.

clearAll()

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

מחיקת כל השעונים המעוררים.

פרמטרים

  • callback

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

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

    (wasCleared: boolean) => void

    • wasCleared

      בוליאני

החזרות

  • Promise<boolean>

    ‫Chrome 91 ואילך

    ההבטחות נתמכות רק ב-Manifest V3 ובגרסאות מאוחרות יותר. בפלטפורמות אחרות צריך להשתמש בפונקציות Callback.

create()

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

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

החזרות

  • Promise<void>

    ‫Chrome 111 ואילך

    ההבטחות נתמכות רק ב-Manifest V3 ובגרסאות מאוחרות יותר. בפלטפורמות אחרות צריך להשתמש בפונקציות Callback.

get()

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

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

פרמטרים

  • שם

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

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

  • callback

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

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

    (alarm?: Alarm) => void

החזרות

  • Promise<Alarm | undefined>

    ‫Chrome 91 ואילך

    ההבטחות נתמכות רק ב-Manifest V3 ובגרסאות מאוחרות יותר. בפלטפורמות אחרות צריך להשתמש בפונקציות Callback.

getAll()

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

מחזירה מערך של כל השעונים המעוררים.

פרמטרים

  • callback

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

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

    (alarms: Alarm[]) => void

החזרות

  • Promise<Alarm[]>

    ‫Chrome 91 ואילך

    ההבטחות נתמכות רק ב-Manifest V3 ובגרסאות מאוחרות יותר. בפלטפורמות אחרות צריך להשתמש בפונקציות Callback.

אירועים

onAlarm

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

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

פרמטרים

  • callback

    פונקציה

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

    (alarm: Alarm) => void