browser.notifications

الوصف

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

الأذونات

notifications

الأنواع

NotificationBitmap

NotificationButton

الخصائص

  • iconUrl

    string اختياري

    تم إيقافها نهائيًا منذ الإصدار 59 من Chrome

    لا تظهر رموز الأزرار لمستخدمي Mac OS X.

  • title

    سلسلة

NotificationItem

الخصائص

  • رسالة

    سلسلة

    تفاصيل إضافية حول هذا العنصر

  • title

    سلسلة

    عنوان عنصر واحد في إشعار قائمة

NotificationOptions

الخصائص

  • appIconMaskUrl

    string اختياري

    تم إيقافها نهائيًا منذ الإصدار 59 من Chrome

    لا يظهر قناع رمز التطبيق لمستخدمي Mac OS X.

    عنوان URL لقناع رمز التطبيق تنطبق على عناوين URL القيود نفسها التي تنطبق على iconUrl.

    يجب أن يكون قناع رمز التطبيق في قناة ألفا، لأنّه سيتم أخذ قناة ألفا للصورة فقط في الاعتبار.

  • الأزرار

    NotificationButton[] اختيارية

    النص والرموز لما يصل إلى زرَّين من أزرار الإجراءات في الإشعارات

  • contextMessage

    string اختياري

    محتوى الإشعار البديل بخط أقل سُمكًا

  • eventTime

    number اختيارية

    طابع زمني مرتبط بالإشعار، بالملي ثانية بعد الحقبة (مثلاً Date.now() + n).

  • iconUrl

    string اختياري

    عنوان URL لأفاتار المُرسِل أو رمز التطبيق أو صورة مصغّرة لإشعارات الصور

    يمكن أن تكون عناوين URL عبارة عن عنوان URL للبيانات أو عنوان URL لملف ثنائي كبير أو عنوان URL مرتبط بمورد ضمن ملف ‎ .crx الخاص بهذه الإضافة

    **ملاحظة:**هذه القيمة مطلوبة لطريقة notifications.create().

  • imageUrl

    string اختياري

    تم إيقافها نهائيًا منذ الإصدار 59 من Chrome

    لا تظهر الصورة لمستخدمي Mac OS X.

    عنوان URL للصورة المصغّرة للإشعارات من نوع الصورة تنطبق على عناوين URL القيود نفسها التي تنطبق على iconUrl.

  • isClickable

    قيمة منطقية اختيارية

    تم إيقافها نهائيًا منذ الإصدار 67 من Chrome

    يتم تجاهل تلميح واجهة المستخدم هذا اعتبارًا من الإصدار 67 من Chrome

  • items

    NotificationItem[] اختياري

    عناصر لإشعارات متعددة العناصر يرى مستخدمو نظام التشغيل Mac OS X العنصر الأول فقط.

  • رسالة

    string اختياري

    المحتوى الرئيسي للإشعار

    **ملاحظة:**هذه القيمة مطلوبة لطريقة notifications.create().

  • الحملة

    number اختيارية

    تتراوح الأولوية من -2 إلى 2. ‫-2 هي الأولوية الأدنى. والمستوى 2 هو الأعلى. القيمة التلقائية هي صفر. على الأنظمة الأساسية التي لا تتيح مركز إشعارات (Windows وLinux وMac)، يؤدي الإعدادان ‎-2 و‎-1 إلى حدوث خطأ لأنّ الإشعارات ذات الأولويات لن تظهر على الإطلاق.

  • التقدم

    number اختيارية

    يتراوح مستوى التقدّم الحالي بين 0 و100.

  • requireInteraction

    قيمة منطقية اختيارية

    الإصدار 50 من Chrome والإصدارات الأحدث متصفّح.* منذ الإصدار 148 من Chrome

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

  • الوضع الصامت

    قيمة منطقية اختيارية

    الإصدار 70 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

    يشير هذا الخيار إلى أنّه يجب عدم إصدار أي أصوات أو اهتزازات عند عرض الإشعار. ويتم ضبط القيمة التلقائية على "خطأ".

  • title

    string اختياري

    عنوان الإشعار (مثل اسم المُرسِل للبريد الإلكتروني)

    **ملاحظة:**هذه القيمة مطلوبة لطريقة notifications.create().

  • النوع

    TemplateType اختيارية

    نوع الإشعار الذي سيتم عرضه مطلوبة لطريقة notifications.create.

PermissionLevel

Enum

"granted"
يشير إلى أنّ المستخدم قد اختار عرض الإشعارات من التطبيق أو الإضافة. هذا هو الخيار التلقائي في وقت التثبيت.

"denied"
يحدّد أنّ المستخدم قد اختار عدم عرض الإشعارات من التطبيق أو الإضافة.

TemplateType

Enum

"basic"
يحتوي على رمز وعنوان ورسالة وexpandedMessage وزرَّين كحدّ أقصى.

"image"
يحتوي على رمز وعنوان ورسالة وexpandedMessage وصورة وزرَّين كحدّ أقصى.

