שימוש ב-Notifications API

ב-API של chrome.notifications אפשר ליצור התראות באמצעות תבניות ולהציג את ההתראות האלה התראות למשתמשים במגש המערכת של המשתמש:

איך הם נראים

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

התראה בסיסית:

בהתראות על רשימות מוצגות כל מספר של פריטים ברשימה:

התראות של תמונות כוללות תצוגה מקדימה של תמונה:

בהתראות על ההתקדמות מוצג סרגל התקדמות:

איך הם מתנהגים

ב-ChromeOS, ההתראות מופיעות במגש המערכת של המשתמש, ונשארות במגש המערכת עד משתמש סוגר אותן. במגש המערכת מוצג ספירה של כל ההתראות החדשות. ברגע שמשתמש רואה את התראות במגש המערכת, הספירה מתאפסת לאפס.

אפשר להקצות להתראות עדיפות בין 2- ל-2. עדיפויות מתחת ל-0 מוצגות ב-ChromeOS במרכז ההתראות, ומפיקה שגיאה בפלטפורמות אחרות. עדיפות ברירת המחדל היא 0. עדיפויות גדולות מ-0 מוצגות למשך זמן ארוך יותר, וניתן להציג יותר התראות עם עדיפות גבוהה שמוצג במגש המערכת.

ההגדרה priority לא משפיעה על סדר ההתראות ב-macOS.

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

איך לפתח אותם

כדי להשתמש ב-API הזה, קוראים לשיטה notifications.create() ומעבירים את פרטי ההתראה באמצעות הפרמטר options:

await chrome.notifications.create(id, options);

השדה notifications.NotificationOptions חייב לכלול את התג notifications.TemplateType, מגדיר את הפרטים הזמינים של התראות ואת האופן שבו הפרטים האלה יוצגו.

יצירת התראה בסיסית

כל סוגי התבניות (basic, image, list ו-progress) חייבים לכלול הודעה title וגם message, וגם iconUrl, שהוא קישור לסמל קטן שמוצג משמאל הודעת ההתראה.

דוגמה לתבנית basic:

var opt = {
  type: "basic",
  title: "Primary Title",
  message: "Primary message to display",
  iconUrl: "url_to_small_icon"
}

שימוש בתמונה

סוג התבנית image כולל גם imageUrl, שהוא קישור לתמונה שמוצגת בתצוגה מקדימה בהודעה. שימו לב שתמונות לא מוצגות למשתמשים ב-macOS.

var opt = {
  type: "image",
  title: "Primary Title",
  message: "Primary message to display",
  iconUrl: "url_to_small_icon",
  imageUrl: "url_to_preview_image"
}

התראה על יצירת רשימה

בתבנית list מוצג items בפורמט של רשימה. שימו לב שרק הפריט הראשון מוצג למשתמשים ב-macOS.

var opt = {
  type: "list",
  title: "Primary Title",
  message: "Primary message to display",
  iconUrl: "url_to_small_icon",
  items: [{ title: "Item1", message: "This is item 1."},
          { title: "Item2", message: "This is item 2."},
          { title: "Item3", message: "This is item 3."}]
}```

### Create progress notification {: #progress }

The `progress` template displays a progress bar where current progress ranges from 0 to 100. On macOS the progress bar displays as a percentage value in the notification title instead of in the progress bar.

```js
var opt = {
  type: "progress",
  title: "Primary Title",
  message: "Primary message to display",
  iconUrl: "url_to_small_icon",
  progress: 42
}

איך מקשיבים לאירועים ועונים עליהם

כל ההתראות יכולות לכלול פונקציות event listener ורכיבי handler של אירועים שמגיבים לפעולות של משתמשים (ראו chrome.events). לדוגמה, אפשר לכתוב את הגורם המטפל באירועים שיגיב על אירוע notifications.onButtonClicked.

האזנה לאירועים:

chrome.notifications.onButtonClicked.addListener(replyBtnClick);

הגורם המטפל באירוע:

function replyBtnClick {
    //Write function to respond to user action.
}

כדאי לכלול פונקציות event listener ומטפלים ב-Service Worker, כדי שההתראות יכול לקפוץ גם כשהתוסף לא פועל.