عرض مصدر Cordova/cordova plugin dialogs

<noinclude>{{DISPLAYTITLE:إضافة مربعات الحوار في كوردوفا}}</noinclude>
[[تصنيف: Cordova]]
[[تصنيف: plugin]]
[[تصنيف: cordova_plugin_dialogs]]
توفر هذه الإضافة إمكانية الوصول إلى بعض مربعات الحوار الأصلية عبر الكائن العام <code>navigator.notification</code>.

على الرغم من أن هذا الكائن مربوط بالنطاق العام للكائن <code>navigator</code>، إلا أنه لن يكون متوفرًا إلا بعد إطلاق الحدث <code>[[Cordova/events#deviceready|deviceready]]</code>. 
<syntaxhighlight lang="javascript">document.addEventListener("deviceready", onDeviceReady, false);
function onDeviceReady() {
    console.log(navigator.notification);
}‎</syntaxhighlight> 

== التثبيت ==
يمكن تثبيت هذه الإضافة عبر الأمر:<syntaxhighlight lang="javascript">cordova plugin add cordova-plugin-dialogs‎</syntaxhighlight> 

== التوابع ==
===<b><code>navigator.notification.alert</code></b>=== 

يُظهر التابع <code>alert</code> مربع حوار (dialog box) أو مربع تنبيه (alert box) مخصص. معظم تقديمات (implementations) كوردوفا لهذا التابع تستخدم مربع حوار أصلي لهذه الميزة، لكن بعض المنصات تستخدم دالة المتصفح <code>alert</code>، والتي تكون عادةً أقل قابلية للتخصيص. 
<syntaxhighlight lang="javascript">navigator.notification.alert(message, alertCallback, [title], [buttonName])‎</syntaxhighlight>

==== المعاملات ====
* <code>message</code>: رسالة مربع الحوار (سلسلة نصية) 
* <code>alertCallback</code>: دالة استجابة (Callback) تُستدعى عند إنهاء مربع التنبيه (alert dialog). (دالة) 
* <code>title</code>: عنوان مربع الحوار (سلسلة نصية، اختياري، القيمة الافتراضية هي <code>Alert</code>) 
* <code>buttonName</code>: اسم الزر (سلسلة نصية، اختياري، القيمة الافتراضية هي <code>OK</code>) 
=== مثال === 
<syntaxhighlight lang="javascript">function alertDismissed() {
    // افعل شيئا ما
}
navigator.notification.alert(
    'You are the winner!',  // الرسالة
    alertDismissed,         // دالة الاستجابة
    'Game Over',            // العنوان
    'Done'                  // اسم الزر
);‎</syntaxhighlight> 
==== المنصات المدعومة ==== 
*أندرويد 
*Browser 
*iOS 
*ويندوز 

===<code>navigator.notification.confirm</code>=== 

يعرض هذا التابع مربع تأكيد (confirmation dialog box) قابل للتخصيص. 
<syntaxhighlight lang="javascript">navigator.notification.confirm(message, confirmCallback, [title], [buttonLabels])‎</syntaxhighlight>

==== المعاملات ====
* <code>message</code>: رسالة مربع الحوار (سلسلة نصية) 
* <code>confirmCallback</code>: دالة استجابة (Callback) تُستدعى مع فهرس الزر الذي ضغط عليه المستخدم (<code>1</code> أو <code>2</code> أو <code>3</code>) أو عند إنهاء مربع الحوار دون الضغط على أي زر (<code>0</code>). (دالة) 
* <code>title</code>: عنوان مربع الحوار (سلسلة نصية، اختياري، القيمة الافتراضية هي <code>Confirm</code>) 
* <code>buttonLabels</code>: مصفوفة من السلاسل النصية تحدد تسميات (labels) الأزرار. (مصفوفة، اختياري، القيمة الافتراضية هي [<code>OK,Cancel</code>]) 
====<code>confirmCallback</code>==== 

تُنفّذ دالة الاستجابة <code>confirmCallback</code> عندما يضغط المستخدم على أحد الأزرار في مربع التأكيد. 

تأخذ هذه الدالة الوسيط <code>buttonIndex</code> (عدد)، والذي يمثل فهرس الزر المضغوط (تذكر أن الفهرسة تبدأ بالعدد واحد، وبالتالي فالقيم الممكنة هي <code>1</code>، <code>2</code>، <code>3</code>، إلخ). 
==== مثال ==== 
<syntaxhighlight lang="javascript">function onConfirm(buttonIndex) {
    alert('You selected button ' + buttonIndex);
}
navigator.notification.confirm(
    'You are the winner!', // الرسالة
     onConfirm,            // دالة الاستجابة التي ستُستدعى مع فهرس الزر المضغوط
    'Game Over',           // العنوان
    ['Restart','Exit']     // اسم الزر
);‎</syntaxhighlight> 
==== المنصات المدعومة ==== 
*أندرويد 
*Browser 
*iOS 
*ويندوز 
====ملاحظات خاصة بمنصة أندرويد ==== 
* يدعم أندرويد ثلاثة أزرار كحد أقصى، ويتجاهل الأزرار الإضافية. 
==== ملاحظات خاصة بمنصة ويندوز ==== 
* على منصتي ويندوز 8 و8.1، ليس من الممكن إضافة أكثر من ثلاثة أزرار إلى نُسخة (instance‏) <code>MessageDialog</code>. 
* على منصة Windows Phone 8.1، لا يمكن إظهار مربع حوار بأكثر من زرين. 

===<code>navigator.notification.prompt</code>=== 

يعرض هذا التابع مربع حوار أصلي أكثر قابلية للتخصيص من دالة المتصفح <code>prompt</code>. 
<syntaxhighlight lang="javascript">navigator.notification.prompt(message, promptCallback, [title], [buttonLabels], [defaultText])‎</syntaxhighlight>

==== المعاملات ====
* <code>message</code>: رسالة مربع الحوار (سلسلة نصية) 
* <code>promptCallback</code>: دالة استجابة (Callback) تُستدعى مع فهرس الزر الذي ضغط عليه المستخدم (<code>1</code> أو <code>2</code> أو <code>3</code>) أو عندما يتم إنهاء مربع الحوار دون الضغط على أيِّ زر (<code>0</code>). (دالة) 
* <code>title</code>: عنوان مربع الحوار (سلسلة نصية، اختياري، القيمة الافتراضية هي <code>Prompt</code>) 
* <code>buttonLabels</code>: مصفوفة من السلاسل النصية التي تحدد تسميات الأزرار (مصفوفة، اختياري، القيمة الافتراضية هي <code>["OK","Cancel"]</code>) 
* <code>defaultText</code>: القيمة الافتراضية لمربع الإدخال textbox‏ (سلسلة نصية، اختياري، القيمة الافتراضية: <code>""</code>) 
====<code>promptCallback</code>==== 

تُنفذ دالة الاستدعاء <code>promptCallback</code> عندما يضغط المستخدم على أحد الأزرار في مربع الطلب (prompt dialog box‏). يحتوي الكائن <code>results</code> الممرّر إلى دالة الاستجابة على الخاصيات التالية: 
* <code>buttonIndex</code>: فهرس الزر المضغوط (عدد)، تذكر أن الفهرس يبدأ من العدد واحد، وبالتالي فإن القيم الممكنة هي <code>1</code> و <code>2</code> و <code>3</code>، إلخ. 
* <code>input1</code>: النص المُدخل في مربع الطلب (سلسلة نصية). 
==== مثال ==== 
<syntaxhighlight lang="javascript">function onPrompt(results) {
    alert("You selected button number " + results.buttonIndex + " and entered " + results.input1);
}
navigator.notification.prompt(
    'Please enter your name',  // الرسالة
    onPrompt,                  // دالة الاستجابة المراد استدعاؤها
    'Registration',            // العنوان 
    ['Ok','Exit'],             // اسم الزر
    'Jane Doe'                 // النص الافتراضي
);‎</syntaxhighlight> 
==== المنصات المدعومة ==== 
*أندرويد 
*Browser 
*iOS 
*ويندوز 
====ملاحظات خاصة بمنصة أندرويد ==== 
* يدعم أندرويد ثلاثة أزرار كحد أقصى، ويتجاهل ما زاد عن ذلك. 
* في الإصدار أندرويد 3.0 وما بعده، تُعرض الأزرار بالترتيب العكسي على الأجهزة التي تستخدم القالب Holo. 
==== ملاحظات خاصة بمنصة ويندوز ==== 
* على منصة ويندوز، يُبنى مُربع الطلب بلغة html بسبب عدم وجود واجهة برمجية أصلية لهذا الغرض. 

===<code>navigator.notification.beep</code>=== 

عند تنفيذ هذا التابع، يطلق الجهاز صوت تنبيه (صافرة). 
<syntaxhighlight lang="javascript">navigator.notification.beep(times);‎</syntaxhighlight>

==== المعاملات ====
* <code>times</code>: عدد مرات تكرار الصافرة (عدد). 
==== مثال ==== 
<syntaxhighlight lang="javascript">// إطلاق صافرتين
navigator.notification.beep(2);‎</syntaxhighlight> 
==== المنصات المدعومة ==== 
*أندرويد 
*Browser 
*iOS 
*ويندوز 
====ملاحظات خاصة بمنصة أندرويد ==== 
* يطلق أندرويد النغمة الافتراضية <code>Notification ringtone</code> المحددة في الإعداد <code>Settings/Sound & Display</code>.

== أنظر أيضا ==
* [[Cordova/plugins|دليل تطوير الإضافات في كوردوفا]]
* صفحة [[Cordova/events|الأحداث]].
* صفحة الإضافة [[Cordova/cordova plugin file|cordova_plugin_file]]

==مصادر==
*[https://cordova.apache.org/docs/en/latest/reference/cordova-plugin-dialogs/index.html صفحة cordova-plugin-dialogs في توثيق كوردوفا الرسمي.]