chrome.notifications

תיאור

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

הרשאות

notifications

סוגים

NotificationBitmap

NotificationButton

תכונות

  • iconUrl

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

    הוצא משימוש מאז Chrome 59

    סמלי לחצנים אינם גלויים למשתמשי Mac OS X.

  • title

    מחרוזת

NotificationItem

תכונות

  • הודעה

    מחרוזת

    פרטים נוספים על הפריט הזה.

  • title

    מחרוזת

    כותרת של פריט אחד מהתראה ברשימה.

NotificationOptions

תכונות

  • appIconMaskUrl

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

    הוצא משימוש מאז Chrome 59

    המסכה של סמל האפליקציה אינה גלויה למשתמשי Mac OS X.

    כתובת URL למסכה של סמל האפליקציה. על כתובות ה-URL חלות אותן ההגבלות כמו בפרמטר iconUrl.

    המסכה של סמל האפליקציה צריכה להופיע בערוץ אלפא, כי רק ערוץ האלפא של התמונה ייכלל.

  • לחצנים

    NotificationButton[] אופציונלי

    טקסט וסמלים המשמשים עבור עד שני לחצני פעולה בהודעות.

  • contextMessage

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

    תוכן התראה חלופי בגופן בעל משקל נמוך יותר.

  • eventTime

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

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

  • iconUrl

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

    כתובת URL לדמות של השולח, סמל האפליקציה או תמונה ממוזערת של התראות על תמונות.

    כתובות URL יכולות להיות כתובת URL של נתונים, כתובת URL של blob או כתובת URL יחסית למשאב בקובץ ה- .crx של התוסף הזה

    **הערה:**זהו ערך חובה עבור השיטה notifications.create().

  • imageUrl

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

    הוצא משימוש מאז Chrome 59

    התמונה אינה גלויה למשתמשי Mac OS X.

    כתובת URL של התמונה הממוזערת של התראות מסוג תמונה. על כתובות ה-URL חלות אותן ההגבלות כמו בפרמטר iconUrl.

  • isClickable

    בוליאני אופציונלי

    הוצא משימוש מאז Chrome 67

    החל מגרסה 67 של Chrome, המערכת מתעלמת מהרמז הזה לממשק המשתמש

  • items

    NotificationItem[] אופציונלי

    פריטים להתראות של פריטים מרובים. משתמשים ב-Mac OS X רואים רק את הפריט הראשון.

  • הודעה

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

    התוכן הראשי של ההתראות.

    **הערה:**זהו ערך חובה עבור השיטה notifications.create().

  • הקמפיין

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

    העדיפות נעה בין 2- ל-2. 2- הוא העדיפות הנמוכה ביותר. 2 הוא הגבוה ביותר. ברירת המחדל של אפס היא אפס. בפלטפורמות שאינן תומכות במרכז הודעות (Windows , Linux ו-Mac ), הערכים -2 ו- -1 יגרמו לשגיאה, כי התראות עם העדיפויות האלה לא יוצגו כלל.

  • התקדמות

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

    ההתקדמות הנוכחית נעה בין 0 ל-100.

  • requireInteraction

    בוליאני אופציונלי

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

    מציינת שההודעה צריכה להישאר גלויה במסך עד שהמשתמש יפעיל או יסגור את ההתראה. ערך ברירת המחדל הוא False.

  • שקט

    בוליאני אופציונלי

    Chrome 70 ומעלה

    מציין שלא יושמעו צלילים או רטט כשההודעה מוצגת. ערך ברירת המחדל הוא False.

  • title

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

    כותרת ההתראה (למשל, שם השולח לאימייל).

    **הערה:**זהו ערך חובה עבור השיטה notifications.create().

  • סוג

    TemplateType אופציונלי

    איזה סוג של התראה להציג. חובה בשיטה notifications.create.

PermissionLevel

טיפוסים בני מנייה (enum)

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

'נדחתה'
מציינת שהמשתמש בחר לא להציג התראות מהאפליקציה או מהתוסף.

TemplateType

טיפוסים בני מנייה (enum)

"בסיסי"
מכיל סמל, כותרת, הודעה, הודעה מורחבת ועד שני לחצנים.

"image"
מכיל סמל, כותרת, הודעה, הודעה מורחבת, תמונה ועד שני לחצנים.

