chrome.notifications

الوصف

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

    number اختياري

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

  • iconUrl

    سلسلة اختيارية

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

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

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

  • imageUrl

    سلسلة اختيارية

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

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

    تمثّل هذه السمة عنوان URL للصورة المصغّرة للإشعارات من النوع "صورة". تخضع عناوين URL للقيود نفسها المفروضة على iconUrl.

  • isClickable

    boolean اختياري

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

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

  • items

    ‫NotificationItem[] اختياري

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

  • رسالة

    سلسلة اختيارية

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

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

  • الحملة

    number اختياري

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

  • التقدم

    number اختياري

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

  • requireInteraction

    boolean اختياري

    Chrome 50 والإصدارات الأحدث

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

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

    boolean اختياري

    الإصدار 70 من Chrome والإصدارات الأحدث

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

  • title

    سلسلة اختيارية

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

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

  • النوع

    TemplateType اختياري

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

PermissionLevel

Enum

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

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

TemplateType

Enum

"أساسي"
يحتوي على رمز وعنوان ورسالة ورسالة موسّعة وما يصل إلى زرّين.

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

"list"
يحتوي على رمز وعنوان ورسالة وعناصر وما يصل إلى زرّين. لا يرى مستخدمو نظام التشغيل Mac OS X سوى العنصر الأول.

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

الطُرق

clear()

الوعد 
chrome.notifications.clear(
  notificationId: string,
  callback?: function,
): Promise<boolean>

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

المعلمات

  • notificationId

    سلسلة

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

  • callback

    الدالة اختيارية

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

    (wasCleared: boolean) => void

    • wasCleared

      قيمة منطقية

المرتجعات

  • Promise<boolean>

    الإصدار 116 من Chrome والإصدارات الأحدث

    لا تتوافق الوعود إلا مع الإصدار Manifest V3 والإصدارات الأحدث، ويجب أن تستخدم المنصات الأخرى عمليات رد الاتصال.

create()

الوعد 
chrome.notifications.create(
  notificationId?: string,
  options: NotificationOptions,
  callback?: function,
): Promise<string>

تنشئ هذه الدالة إشعارًا وتعرضه.

المعلمات

  • notificationId

    سلسلة اختيارية

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

    يجب توفُّر المَعلمة notificationId قبل الإصدار 42 من Chrome.

  • الخيارات

    NotificationOptions

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

  • callback

    الدالة اختيارية

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

    (notificationId: string) => void

    • notificationId

      سلسلة

المرتجعات

  • Promise<string>

    الإصدار 116 من Chrome والإصدارات الأحدث

    لا تتوافق الوعود إلا مع الإصدار Manifest V3 والإصدارات الأحدث، ويجب أن تستخدم المنصات الأخرى عمليات رد الاتصال.

getAll()

الوعد 
chrome.notifications.getAll(
  callback?: function,
): Promise<object>

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

المعلمات

  • callback

    الدالة اختيارية

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

    (notifications: object) => void

    • الإشعارات

      عنصر

المرتجعات

  • Promise<object>

    الإصدار 116 من Chrome والإصدارات الأحدث

    لا تتوافق الوعود إلا مع الإصدار Manifest V3 والإصدارات الأحدث، ويجب أن تستخدم المنصات الأخرى عمليات رد الاتصال.

getPermissionLevel()

الوعد 
chrome.notifications.getPermissionLevel(
  callback?: function,
): Promise<PermissionLevel>

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

المعلمات

  • callback

    الدالة اختيارية

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

    (level: PermissionLevel) => void

المرتجعات

  • Promise<PermissionLevel>

    الإصدار 116 من Chrome والإصدارات الأحدث

    لا تتوافق الوعود إلا مع الإصدار Manifest V3 والإصدارات الأحدث، ويجب أن تستخدم المنصات الأخرى عمليات رد الاتصال.

update()

الوعد 
chrome.notifications.update(
  notificationId: string,
  options: NotificationOptions,
  callback?: function,
): Promise<boolean>

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

المعلمات

  • notificationId

    سلسلة

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

  • الخيارات

    NotificationOptions

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

  • callback

    الدالة اختيارية

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

    (wasUpdated: boolean) => void

    • wasUpdated

      قيمة منطقية

المرتجعات

  • Promise<boolean>

    الإصدار 116 من Chrome والإصدارات الأحدث

    لا تتوافق الوعود إلا مع الإصدار Manifest V3 والإصدارات الأحدث، ويجب أن تستخدم المنصات الأخرى عمليات رد الاتصال.

الفعاليات

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

      قيمة منطقية

onPermissionLevelChanged

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

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

المعلمات

  • callback

    دالة

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

    (level: PermissionLevel) => void

onShowSettings

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

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

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

المعلمات

  • callback

    دالة

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

    () => void