chrome.alarms

תיאור

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

הרשאות

alarms

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

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

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

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

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

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

התמדה

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

const STORAGE_KEY = "user-preference-alarm-enabled";

async function checkAlarmState() {
  const { alarmEnabled } = await chrome.storage.get(STORAGE_KEY);

  if (alarmEnabled) {
    const alarm = await chrome.alarms.get("my-alarm");

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

checkAlarmState();

דוגמאות

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

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

AlarmCreateInfo

מאפיינים

  • delayInMinutes

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

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

  • periodInMinutes

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

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

  • מתי

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

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

שיטות

clear()

הבטחה
chrome.alarms.clear(
  name?: string,
  callback?: function,
)

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

פרמטרים

  • שם

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

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

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

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

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

    (wasCleared: boolean) => void

    • wasCleared

      בוליאני

החזרות

  • Promise<boolean>

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

    הבטחות נתמכות במניפסט מגרסה V3 ואילך, אבל ניתנות קריאות חוזרות (callback) בשביל תאימות לאחור. לא ניתן להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה הזו מצליחה לפתור את הבעיה באותו סוג שמועבר לקריאה החוזרת.

clearAll()

הבטחה
chrome.alarms.clearAll(
  callback?: function,
)

ניקוי כל ההתראות

פרמטרים

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

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

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

    (wasCleared: boolean) => void

    • wasCleared

      בוליאני

החזרות

  • 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 שניות לפחות.

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

פרמטרים

  • שם

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

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

  • alarmInfo

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

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

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

    Chrome 111 ואילך

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

    () => void

החזרות

  • הבטחה<Empty>

    Chrome 111 ואילך

    הבטחות נתמכות במניפסט מגרסה V3 ואילך, אבל ניתנות קריאות חוזרות (callback) בשביל תאימות לאחור. לא ניתן להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה הזו מצליחה לפתור את הבעיה באותו סוג שמועבר לקריאה החוזרת.

get()

הבטחה
chrome.alarms.get(
  name?: string,
  callback?: function,
)

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

פרמטרים

  • שם

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

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

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

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

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

    (alarm?: Alarm) => void

החזרות

  • Promise&lt;Alarm | לא מוגדר>

    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