שימוש ב-Notifications API

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

איך הם נראים

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

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

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

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

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

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

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

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

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

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

איך מפתחים אותם

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

await browser.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
}

האזנה לאירועים ותגובה להם

כל ההתראות יכולות לכלול מאזינים לאירועים ומטפלים באירועים שמגיבים לפעולות של משתמשים (ראו browser.events). לדוגמה, אפשר לכתוב מטפל באירועים כדי להגיב לאירוע notifications.onButtonClicked.

רכיב event listener:

browser.notifications.onButtonClicked.addListener(replyBtnClick);

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

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

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