browser.alarms

תיאור

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

הרשאות

alarms

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

Set an alarm

בדוגמה הבאה מוגדרת התראה ב-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

    ‫boolean אופציונלי

    ‫Chrome 150 ואילך

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

  • מתי

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

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