"list"
يحتوي على رمز وعنوان ورسالة وعناصر وزرَّين كحدّ أقصى. أما مستخدمو نظام التشغيل Mac OS X، فيظهر لهم العنصر الأول فقط.

"progress"
يحتوي على رمز وعنوان ورسالة ومؤشر تقدّم وزرَّين كحدّ أقصى.

الطُرق

clear()

browser.notifications.clear(
  notificationId: string,
): Promise<boolean>

لمحو الإشعار المحدّد

المعلمات

  • notificationId

    سلسلة

    رقم تعريف الإشعار المطلوب محوه يتم عرض هذه القيمة من خلال الإجراء notifications.create.

المرتجعات

  • Promise<boolean>

    الإصدار 116 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

    تعرض هذه الطريقة كائن Promise يتم تحليله للإشارة إلى ما إذا كان هناك إشعار مطابق.

create()

browser.notifications.create(
  notificationId?: string,
  options: NotificationOptions,
): Promise<string>

لإنشاء إشعار وعرضه

المعلمات

  • notificationId

    string اختياري

    معرّف الإشعار في حال عدم ضبطه أو تركه فارغًا، سيتم إنشاء معرّف تلقائيًا. إذا كان الإشعار يتطابق مع إشعار حالي، ستزيل هذه الطريقة الإشعار الحالي أولاً قبل المتابعة في عملية الإنشاء. يجب ألا يزيد طول المعرّف عن 500 حرف.

    تكون المَعلمة notificationId مطلوبة قبل الإصدار 42 من Chrome.

  • الخيارات

    NotificationOptions

    محتوى الإشعار

المرتجعات

  • وعد<سلسلة>

    الإصدار 116 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

    تعرض هذه الطريقة كائن Promise يتم حله باستخدام معرّف الإشعار (سواء تم توفيره أو إنشاؤه) الذي يمثّل الإشعار الذي تم إنشاؤه.

getAll()

browser.notifications.getAll(): Promise<object>

يسترد هذا الإجراء جميع إشعارات هذا التطبيق أو الإضافة.

المرتجعات

  • وعد<كائن>

    الإصدار 116 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

    تعرض هذه الطريقة Promise يتم حلّه باستخدام مجموعة notification_ids المتوفّرة حاليًا في النظام.

getPermissionLevel()

browser.notifications.getPermissionLevel(): Promise<PermissionLevel>

تسترد هذه الطريقة ما إذا كان المستخدم قد فعّل الإشعارات من هذا التطبيق أو الإضافة.

المرتجعات

  • Promise<PermissionLevel>

    الإصدار 116 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

    تعرض هذه الطريقة كائن Promise يتم حله باستخدام مستوى الإذن الحالي.

update()

browser.notifications.update(
  notificationId: string,
  options: NotificationOptions,
): Promise<boolean>

تعديل إشعار حالي

المعلمات

  • notificationId

    سلسلة

    رقم تعريف الإشعار المطلوب تعديله يتم عرض هذه القيمة من خلال الإجراء notifications.create.

  • الخيارات

    NotificationOptions

    محتوى الإشعار الذي تريد تعديله

المرتجعات

  • Promise<boolean>

    الإصدار 116 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

    تعرض هذه الطريقة كائن Promise يتم تحليله للإشارة إلى ما إذا كان هناك إشعار مطابق.

الفعاليات

onButtonClicked

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

ضغط المستخدم على زر في الإشعار.

المعلمات

  • callback

    دالة

    تظهر المَعلمة callback على النحو التالي: 

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

    • notificationId

      سلسلة

    • buttonIndex

      الرقم

onClicked

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

نقَر المستخدم على منطقة في الإشعار لا تحتوي على زر.

المعلمات

  • callback

    دالة

    تظهر المَعلمة callback على النحو التالي: 

    (notificationId: string) => void

    • notificationId

      سلسلة

onClosed

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

تم إغلاق الإشعار، إما من خلال النظام أو من خلال إجراء المستخدم.

المعلمات

  • callback

    دالة

    تظهر المَعلمة callback على النحو التالي: 

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

    • notificationId

      سلسلة

    • byUser

      قيمة منطقية

onPermissionLevelChanged

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

يغيّر المستخدم مستوى الإذن. اعتبارًا من الإصدار 47 من Chrome، يتوفّر فقط في ChromeOS واجهة مستخدم ترسل هذا الحدث.

المعلمات

onShowSettings

تم إيقافها نهائيًا منذ الإصدار 65 من Chrome
browser.notifications.onShowSettings.addListener(
  callback: function,
)

لم يعُد زر إعدادات الإشعارات المخصّصة متاحًا.

نقَر المستخدم على رابط يؤدي إلى إعدادات الإشعارات في التطبيق. اعتبارًا من الإصدار 47 من Chrome، يتوفّر فقط في ChromeOS واجهة مستخدم ترسل هذا الحدث. واعتبارًا من الإصدار 65 من Chrome، تمت إزالة واجهة المستخدم هذه من ChromeOS أيضًا.

المعلمات

  • callback

    دالة

    تظهر المَعلمة callback على النحو التالي: 

    () => void