في هذا الدرس التطبيقي، ستستخدم الميزات الأساسية لواجهة برمجة التطبيقات Notifications API لإجراء ما يلي:
- طلب الإذن بإرسال الإشعارات
- إرسال إشعارات
- تجربة خيارات الإشعارات
إعادة مزج نموذج التطبيق وعرضه في علامة تبويب جديدة
يتم تلقائيًا حظر الإشعارات من تطبيق Glitch المضمّن، لذا لن تتمكّن من معاينة التطبيق على هذه الصفحة. بدلاً من ذلك، إليك الخطوات التي يجب اتّباعها:
- انقر على Remix to Edit (إنشاء ريمكس للتعديل) ليصبح المشروع قابلاً للتعديل.
- لمعاينة الموقع الإلكتروني، اضغط على عرض التطبيق. ثم اضغط على ملء الشاشة .
من المفترض أن يتم فتح Glitch في علامة تبويب جديدة في Chrome:
أثناء العمل على هذا الدليل التعليمي حول الرموز البرمجية، يمكنك إجراء تغييرات على الرمز البرمجي في Glitch المضمّنة في هذه الصفحة. يُرجى إعادة تحميل علامة التبويب الجديدة التي تتضمّن تطبيقك المباشر للاطّلاع على التغييرات.
التعرّف على التطبيق الأوّلي ورمزه
ابدأ بالاطّلاع على التطبيق المباشر في علامة التبويب الجديدة على Chrome:
اضغط على Ctrl + Shift + J (أو Command + Option + J على نظام التشغيل Mac) لفتح DevTools. انقر على علامة التبويب وحدة التحكم.
من المفترض أن تظهر لك الرسالة التالية في وحدة التحكّم:
Notification permission is default
إذا لم تكن تعرف ما يعنيه ذلك، لا داعي للقلق، سنكشف لك كل التفاصيل قريبًا.
انقر على الزرَّين في التطبيق المنشور: طلب إذن لإرسال الإشعارات وإرسال إشعار.
تطبع وحدة التحكّم رسائل "TODO" من نموذجَين للدوالّ:
requestPermission
وsendNotification
. في ما يلي الدوالّ التي ستنفّذها في هذا الدليل التعليمي.
لنلقِ الآن نظرة على رمز نموذج التطبيق في Glitch المضمّن في هذه الصفحة.
افتح public/index.js
واطّلِع على بعض الأجزاء المهمة من الرمز الحالي:
تستخدِم الدالة
showPermission
Notifications API للحصول على حالة الأذونات الحالية للموقع الإلكتروني وتسجيلها في وحدة التحكّم:// Print current permission state to console;
// update onscreen message.
function showPermission() {
let permission = Notification.permission;
console.log('Notification permission is ' + permission);
let p = document.getElementById('permission');
p.textContent = 'Notification permission is ' + permission;
}قبل طلب الإذن، تكون حالة الإذن هي
default
. في حالة إذنdefault
، يجب أن يطلب الموقع الإلكتروني الإذن وأن يتم منحه قبل أن يتمكّن من إرسال الإشعارات.الدالة
requestPermission
هي دالة نموذجية:// Use the Notification API to request permission to send notifications.
function requestPermission() {
console.log('TODO: Implement requestPermission()');
}ستنفّذ هذه الدالة في الخطوة التالية.
الدالة
sendNotification
هي دالة نموذجية:// Use the Notification constructor to create and send a new Notification.
function sendNotification() {
console.log('TODO: Implement sendNotification()');
}ستنفّذ هذه الدالة بعد تنفيذ
requestPermission
.يُطلِق مستمع أحداث
window.onload
الدالةshowPermission
عند تحميل الصفحة، ما يعرض حالة الإذن الحالية في وحدة التحكّم وعلى الصفحة:window.onload = () => { showPermission(); };
طلب الإذن بإرسال الإشعارات
في هذه الخطوة، ستضيف وظيفة لطلب إذن المستخدم لإرسال الإشعارات.
ستستخدم الطريقة Notification.requestPermission()
لعرض نافذة منبثقة تطلب من المستخدم السماح بالإشعارات من موقعك الإلكتروني أو حظرها.
استبدِل الرمز البرمجي المخصّص للدالة
requestPermission
في public/index.js بالرمز البرمجي التالي:// Use the Notification API to request permission to send notifications.
function requestPermission() {
Notification.requestPermission()
.then((permission) => {
console.log('Promise resolved: ' + permission);
showPermission();
})
.catch((error) => {
console.log('Promise was rejected');
console.log(error);
});
}أعِد تحميل علامة التبويب في Chrome التي تعرض تطبيقك المباشر.
في واجهة التطبيق المنشور، انقر على طلب الإذن لإرسال الإشعارات. ستظهر نافذة منبثقة.
يمكن للمستخدم تقديم أحد الخيارات الثلاثة على النافذة المنبثقة للسماح.
استجابة المستخدم | حالة إذن إرسال الإشعارات |
---|---|
يختار المستخدم السماح. | granted |
يختار المستخدم حظر. | denied |
إغلاق المستخدم للنافذة المنبثقة بدون إجراء اختيار | default |
إذا نقر المستخدم على "السماح":
تم ضبط
Notification.permission
علىgranted
.سيتمكّن الموقع الإلكتروني من عرض الإشعارات.
ستؤدي المكالمات اللاحقة إلى
Notification.requestPermission
إلى إعادة التوجيه إلىgranted
بدون نافذة منبثقة.
إذا نقر المستخدم على "حظر":
تم ضبط
Notification.permission
علىdenied
.لن يتمكّن الموقع الإلكتروني من عرض الإشعارات للمستخدم.
ستؤدي المكالمات اللاحقة إلى
Notification.requestPermission
إلى إعادة التوجيه إلىdenied
بدون نافذة منبثقة.
إذا أغلق المستخدم النافذة المنبثقة:
يبقى سعر
Notification.permission
default
.ولن يتمكّن الموقع الإلكتروني من عرض الإشعارات للمستخدم.
ستؤدي المكالمات اللاحقة إلى
Notification.requestPermission
إلى ظهور المزيد من النوافذ المنبثقة.ومع ذلك، إذا استمرّ المستخدم في إغلاق النوافذ المنبثقة، قد يحظر المتصفّح الموقع الإلكتروني، ويضبط القيمة
Notification.permission
علىdenied
. ولا يمكن بعد ذلك عرض إشعارات أو نوافذ منبثقة لطلب الأذونات للمستخدم.في وقت كتابة هذه المقالة، لا يزال سلوك المتصفّح استجابةً لنوافذ الإشعارات المنبثقة التي تم رفضها بشأن أذونات الإشعارات عرضة للتغيير. وأفضل طريقة للتعامل مع هذه المشكلة هي طلب إذن الإشعارات دائمًا استجابةً لبعض التفاعلات التي بدأها المستخدم حتى يتوقعها ويعرف ما يحدث.
إرسال إشعار
في هذه الخطوة، عليك إرسال إشعار إلى المستخدم.
ستستخدم عنصر الإنشاء Notification
لإنشاء إشعار جديد ومحاولة عرضه.
إذا كانت حالة الإذن هي granted
، سيتم عرض إشعارك.
استبدِل الرمز البرمجي المخصّص للدالة
sendNotification
في index.js بالرمز البرمجي التالي:// Use the Notification constructor to create and send a new Notification.
function sendNotification() {
let title = 'Test';
let options = {
body: 'Test body',
// Other options can go here
};
console.log('Creating new notification');
let notification = new Notification(title, options);
}تأخذ الدالة الإنشائية
Notification
مَعلمتَين:title
وoptions
.options
هو عنصر يتضمّن سمات تمثّل الإعدادات المرئية والبيانات التي يمكنك تضمينها في إشعار. اطّلِع على مستندات MDN حول مَعلمات الإشعارات للحصول على مزيد من المعلومات.أعِد تحميل علامة التبويب Chrome التي تعرض تطبيقك المباشر، ثم انقر على زر إرسال إشعار. من المفترض أن يظهر إشعار يتضمّن النص
Test body
.
ماذا يحدث عند إرسال إشعارات بدون إذن؟
في هذه الخطوة، ستضيف بضعة أسطر من الرموز البرمجية التي ستتيح لك معرفة ما يحدث عند محاولة عرض إشعار بدون إذن المستخدم.
- في
public/index.js
، في نهاية الدالةsendNotification
، حدِّد معالِج الحدثonerror
للإشعار الجديد:
// Use the Notification constructor to create and send a new Notification.
function sendNotification() {
let title = 'Test';
let options = {
body: 'Test body',
// Other options can go here
};
console.log('Creating new notification');
let notification = new Notification(title, options);
notification.onerror = (event) => {
console.log('Could not send notification');
console.log(event);
};
}
لرصد خطأ في إذن إرسال الإشعارات:
انقر على رمز القفل بجانب شريط عناوين Chrome وأعِد ضبط إعدادات إذن الإشعارات للموقع الإلكتروني على الإعدادات التلقائية.
انقر على طلب الإذن لإرسال الإشعارات، واختَر هذه المرة حظر من النافذة المنبثقة.
انقر على إرسال إشعار واطّلِع على ما يحدث. يتم تسجيل نص الخطأ (
Could not send notification
) وعنصر الحدث في وحدة التحكّم.
يمكنك اختياريًا إعادة ضبط أذونات إرسال الإشعارات للموقع الإلكتروني مرة أخرى. يمكنك محاولة طلب الإذن وإغلاق النافذة المنبثقة عدة مرات لمعرفة ما سيحدث.
تجربة خيارات الإشعارات
لقد اطّلعت الآن على أساسيات كيفية طلب الإذن وإرسال الإشعارات. ولاحظت أيضًا تأثير ردود المستخدمين في قدرة تطبيقك على عرض الإشعارات.
يمكنك الآن تجربة العديد من خيارات البيانات والمرئيات المتاحة عند إنشاء إشعار. في ما يلي المجموعة الكاملة للخيارات المتاحة. (اطّلِع على مستندات الإشعارات على MDN للحصول على مزيد من المعلومات عن هذه الخيارات).
تجدر الإشارة إلى أنّ المتصفّحات والأجهزة تطبّق هذه الخيارات بشكلٍ مختلف، لذلك من المفيد اختبار إشعاراتك على أنظمة أساسية مختلفة لمعرفة شكلها.
let options = {
dir: 'auto', // Text direction
lang: 'en-US', // A language tag
badge: '/orange-cat.png', // Display when insufficient room
body: 'Hello World', // Body text
tag: 'mytag', // Tag for categorization
icon: '/line-cat.png', // To display in the notification
image: '/orange-cat.png', // To display in the notification
data: { // Arbitrary data; any data type
cheese: 'I like cheese',
pizza: 'Excellent cheese delivery mechanism',
arbitrary: {
faveNumber: 42,
myBool: true
}},
vibrate: [200, 100, 200], // Vibration pattern for hardware
renotify: false, // Notify if replaced? Default false
requireInteraction: false,// Active until click? Default false
/*
actions: // Array of NotificationActions
// Only usable with a service worker
[{
action: 'shop',
title: 'Shop!',
icon: '/bags.png'
},],
*/
}
يمكنك الاطّلاع على أداة إنشاء الإشعارات من Peter Beverloo للحصول على مزيد من الأفكار.
إذا واجهت مشكلة، إليك الرمز البرمجي المكتمل لهذا الدرس التطبيقي حول الترميز: glitch.com/edit/#!/codelab-notifications-get-started-completed
اطّلِع على الدرس التطبيقي التالي في هذه السلسلة، وهو معالجة الإشعارات باستخدام عامل خدمة، للتعرّف على مزيد من المعلومات.