"list"
מכילה סמל, כותרת, הודעה, פריטים ועד שני לחצנים. משתמשים ב-Mac OS X רואים רק את הפריט הראשון.

"progress"
מכילה סמל, כותרת, הודעה, התקדמות ושני לחצנים לכל היותר.

שיטות

clear()

הבטחה 
chrome.notifications.clear(
  notificationId: string,
  callback?: function,
)

ניקוי ההתראה שצוינה.

פרמטרים

  • notificationId

    מחרוזת

    המזהה של ההתראה שיש למחוק. הערך הזה מוחזר על ידי שיטת notifications.create.

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

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

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

    (wasCleared: boolean)=>void

    • wasCleared

      boolean

החזרות

  • Promise<boolean>

    Chrome 116 ומעלה

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

create()

הבטחה 
chrome.notifications.create(
  notificationId?: string,
  options: NotificationOptions,
  callback?: function,
)

יצירה והצגה של התראה.

פרמטרים

  • notificationId

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

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

    הפרמטר notificationId נדרש לפני Chrome 42.

  • אפשרויות

    NotificationOptions

    תוכן ההתראה.

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

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

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

    (notificationId: string)=>void

    • notificationId

      מחרוזת

החזרות

  • הבטחה<string>

    Chrome 116 ומעלה

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

getAll()

הבטחה 
chrome.notifications.getAll(
  callback?: function,
)

מאחזר את כל ההתראות של האפליקציה או התוסף.

פרמטרים

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

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

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

    (notifications: object)=>void

    • התראות

      אובייקט

החזרות

  • Promise<object>

    Chrome 116 ומעלה

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

getPermissionLevel()

הבטחה 
chrome.notifications.getPermissionLevel(
  callback?: function,
)

אחזור אם המשתמש הפעיל התראות מהאפליקציה או מהתוסף האלה.

פרמטרים

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

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

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

    (level: PermissionLevel)=>void

החזרות

  • Promise<PermissionLevel>

    Chrome 116 ומעלה

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

update()

הבטחה 
chrome.notifications.update(
  notificationId: string,
  options: NotificationOptions,
  callback?: function,
)

מעדכן התראה קיימת.

פרמטרים

  • notificationId

    מחרוזת

    המזהה של ההתראה לעדכון. הערך הזה מוחזר על ידי שיטת notifications.create.

  • אפשרויות

    NotificationOptions

    תוכן ההתראה שצריך לעדכן.

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

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

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

    (wasUpdated: boolean)=>void

    • wasUpdated

      boolean

החזרות

  • Promise<boolean>

    Chrome 116 ומעלה

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

אירועים

onButtonClicked

chrome.notifications.onButtonClicked.addListener(
  callback: function,
)

המשתמש לחץ על לחצן בהתראה.

פרמטרים

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

    פונקציה

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

    (notificationId: string,buttonIndex: number)=>void

    • notificationId

      מחרוזת

    • buttonIndex

      מספר

onClicked

chrome.notifications.onClicked.addListener(
  callback: function,
)

המשתמש לחץ על אזור בהתראה שאינו לחצנים.

פרמטרים

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

    פונקציה

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

    (notificationId: string)=>void

    • notificationId

      מחרוזת

onClosed

chrome.notifications.onClosed.addListener(
  callback: function,
)

ההתראה נסגרה על ידי המערכת או על ידי פעולה מצד המשתמש.

פרמטרים

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

    פונקציה

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

    (notificationId: string,byUser: boolean)=>void

    • notificationId

      מחרוזת

    • byUser

      boolean

onPermissionLevelChanged

chrome.notifications.onPermissionLevelChanged.addListener(
  callback: function,
)

המשתמש משנה את רמת ההרשאה. החל מגרסה 47 של Chrome, רק ל-ChromeOS יש ממשק משתמש ששולח את האירוע הזה.

פרמטרים

onShowSettings

הוצא משימוש מאז Chrome 65
chrome.notifications.onShowSettings.addListener(
  callback: function,
)

לחצן הגדרת ההתראות בהתאמה אישית לא נתמך יותר.

המשתמש לחץ על קישור להגדרות ההודעות של האפליקציה. החל מגרסה 47 של Chrome, רק ל-ChromeOS יש ממשק משתמש ששולח את האירוע הזה. החל מגרסה 65 של Chrome, גם ממשק המשתמש הזה הוסר מ-ChromeOS.

פרמטרים

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

    פונקציה

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

    ()=>void