chrome.alarms

‫

תיאור

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

הרשאות

alarms

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

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

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

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

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

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

התמדה

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

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

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

checkAlarmState();

דוגמאות

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

מאפיינים

  • שם

    מחרוזת

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

  • periodInMinutes

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

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

  • persistAcrossSessions

    בוליאני

    בהמתנה

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

  • scheduledTime

    number

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

AlarmCreateInfo

מאפיינים

  • delayInMinutes

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

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

  • periodInMinutes

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

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

  • persistAcrossSessions

    boolean אופציונלי

    בהמתנה

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

  • מתי

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

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

Methods

clear()

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

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

פרמטרים

  • שם

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

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

החזרות

  • Promise<boolean>

    ‫Chrome 91 ואילך

clearAll()

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

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

החזרות

  • Promise<boolean>

    ‫Chrome 91 ואילך

create()

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

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

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

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

פרמטרים

  • שם

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

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

  • 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