استخدام واجهة برمجة التطبيقات Notification API

تتيح لك واجهة برمجة التطبيقات browser.notifications إنشاء إشعارات باستخدام النماذج وعرض هذه الإشعارات للمستخدمين في علبة النظام:

الشكل الذي تظهر به

تتوفّر الإشعارات الغنية بأربعة أنواع مختلفة: أساسية وصورة وقائمة وتقدّم. تتضمّن جميع الإشعارات عنوانًا ورسالة ورمزًا صغيرًا يظهر على يمين رسالة الإشعار وحقل contextMessage، ويظهر هذا الحقل كحقل نص ثالث بخط بلون أفتح.

إشعار أساسي:

تعرض إشعارات القوائم أي عدد من عناصر القائمة:

تتضمّن إشعارات الصور معاينة للصورة:

تعرض إشعارات مستوى التقدّم شريطًا:

سلوكيات الجمهور

في ChromeOS، تظهر الإشعارات في لوحة نظام المستخدم، وتبقى فيها إلى أن يغلقها المستخدم. تحتفظ لوحة النظام بعدد جميع الإشعارات الجديدة. بعد أن يرى المستخدم الإشعارات في لوحة النظام، تتم إعادة ضبط العدد إلى صفر.

يمكن تحديد أولوية للإشعارات تتراوح بين -2 و2. يتم عرض الأولويات الأقل من 0 في مركز إشعارات ChromeOS، ويؤدي استخدامها إلى حدوث خطأ على المنصات الأخرى. الأولوية التلقائية هي 0. تظهر الأولويات الأكبر من 0 لمدة أطول، ويمكن عرض المزيد من الإشعارات ذات الأولوية العالية في علبة النظام.

لا يؤثّر الإعداد priority في ترتيب الإشعارات على أجهزة macOS.

بالإضافة إلى عرض المعلومات، يمكن أن تتضمّن جميع أنواع الإشعارات ما يصل إلى عنصرَي إجراء. عندما ينقر المستخدمون على عنصر إجراء، يمكن أن يستجيب تطبيقك باتّخاذ الإجراء المناسب. على سبيل المثال، عندما ينقر المستخدم على رد، يفتح تطبيق البريد الإلكتروني ويمكن للمستخدم إكمال الرد:

كيفية تطويرها

لاستخدام واجهة برمجة التطبيقات هذه، استدعِ طريقة 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.

متتبِّع الأحداث:

browser.notifications.onButtonClicked.addListener(replyBtnClick);

معالج الأحداث:

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

ننصحك بتضمين أدوات معالجة الأحداث وأدوات معالجة الأخطاء في عامل الخدمة، حتى تظهر الإشعارات حتى عندما لا يكون التطبيق قيد التشغيل.