chrome.notifications

الوصف

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

الأذونات

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

  الرقم اختياري

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

• iconUrl

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

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

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

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

• imageUrl

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

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

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

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

• isClickable

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

  تم إيقافها منذ Chrome 67

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

• عناصر

  NotificationItem[] اختيارية

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

• رسالة

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

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

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

• الحملة

  الرقم اختياري

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

• التقدم

  الرقم اختياري

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

• requireInteraction

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

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

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

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

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

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

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

• title

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

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

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

• كتابة

  TemplateType اختيارية

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

PermissionLevel

التعداد

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

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

TemplateType

التعداد

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

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

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

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

الطُرق

clear()

وعد

chrome.notifications.clear(
  notificationId: string,
  callback?: function,
)

يؤدي هذا الإجراء إلى محو الإشعار المحدَّد.

المَعلمات

• notificationId

  سلسلة

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

• معاودة الاتصال

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

  تبدو معلَمة callback على النحو التالي:

  (wasCleared: boolean)=>void

  • wasCleared

    boolean

المرتجعات

• Promise<boolean>

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

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

create()

وعد

chrome.notifications.create(
  notificationId?: string,
  options: NotificationOptions,
  callback?: function,
)

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

المَعلمات

• notificationId

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

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

  يجب استخدام المعلَمة notificationId قبل الإصدار 42 من Chrome.

• الخيارات

  NotificationOptions

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

• معاودة الاتصال

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

  تبدو معلَمة callback على النحو التالي:

  (notificationId: string)=>void

  • notificationId

    سلسلة

المرتجعات

• وعد<string>

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

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

getAll()

وعد

chrome.notifications.getAll(
  callback?: function,
)

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

المَعلمات

• معاودة الاتصال

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

  تبدو معلَمة callback على النحو التالي:

  (notifications: object)=>void

  • الإشعارات

    كائن

المرتجعات

• Promise<object>

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

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

getPermissionLevel()

وعد

chrome.notifications.getPermissionLevel(
  callback?: function,
)

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

المَعلمات

• معاودة الاتصال

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

  تبدو معلَمة callback على النحو التالي:

  (level: PermissionLevel)=>void

  • المستوى

    PermissionLevel

المرتجعات

• Promise<PermissionLevel>

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

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

update()

وعد

chrome.notifications.update(
  notificationId: string,
  options: NotificationOptions,
  callback?: function,
)

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

المَعلمات

• notificationId

  سلسلة

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

• الخيارات

  NotificationOptions

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

• معاودة الاتصال

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

  تبدو معلَمة callback على النحو التالي:

  (wasUpdated: boolean)=>void

  • wasUpdated

    boolean

المرتجعات

• Promise<boolean>

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

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

فعاليات

onButtonClicked

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

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

المَعلمات

• معاودة الاتصال

  الوظيفة

  تبدو معلَمة callback على النحو التالي:

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

  • notificationId

    سلسلة

  • buttonIndex

    الرقم

onClicked

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

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

المَعلمات

• معاودة الاتصال

  الوظيفة

  تبدو معلَمة callback على النحو التالي:

  (notificationId: string)=>void

  • notificationId

    سلسلة

onClosed

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

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

المَعلمات

• معاودة الاتصال

  الوظيفة

  تبدو معلَمة callback على النحو التالي:

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

  • notificationId

    سلسلة

  • byUser

    boolean

onPermissionLevelChanged

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

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

المَعلمات

• معاودة الاتصال

  الوظيفة

  تبدو معلَمة callback على النحو التالي:

  (level: PermissionLevel)=>void

  • المستوى

    PermissionLevel

onShowSettings

تم إيقافه منذ إصدار Chrome 65

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

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

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

المَعلمات

• معاودة الاتصال

  الوظيفة

  تبدو معلَمة callback على النحو التالي:

  ()=>void