إضافة مربعات الحوار في كوردوفا

 توفر هذه الإضافة إمكانية الوصول إلى بعض عناصر نوافذ الحوار الأصلية عبر الكائن العام 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

navigator.notification.alert

يظهر التابع 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
• ويندوز

navigator.notification.confirm

يعرض هذا التابع مربع تأكيد (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، لا يمكن إظهار مربع حوار بأكثر من زرين.

navigator.notification.prompt

يعرض هذا التابع مربع حوار أصلي أكثر قابلية للتخصيص من دالة المتصفح 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

يطلق الجهاز صوت تنبيه (صافرة).

navigator.notification.beep(times);‎

• times: عدد مرات تكرار الصافرة. (عدد)

مثال

// Beep twice!
navigator.notification.beep(2);‎

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

• أندرويد
• Browser
• iOS
• ويندوز

ملاحظات خاصة بمنصة أندرويد

• يطلق أندرويد النغمة الافتراضية Notification ringtone المحددة في الإعداد Settings/Sound & Display.

مصادر

• صفحة cordova-plugin-dialogs في توثيق كوردوفا الرسمي.