chrome.alarms

תיאור

הרשאות

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

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

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

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

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

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

התמדה

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

דפדפנים אחרים וגרסאות קודמות של Chrome

המאפיין הזה לא נתמך בדפדפנים אחרים (בעיה) או בגרסאות של Chrome לפני Chrome 150, שבהן ההתנהגות יכולה להיות בלתי צפויה. לכן, מומלץ לוודא שקיימות התראות חשובות בכל פעם ש-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 }) => {
  // Create an alarm so we have something to look at in the demo
  await chrome.alarms.create('demo-default-alarm', {
    delayInMinutes: 1,
    periodInMinutes: 1,
    persistAcrossSessions: true
  });
});

איך מגיבים לאזעקה

בדוגמה הבאה, הסמל של סרגל הכלים של הפעולה מוגדר על סמך שם האזעקה שהופעלה.

‫service-worker.js:

chrome.alarms.onAlarm.addListener((alarm) => {
  chrome.action.setIcon({
    path: getIconPath(alarm.name),
  });
});

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

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

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

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

chrome.alarms.getAll(): Promise<Alarm[]>

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