chrome.notifications

refresh date: 2026-09-25 robots: noindex

الوصف

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

الأذونات

notifications

الأنواع

NotificationBitmap

NotificationButton

الخصائص

  • iconUrl

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

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

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

  • title

    سلسلة

NotificationItem

الخصائص

  • رسالة

    سلسلة

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

  • title

    سلسلة

    تمثّل هذه السمة عنوان أحد عناصر إشعار القائمة.

NotificationOptions

الخصائص

  • appIconMaskUrl

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

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

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

    تمثّل هذه السمة عنوان URL لقناع رمز التطبيق. تخضع عناوين URL للقيود نفسها التي تخضع لها iconUrl.

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

  • الأزرار

    NotificationButton[] اختياري

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

  • contextMessage

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

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

  • eventTime

    number اختياري

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

  • iconUrl

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

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

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

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

  • imageUrl

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

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

    لا تظهر الصورة لمستخدمي نظام التشغيل 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+

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

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

    boolean اختياري

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

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

  • title

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

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

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

  • النوع

    TemplateType اختياري

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

PermissionLevel

تعداد

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

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

TemplateType

تعداد

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

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

"القائمة"
تحتوي على رمز وعنوان ورسالة وعناصر وما يصل إلى زرَّين. لا يرى مستخدمو نظام التشغيل 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 والإصدارات الأحدث

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

    لا تتوفّر الوعود إلا في الإصدار 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 والإصدارات الأحدث

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

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

getAll()

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

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

المعلمات

  • callback

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

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

    (notifications: object) => void

    • الإشعارات

      عنصر

المرتجعات

  • Promise<object>

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

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

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

getPermissionLevel()

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

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

المعلمات

  • callback

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

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

    (level: PermissionLevel) => void

المرتجعات

  • Promise<PermissionLevel>

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

    تعرض هذه الطريقة Promise يتم تنفيذه مع مستوى الإذن الحالي.

    لا تتوفّر الوعود إلا في الإصدار 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 والإصدارات الأحدث

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

    لا تتوفّر الوعود إلا في الإصدار 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 فقط واجهة مستخدم ترسل هذا الحدث.

المعلمات

onShowSettings

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

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

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

المعلمات

  • callback

    دالة

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

    () => void