إضافة مربعات الحوار في كوردوفا
توفر هذه الإضافة إمكانية الوصول إلى بعض عناصر نوافذ الحوار الأصلية عبر الكائن العام navigator.notification
.
على الرغم من أن الكائن مربوط بالنطاق العام للكائن navigator
، إلا أنه غير متوفر إلا بعد إطلاق الحدث deviceready
.
document.addEventListener("deviceready", onDeviceReady, false);
function onDeviceReady() {
console.log(navigator.notification);
}
تقرير القضايا على Apache Cordova issue tracker
التثبيت
cordova plugin add cordova-plugin-dialogs
التوابع
navigator.notification.alert
navigator.notification.confirm
navigator.notification.prompt
navigator.notification.beep
يظهر التابع alert مربع حوار أو تنبيه مخصص. معظم تقديمات (implementations) كوردوفا لهذا التابع تستخدم مربع حوار أصلي لهذه الميزة، لكن بعض المنصات تستخدم دالة المتصفح alert
، والتي هي عادةً أقل قابلية للتخصيص.
navigator.notification.alert(message, alertCallback, [title], [buttonName])
- message: رسالة مربع الحوار. (سلسلة نصية)
- alertCallback: دالة استجابة (Callback) تُستدعى عند إنهاء مربع حوار التنبيه (alert dialog). (دالة)
- title: عنوان مربع الحوار. (سلسلة نصية) (اختياري، القيمة الافتراضية هي
Alert
) - buttonName: اسم الزر. (سلسلة نصية) (اختياري، القيمة الافتراضية هي
OK
)
مثال
function alertDismissed() {
// do something
}
navigator.notification.alert(
'You are the winner!', // message
alertDismissed, // callback
'Game Over', // title
'Done' // buttonName
);
المنصات المدعومة
- أندرويد
- Browser
- iOS
- ويندوز
يعرض هذا التابع مربع تأكيد (confirmation dialog box) قابل للتخصيص.
navigator.notification.confirm(message, confirmCallback, [title], [buttonLabels])
- message: رسالة مربع الحوار. (سلسلة نصية)
- confirmCallback: دالة استجابة (Callback) تُستدعى مع فهرس الزر الذي نقر عليه المستخدم (1 أو 2 أو 3) أو عند إنهاء مربع الحوار دون الضغط على أي زر (0). (دالة)
- title: عنوان مربع الحوار. (سلسلة نصية) (اختياري، القيمة الافتراضية هي
Confirm
) - buttonLabels: مصفوفة من السلاسل النصية تحدد تسميات (labels) الأزرار. (مصفوفة) (اختياري، القيمة الافتراضية هي [
OK,Cancel
])
confirmCallback
تُنفّذ دالة الاستجابة confirmCallback
عندما يضغط المستخدم على أحد الأزرار في مربع التأكيد.
تأخذ هذه الدالة الوسيط buttonIndex
(عدد)، والذي يمثل فهرس الزر المضغوط. تذكر أن الفهرسة تبدأ بالعدد واحد، وبالتالي فالقيم الممكنة هي 1
، 2
، 3
، إلخ.
مثال
function onConfirm(buttonIndex) {
alert('You selected button ' + buttonIndex);
}
navigator.notification.confirm(
'You are the winner!', // message
onConfirm, // callback to invoke with index of button pressed
'Game Over', // title
['Restart','Exit'] // buttonLabels
);
المنصات المدعومة
- أندرويد
- Browser
- iOS
- ويندوز
ملاحظات خاصة بمنصة أندرويد
- يدعم أندرويد ثلاثة أزرار كحد أقصى، ويتجاهل الأزرار الإضافية ذلك.
ملاحظات خاصة بمنصة ويندوز
- على منصتي ويندوز 8 و8.1، ليس من الممكن إضافة أكثر من ثلاثة أزرار إلى نسخة MessageDialog.
- على منصة Windows Phone 8.1، لا يمكن إظهار مربع حوار بأكثر من زرين.
يعرض هذا التابع مربع حوار أصلي أكثر قابلية للتخصيص من دالة المتصفح prompt
.
navigator.notification.prompt(message, promptCallback, [title], [buttonLabels], [defaultText])
- message: رسالة مربع الحوار. (سلسلة نصية)
- promptCallback: دالة استجابة (Callback) تُستدعى مع فهرس الزر الذي ضغط عليه المستخدم (1 أو 2 أو 3) أو عندما يتم إنهاء مربع الحوار دون الضغط على أيِّ زر (0). (دالة)
- title: عنوان مربع الحوار (سلسلة نصية) (اختياري، القيمة الافتراضية هي
Prompt
) - buttonLabels: مصفوفة من السلاسل النصية التي تحدد تسميات الأزرار (مصفوفة) (اختياري، القيمة الافتراضية هي
["OK","Cancel"]
) - defaultText: القيمة الافتراضية لمربع الإدخال textbox (
String
) (اختياري، القيمة الافتراضية: سلسلة نصية فارغة)
promptCallback
تُنفذ دالة الاستدعاء promptCallback
عندما يضغط المستخدم على أحد الأزرار في مربع الطلب (prompt dialog box). يحتوي الكائن results
الممرّر إلى دالة الاستجابة على الخاصيات التالية:
- buttonIndex: فهرس الزر المضغوط. (عدد) لاحظ أن الفهرس يبدأ من العدد واحد، وبالتالي فإن القيم الممكنة هي
1
و2
و3
، إلخ. - input1: النص المُدخل في مربع الطلب. (سلسلة نصية)
مثال
function onPrompt(results) {
alert("You selected button number " + results.buttonIndex + " and entered " + results.input1);
}
navigator.notification.prompt(
'Please enter your name', // message
onPrompt, // callback to invoke
'Registration', // title
['Ok','Exit'], // buttonLabels
'Jane Doe' // defaultText
);
المنصات المدعومة
- أندرويد
- Browser
- iOS
- ويندوز
ملاحظات خاصة بمنصة أندرويد
- يدعم أندرويد ثلاثة أزرار كحد أقصى، ويتجاهل ما زاد عن ذلك.
- في الإصدار أندرويد 3.0 وما بعده، تُعرض الأزرار بالترتيب العكسي على الأجهزة التي تستخدم القالب Holo.
ملاحظات خاصة بمنصة ويندوز
- على منصة ويندوز، يُبنى مربع الطلب بلغة html بسبب عدم وجود واجهة برمجية أصلية لهذا الغرض.
يطلق الجهاز صوت تنبيه (صافرة).
navigator.notification.beep(times);
- times: عدد مرات تكرار الصافرة. (عدد)
مثال
// Beep twice!
navigator.notification.beep(2);
المنصات المدعومة
- أندرويد
- Browser
- iOS
- ويندوز
ملاحظات خاصة بمنصة أندرويد
- يطلق أندرويد النغمة الافتراضية Notification ringtone المحددة في الإعداد Settings/Sound & Display.