الفرق بين المراجعتين ل"Cordova/events"

من موسوعة حسوب
اذهب إلى التنقل اذهب إلى البحث
(أنشأ الصفحة ب'<noinclude>{{DISPLAYTITLE:الأحداث في كوردوفا}}</noinclude> تصنيف: Cordova تصنيف: events توقر كوردوفا العديد من...')
 
(تحديث)
 
(5 مراجعات متوسطة بواسطة مستخدمين اثنين آخرين غير معروضة)
سطر 1: سطر 1:
 
<noinclude>{{DISPLAYTITLE:الأحداث في كوردوفا}}</noinclude>
 
<noinclude>{{DISPLAYTITLE:الأحداث في كوردوفا}}</noinclude>
−
[[تصنيف: Cordova]]
+
[[تصنيف: Cordova]]
−
[[تصنيف: events]]
+
توفر كوردوفا العديد من الأحداث التي يمكن استخدامها من قبل التطبيقات، إذ يمكن إضافة مُنصِتات (listeners) لها لتحسس وقوعها ومعالجتها.  
−
توقر كوردوفا العديد من الأحداث ليتم استخدامها من قبل التطبيقات. يمكن لشيفرة التطبيق إضافة مُنصِتات (listeners) لتلك الأحداث. مثلا:
 
  
−
'''HTML File'''
+
__TOC__
−
<syntaxhighlight lang="javascript"><!DOCTYPE html>
+
إليك المثال التالي المكون من ملفين. الملف الأول هو ملف [[HTML]] بالشكل التالي:<syntaxhighlight lang="html"><!DOCTYPE html>
 
<html>
 
<html>
 
     <head>
 
     <head>
 
     <title>Device Ready Example</title>
 
     <title>Device Ready Example</title>
 +
 
     <script type="text/javascript" charset="utf-8" src="cordova.js"></script>
 
     <script type="text/javascript" charset="utf-8" src="cordova.js"></script>
 
     <script type="text/javascript" charset="utf-8" src="example.js"></script>
 
     <script type="text/javascript" charset="utf-8" src="example.js"></script>
سطر 14: سطر 14:
 
     <body onload="onLoad()">
 
     <body onload="onLoad()">
 
     </body>
 
     </body>
−
</html>‎</syntaxhighlight>  
+
</html></syntaxhighlight>  
  
−
'''JS File'''
+
والملف الثاني هو ملف [[JavaScript]]:
−
<syntaxhighlight lang="javascript">// example.js file
+
<syntaxhighlight lang="javascript">// example.js الملف
−
// Wait for device API libraries to load
+
// انتظار تحميل الواجهة البرمجية للجهاز
 
//
 
//
 
function onLoad() {
 
function onLoad() {
 
     document.addEventListener("deviceready", onDeviceReady, false);
 
     document.addEventListener("deviceready", onDeviceReady, false);
 
}
 
}
−
// device APIs are available
+
// الواجهات البرمجية للجهاز جاهزة
 
//
 
//
 
function onDeviceReady() {
 
function onDeviceReady() {
سطر 29: سطر 29:
 
     document.addEventListener("resume", onResume, false);
 
     document.addEventListener("resume", onResume, false);
 
     document.addEventListener("menubutton", onMenuKeyDown, false);
 
     document.addEventListener("menubutton", onMenuKeyDown, false);
−
     // Add similar listeners for other events
+
     // إضافة مستمعات بشكل مشابه لبقية الأحداث
 
}
 
}
 
function onPause() {
 
function onPause() {
−
     // Handle the pause event
+
     // pause معالجة الحدث
 
}
 
}
 
function onResume() {
 
function onResume() {
−
     // Handle the resume event
+
     // resume معالجة الحدث
 
}
 
}
 
function onMenuKeyDown() {
 
function onMenuKeyDown() {
−
     // Handle the menubutton event
+
     // menubutton معالجة الحدث
 
}
 
}
−
// Add similar event handlers for other events‎</syntaxhighlight>  
+
// إضافة معالجات لأحداث أخرى</syntaxhighlight>  
  
−
'''Note''': في العادة، يجب أن تستخدم التطبيقات التابع <code>document.addEventListener</code> لإرفاق مُنصِت بحدثٍ ما بمجرد وقوع الحدث [#deviceready deviceready].  
+
'''ملاحظة''': عادةً، يجب أن تستخدم التطبيقات التابع <code>document.addEventListener</code> لإرفاق مُنصِت (listener) بحدثٍ ما بمجرد وقوع الحدث <code>deviceready</code>.  
  
 
يسرد الجدول التالي أحداث كوردوفا والمنصات المدعومة:  
 
يسرد الجدول التالي أحداث كوردوفا والمنصات المدعومة:  
−
المنصات المدعومة /
+
{| class="wikitable"
−
الأحداث
+
!المنصات المدعومة
−
أندرويد  
+
/الأحداث
−
iOS  
+
!أندرويد  
−
الويندوز
+
!iOS  
−
[#deviceready deviceready]  
+
!ويندوز
−
[#pause pause]  
+
|-
−
[#resume resume]  
+
|    <code>[[Cordova/events#deviceready|deviceready]]</code>
−
[#backbutton backbutton]  
+
|✔️
−
[#menubutton menubutton]  
+
|✔️
−
[#searchbutton searchbutton]  
+
|✔️
−
[#startcallbutton startcallbutton]  
+
|-
−
[#endcallbutton endcallbutton]  
+
|<code>[[Cordova/events#pause|pause]]</code>
−
[#volumedownbutton volumedownbutton]  
+
|✔️
−
[#volumeupbutton volumeupbutton]  
+
|✔️
−
[#activated activated]  
+
|✔️
 +
|-
 +
|        <code>[[Cordova/events#resume|resume]]</code>
 +
|✔️
 +
|✔️
 +
|✔️
 +
|-
 +
|<code>[[Cordova/events#backbutton|backbutton]]</code>
 +
|✔️
 +
|❌
 +
|✔️
 +
|-
 +
|    <code>[[Cordova/events#menubutton|menubutton]]</code>
 +
|✔️
 +
|❌
 +
|❌
 +
|-
 +
|<code>[[Cordova/events#searchbutton|searchbutton]]</code>
 +
|✔️
 +
|❌
 +
|❌
 +
|-
 +
|<code>[[Cordova/events#startcallbutton|startcallbutton]]</code>
 +
|❌
 +
|❌
 +
|❌
 +
|-
 +
|<code>[[Cordova/events#endcallbutton|endcallbutton]]</code>
 +
|❌
 +
|❌
 +
|❌
 +
|-
 +
|<code>[[Cordova/events#volumedownbutton|volumedownbutton]]</code>
 +
|✔️
 +
|❌
 +
|❌
 +
|-
 +
|<code>[[Cordova/events#volumeupbutton|volumeupbutton]]</code>
 +
|✔️
 +
|❌
 +
|❌
 +
|-
 +
|<code>[[Cordova/events#activated|activated]]</code>
 +
|❌
 +
|❌
 +
|✔️
 +
|}
  
−
deviceready  
+
== <code>deviceready</code> ==
 +
يُطلق الحدث <code>deviceready</code> عند تحميل كوردوفا بالكامل. هذا الحدث ضروري لأي تطبيق، إذ يُخطِر بأنّ واجهات كوردوفا البرمجية الخاصة بالجهاز قد تم تحميلها، وأنه بالإمكان الوصول إليها.
  
−
يُطلق حدث deviceready عند تحميل كوردوفا بالكامل. هذا الحدث ضروري لأي تطبيق. إذ يُخطِر بأنّ واجهات كوردوفا البرمجية الخاصة بالجهاز قد تم تحميلها، وأنه بالإمكان الوصول إليها.  
+
تتألف كوردوفا من شيفرتين أساسيتين: الشيفرة الأصيلة (native) وشيفرة [[JavaScript]]. أثناء تحميل الشيفرة الأصيلة، يتم عرض صورة تحميل مُخصصة. من جهة أخرى، لا تُحمّل [[JavaScript|JavaScript]] إلا بعد تحميل شجرة DOM. وهذا يعني أن تطبيق الويب قد يستدعي دوال [[JavaScript|JavaScript]] قبل أن تصبح الشيفرة الأصيلة المقابلة متاحة.  
  
−
تتألف كوردوفا من شيفرتين أساسيتين: الشيفرة الأصلية (native) وشيفرة [[JavaScript|[[Java|جافا]]اسكريبت]]. أثناء تحميل الشيفرة الأصلية، يتم عرض صورة تحميل مُخصصة. من جهة أخرى، لا تُحمّل [[JavaScript|[[Java|جافا]]اسكريبت]] إلا بعد تحميل الدوم (DOM). هذا يعني أن تطبيق الويب قد يستدعي دوال [[JavaScript|[[Java|جافا]]اسكريبت]] قبل أن تصبح الشيفرة الأصلية المقابلة متاحة.  
+
يُطلق الحدث <code>deviceready</code> بمجرد تحميل كوردوفا بالكامل. وعندها يمكنك إجراء الاستدعاءات بأمان من الواجهات البرمجية لكوردوفا. عادةً ما تُرفق التطبيقات مُنصِتًا (listener) للحدث <code>document.addEventListener</code> بمجرد تحميل DOM الخاص بملف [[HTML]].
  
−
يُطلق الحدث <code>deviceready</code> بمجرد تحميل كوردوفا بالكامل. بمجرد إطلاق الحدث، يمكنك إجراء الاستدعاءات بأمان من الواجهات البرمجية لكوردوفا. عادةً ما ترُفق التطبيقات مُنصِتًا (listener) للحدث <code>document.addEventListener</code> بمجرد تحميل الدوم (DOM) الخاص بملف HTML.
 
  
−
يختلف سلوك الحدث <code>deviceready</code> عن الأحداث الأخرى. أي معالج أحداث يتم تسجيله بعد إطلاق الحدث <code>deviceready</code> ستُسدعى دالة الرد (callback function) خاصته على الفور.  
+
 
−
== مثال سريع ==
+
يختلف سلوك الحدث <code>deviceready</code> عن الأحداث الأخرى. فأيُّ معالج أحداث (event handler) يتم تسجيله بعد إطلاق الحدث <code>deviceready</code> ستُسدعى دالة الرد (callback function) المرتبطة به على الفور. اطلع على المثال التالي: <syntaxhighlight lang="javascript">document.addEventListener("deviceready", onDeviceReady, false);
−
<syntaxhighlight lang="javascript">document.addEventListener("deviceready", onDeviceReady, false);
 
 
function onDeviceReady() {
 
function onDeviceReady() {
−
     // Now safe to use device APIs
+
     // يمكنك الآن استخدام الواجهة البرمجية للجهاز بأمان
−
}‎</syntaxhighlight>  
+
}‎</syntaxhighlight>
  
−
pause  
+
== <code>pause</code> ==
−
 
+
يُطلق الحدث <code>pause</code> عندما ترسل المنصة الأصلية التطبيقَ إلى الخلفية، يحدث هذا عادةً عندما ينتقل المستخدم إلى تطبيق آخر. <syntaxhighlight lang="javascript">document.addEventListener("pause", onPause, false);
−
يُطلق الحدث pause عند ترسل المنصة الأصلية التطبيق إلى الخلفية، يحدث هذا عادةً عندما ينتقل المستخدم إلى تطبيق آخر.  
 
−
== مثال سريع ==
 
−
<syntaxhighlight lang="javascript">document.addEventListener("pause", onPause, false);
 
 
function onPause() {
 
function onPause() {
−
     // Handle the pause event
+
     // هنا pause عالج الحدث
 
}‎</syntaxhighlight>  
 
}‎</syntaxhighlight>  
−
== ملاحظات خاصة بمنصة iOS ==  
+
=== ملاحظات خاصة بالمنصة iOS ===  
  
−
في مُعالج (handler) الحدث <code>pause</code>، لا تعمل أي استدعاءات للواجهة البرمجية لكوردوفا أو الإضافات المحلية التي تستخدم لغة Objective-C، إلى جانب أي استدعاءات تفاعلية (interactive calls)، مثل التنبيهات أو الدالة <code>console.log()</code>. إن لن تُعالج إلا عند استئناف التطبيق، عند التشغيل الموالي.  
+
في مُعالج الحدث <code>pause</code>، لا تعمل أي استدعاءات للواجهة البرمجية لكوردوفا أو الإضافات المحلية التي تمر عبر لغة Objective-C، إلى جانب الاستدعاءات التفاعلية (interactive calls)، مثل التنبيهات أو الدالة <code>console.log()‎</code>، إذ لنْ تُعالَج إلا عند استئناف التطبيق عند التشغيل التالي.  
  
−
الحدث <code>resign</code> المخصوص بنظام iOS هو بديل للحدث <code>pause</code>، ويرصد قيام المستخدمين بتمكينا الزر '''Lock''' لقفل (lock) الجهاز مع تشغيل التطبيق في المقدمة. إذا تم تمكين التطبيق (والجهاز) من اسخدام المهام المتعددة (multi-tasking)، فسيُقرن مع حدث <code>pause</code> لاحق، ولكن فقط على منصة iOS 5. في الواقع، تُدفع جميع التطبيقات المقفلة في منصة iOS 5 التي مُكِّين تعدد المهام بها إلى الخلفية. لكي تبقى التطبيقات قيد التشغيل عند قفلها في منصة iOS 5، قم بتعطيل تعدد المهام في التطبيق عن طريق ضبط الخاصية [http://developer.apple.com/library/ios/#documentation/general/Reference/InfoPlistKeyReference/Articles/iPhoneOSKeys.html UIApplicationExitsOnSuspend] عند القيمة <code>YES</code>.ولتشغيله أثناء قفله على منصة iOS 4، فهذا الإعداد لا يهم.
+
الحدث <code>resign</code> المخصوص بنظام iOS هو بديل للحدث <code>pause</code>، إذ يرصد قيام المستخدمين بتمكين زر القفل <code>Lock</code> لأجل قفل الجهاز مع تشغيل التطبيق في المقدمة (foreground). إذا تم تمكين التطبيق (والجهاز) من استخدام المهام المتعددة (multi-tasking)، فسيُقرن هذا الحدث مع حدث <code>pause</code> لاحق؛ ولكن فقط على منصة iOS 5، تُدفع جميع التطبيقات متعددة المهام المقفلة في منصة iOS 5 إلى الخلفية.
  
−
resume
+
لكي تبقى التطبيقات قيد التشغيل عند قفلها في منصة iOS 5، قم بتعطيل تعدد المهام في التطبيق عن طريق ضبط الخاصية [http://developer.apple.com/library/ios/#documentation/general/Reference/InfoPlistKeyReference/Articles/iPhoneOSKeys.html UIApplicationExitsOnSuspend] إلى القيمة <code>YES</code>. أمّا إن أردت تشغيله أثناء قفله على منصة iOS 4، فهذا الإعداد لا يهم.
  
−
يُطلق الحدث <code>resume</code> عندما تسحب المنصة الأصلية التطبيق من الخلفية.  
+
== <code>resume</code> ==
−
== مثال سريع ==
+
يُطلق الحدث <code>resume</code> عندما تسحب المنصة الأصلية التطبيق من الخلفية وتستأنف عمله. <syntaxhighlight lang="javascript">document.addEventListener("resume", onResume, false);
−
<syntaxhighlight lang="javascript">document.addEventListener("resume", onResume, false);
 
 
function onResume() {
 
function onResume() {
−
     // Handle the resume event
+
     // هنا resume عالج الحدث
 
}‎</syntaxhighlight>  
 
}‎</syntaxhighlight>  
−
== ملاحظات خاصة بمنصة IOS ==  
+
=== ملاحظات خاصة بمنصة IOS ===
−
 
 
−
تُنفذ الدوال التفاعلية المُستدعاة من أحد معالجات الحدث [#pause pause] في وقت لاحق عند استئناف التطبيق، والذي يُشار إليه بواسطة الحدث <code>resume</code>. ويشمل هذا التنبيهات، والدالة <code>console.log()</code>، وكل الاستدعاءات القادمة من الإضافات أو الواجهة البرمجية لكوردوفا، والتي تمر عبر Objective-C.
 
−
 
 
−
الحدث '''active'''
 
  
−
الحدث <code>active</code> المخصوص بنظام iOS هو بديل للحدث <code>resume</code>، ويرصد قيام المستخدمين بتعطيل الزر '''Lock''' لفتح (unlock) الجهاز مع تشغيل التطبيق في المقدمة. إذا تم تمكين التطبيق (والجهاز) لاستخدم المهام المتعددة، فسيُقرن هذا مع حدث <code>resume</code> لاحق، ولكن فقط في المنصة iOS 5. في الواقع، تُدفع جميع التطبيقات المقفولة في منصة iOS 5 التي تم تمكين ميزة تعدد المهام بها إلى الخلفية. لكي تبقى التطبيقات قيد التشغيل عند قفلها في المنصة iOS 5، قم بتعطيل تعدد المهام في التطبيق عن طريق ضبط الخاصية [http://developer.apple.com/library/ios/#documentation/general/Reference/InfoPlistKeyReference/Articles/iPhoneOSKeys.html UIApplicationExitsOnSuspend] عند القيمة <code>YES</code>. ولتشغيل التطبيق أثناء القفل على منصة iOS 4، فلا يهم هذا الإعداد.  
+
تُنفذ الدوال التفاعلية المُستدعاة من أحد معالجات الحدث <code>pause</code> في وقت لاحق عند استئناف التطبيق، والذي يُشار إليه من الحدث <code>resume</code>. ويشمل ذلك التنبيهات، والدالة <code>console.log()‎</code>، وكل الاستدعاءات القادمة من الإضافات أو الواجهة البرمجية لكوردوفا، والتي تمر عبر لغة Objective-C.
 +
* الحدث <code>active</code>''':''' الحدث <code>active</code> المخصوص بنظام iOS هو بديل للحدث <code>resume</code>، حيث يرصد قيام المستخدمين بتعطيل الزر <code>Lock</code> لأجل فتح (unlock) الجهاز مع تشغيل التطبيق في المقدمة. إذا تم تمكين التطبيق (والجهاز) من استخدام المهام المتعددة، فسيُقرن هذا مع حدث <code>resume</code> لاحق؛ ولكن فقط في المنصة iOS 5، ستُدفع جميع التطبيقات متعددة المهام المقفولة (locked) في منصة iOS 5 إلى الخلفية. إن أردت أن تبقى التطبيقات قيد التشغيل عند قفلها في المنصة iOS 5، قم بتعطيل تعدد المهام في التطبيق عن طريق ضبط الخاصية [http://developer.apple.com/library/ios/#documentation/general/Reference/InfoPlistKeyReference/Articles/iPhoneOSKeys.html UIApplicationExitsOnSuspend] إلى القيمة <code>YES</code>. أما إن أردت تشغيل التطبيق أثناء القفل على منصة iOS 4، فهذا الإعداد لا يهم.
  
−
الحدث '''resume'''  
+
* الحدث <code>resume</code>''':''' عندما يُستدعى من أحد معالجات الحدث <code>resume</code>، فالدوال التفاعلية مثل <code>alert()‎</code> يجب أن تُغلّف داخل استدعاءٍ للدالة <code>setTimeout()‎</code>، مع ضبط قيمة المهلة (timeout) إلى القيمة <code>0</code> وإلا فسيختنق التطبيق.  
−
 
+
إليك المثال التالي:<syntaxhighlight lang="javascript">document.addEventListener("resume", onResume, false);
−
عندما يُستدعى من معالجٍ للحدث <code>resume</code>، فالدوال التفاعلية مثل <code>alert()</code> يجب أن تُغلّف داخل استدعاءٍ للدالة <code>setTimeout()</code>، مع ضبط قيمة المهلة (timeout) عدن 0، وإلا فسيختنق التطبيق. مثلا:  
 
−
<syntaxhighlight lang="javascript">document.addEventListener("resume", onResume, false);
 
 
function onResume() {
 
function onResume() {
 
     setTimeout(function() {
 
     setTimeout(function() {
−
             // TODO: do your thing!
+
             // ضع ما تريد أن يحدث هنا
 
         }, 0);
 
         }, 0);
 
}‎</syntaxhighlight>  
 
}‎</syntaxhighlight>  
−
==ملاحظات خاصة بمنصة أندرويد ==  
+
===ملاحظات خاصة بمنصة أندرويد ===  
  
−
ارجع إلى [../../guide/platforms/android/index.html#lifecycle-guide Android Life Cycle Guide] لمزيد من التفاصيل حول خصوصيات الحدث <code>resume</code> في أندرويد.  
+
ارجع إلى [[Cordova/platforms android#.D8.AF.D9.84.D9.8A.D9.84 .D8.AF.D9.88.D8.B1.D8.A9 .D8.A7.D9.84.D8.AD.D9.8A.D8.A7.D8.A9|دليل دورة حياة تطبيق أندرويد]] لمزيد من التفاصيل حول بعض الملاحظات الخاصة بالحدث <code>resume</code> في أندرويد.  
  
−
backbutton  
+
== <code>backbutton</code> ==
 +
يُطلق هذا الحدث عندما يضغط المستخدم على زر الرجوع. 
  
−
يُطلق هذا الحدث عندما يضغط المستخدم على زر الرجوع. لتجاوز السلوك الافتراضي للزر الرجوع، فعليك تسجيل مُنصتٍ (listener) للحدث <code>backbutton</code>. لم يعد ضروريًا استدعاء أي تابع آخر لتجاوز سلوك الزر الخلفي.  
+
لاستبدال السلوك الافتراضي لزر الرجوع، عليك تسجيل مُنصتٍ (listener) للحدث <code>backbutton</code>. فلم يعد ضروريًا استدعاء أي تابع آخر لتبديل سلوك الزر الخلفي الافتراضي. <syntaxhighlight lang="javascript">document.addEventListener("backbutton", onBackKeyDown, false);
−
== مثال سريع ==
 
−
<syntaxhighlight lang="javascript">document.addEventListener("backbutton", onBackKeyDown, false);
 
 
function onBackKeyDown() {
 
function onBackKeyDown() {
−
     // Handle the back button
+
     // معالجة عملية الضغط على الزر الخلفي
 
}‎</syntaxhighlight>  
 
}‎</syntaxhighlight>  
−
== ملاحظات خاصة بمنصة ويندوز ==  
+
=== ملاحظات خاصة بمنصة ويندوز ===  
  
−
اطلق خطأً في دالة الرد (callback) الخاصة بالحدث <code>backbutton</code> لفرض العودة للسلوك الافتراضي، و الذي هو خروج التطبيق:  
+
إن أردت العودة للسلوك الافتراضي (و الذي هو خروج التطبيق)، فأطلق خطأً في دالة رد النداء (callback) الخاصة بالحدث <code>backbutton</code>:  
 
<syntaxhighlight lang="javascript">document.addEventListener('backbutton', function (evt) {
 
<syntaxhighlight lang="javascript">document.addEventListener('backbutton', function (evt) {
 
     if (cordova.platformId !== 'windows') {
 
     if (cordova.platformId !== 'windows') {
سطر 138: سطر 173:
 
         window.history.back();
 
         window.history.back();
 
     } else {
 
     } else {
−
         throw new Error('Exit'); // This will suspend the app
+
         throw new Error('Exit'); // هذا سيوقف التطبيق
 
     }
 
     }
−
}, false);‎</syntaxhighlight>  
+
}, false);‎</syntaxhighlight>
  
−
menubutton  
+
== <code>menubutton</code> ==
 +
يُطلق هذا الحدث عندما يضغط المستخدم على زر القائمة (menu button). 
  
−
يُطلق هذا الحدث عندما يضغط المستخدم على زر القائمة (menu button). تطبيق معالجٍ أحداث يتجاوز السلوك الافتراضي لزر القائمة.  
+
إنشاء معالجٍ أحداث (event handler) يستبدل السلوك الافتراضي لزر القائمة. إليك المثال التالي: <syntaxhighlight lang="javascript">document.addEventListener("menubutton", onMenuKeyDown, false);
−
== مثال سريع ==
 
−
<syntaxhighlight lang="javascript">document.addEventListener("menubutton", onMenuKeyDown, false);
 
 
function onMenuKeyDown() {
 
function onMenuKeyDown() {
−
     // Handle the back button
+
     // معالجة عملية الضغط على زر العودة
−
}‎</syntaxhighlight>  
+
}‎</syntaxhighlight>
  
−
searchbutton  
+
== <code>searchbutton</code> ==
−
 
+
يُطلق هذا الحدث عندما يضغط المستخدم على زر البحث في منصة أندرويد. إن كنت بحاجة إلى استبدال سلوك زر البحث الافتراضي على أندرويد، فيمكنك تسجيل مُنصِت للحدث <code>searchbutton</code>. <syntaxhighlight lang="javascript">document.addEventListener("searchbutton", onSearchKeyDown, false);
−
يُطلق هذا الحدث عندما يضغط المستخدم على زر البحث في منصة أندرويد. إن كنت بحاجة إلى تجاوز سلوك زر البحث الافتراضي على أندرويد، فيمكنك تسجيل مُنصِت للحدث "searchbutton".  
 
−
== مثال سريع ==
 
−
<syntaxhighlight lang="javascript">document.addEventListener("searchbutton", onSearchKeyDown, false);
 
 
function onSearchKeyDown() {
 
function onSearchKeyDown() {
−
     // Handle the search button
+
     // معالجة عمليةالضغط على زر البحث
−
}‎</syntaxhighlight>  
+
}‎</syntaxhighlight>
−
 
 
−
startcallbutton
 
  
−
يُطلق هذا الحدث عند قيام المستخدم بالضغط على زر بدء المكالمة. إذا احتجت إلى تجاوز السلوك الافتراضي لبدء المكالمة، فيمكنك تسجيل مُنصِتٍ للحدث <code>startcallbutton</code>.  
+
== <code>startcallbutton</code> ==
−
== مثال سريع ==
+
يُطلق هذا الحدث عند قيام المستخدم بالضغط على زر بدء المكالمة. إذا احتجت إلى استبدال السلوك الافتراضي لبدء المكالمة، فيمكنك تسجيل مُنصِتٍ للحدث <code>startcallbutton</code>. <syntaxhighlight lang="javascript">document.addEventListener("startcallbutton", onStartCallKeyDown, false);
−
<syntaxhighlight lang="javascript">document.addEventListener("startcallbutton", onStartCallKeyDown, false);
 
 
function onStartCallKeyDown() {
 
function onStartCallKeyDown() {
−
     // Handle the start call button
+
     // معالجة عملية الضغط على زر بدء مكالمة
−
}‎</syntaxhighlight>  
+
}‎</syntaxhighlight>
  
−
endcallbutton  
+
== <code>endcallbutton</code> ==
−
 
+
يُطلق هذا الحدث عندما يضغط المستخدم على زر إنهاء المكالمة. يستبدل هذا الحدث السلوك الافتراضي لعملية إنهاء المكالمة. <syntaxhighlight lang="javascript">document.addEventListener("endcallbutton", onEndCallKeyDown, false);
−
يُطلق هذا الحدث عندما يضغط المستخدم على زر إنهاء المكالمة. يتجاوز هذا الحدث السلوك الافتراضي لنهاية المكالمة.  
 
−
== مثال سريع ==
 
−
<syntaxhighlight lang="javascript">document.addEventListener("endcallbutton", onEndCallKeyDown, false);
 
 
function onEndCallKeyDown() {
 
function onEndCallKeyDown() {
−
     // Handle the end call button
+
     // معالجة عملية الضغط على زر إنهاء المكالمة
−
}‎</syntaxhighlight>  
+
}‎</syntaxhighlight>
−
 
 
−
volumedownbutton
 
  
−
يُطلق هذا الحدث عند قيام المستخدم بالضغط على زر خفض مستوى الصوت. إذا احتجت إلى تجاوز السلوك الافتراضي لخفض الصوت، فيمكنك تسجيل منصتٍ للحدث <code>volumedownbutton</code>.  
+
== <code>volumedownbutton</code> ==
−
== مثال سريع ==
+
يُطلق هذا الحدث عند قيام المستخدم بالضغط على زر خفض الصوت. إذا احتجت إلى استبدال السلوك الافتراضي لخفض الصوت، فيمكنك تسجيل منصتٍ للحدث <code>volumedownbutton</code>. <syntaxhighlight lang="javascript">document.addEventListener("volumedownbutton", onVolumeDownKeyDown, false);
−
<syntaxhighlight lang="javascript">document.addEventListener("volumedownbutton", onVolumeDownKeyDown, false);
 
 
function onVolumeDownKeyDown() {
 
function onVolumeDownKeyDown() {
−
     // Handle the volume down button
+
     // معالجة عملية الضغط على رز خفض الصوت
−
}‎</syntaxhighlight>  
+
}‎</syntaxhighlight>
  
−
volumeupbutton  
+
== <code>volumeupbutton</code> ==
−
 
+
يُطلق هذا الحدث عند قيام المستخدم بالضغط على زر رفع الصوت. إن كنت بحاجة إلى استبدال السلوك الافتراضي لرفع الصوت، فيمكنك تسجيل منصتٍ للحدث <code>volumeupbutton</code>. <syntaxhighlight lang="javascript">document.addEventListener("volumeupbutton", onVolumeUpKeyDown, false);
−
يُطلق هذا الحدث عند قيام المستخدم بالضغط على زر رفع الصوت. إن كنت بحاجة إلى تجاوز سلوك رفع الصوت الافتراضي، فيمكنك تسجيل منصتٍ للحدث <code>volumeupbutton</code>.  
 
−
== مثال سريع ==
 
−
<syntaxhighlight lang="javascript">document.addEventListener("volumeupbutton", onVolumeUpKeyDown, false);
 
 
function onVolumeUpKeyDown() {
 
function onVolumeUpKeyDown() {
−
     // Handle the volume up button
+
     // معالجة عملية الضغط على زر رفع الصوت
−
}‎</syntaxhighlight>  
+
}‎</syntaxhighlight>
  
−
activated  
+
== <code>activated</code> ==
−
 
+
يُطلق هذا الحدث عند تنشيط Windows Runtime. انظر [https://msdn.microsoft.com/en-us/library/windows/apps/br212679.aspx توثيق MSDN] لمزيد من التفاصيل وأنواع التنشيط. <syntaxhighlight lang="javascript">document.addEventListener("activated", activated, false);
−
يُطلق هذا الحدث عند تنشيط Windows Runtime. انظر صفحة [https://msdn.microsoft.com/en-us/library/windows/apps/br212679.aspx MSDN docs] لمزيد من التفاصيل وأنواع التنشيط.  
 
−
== مثال سريع ==
 
−
<syntaxhighlight lang="javascript">document.addEventListener("activated", activated, false);
 
 
function activated(args) {
 
function activated(args) {
 
     if (args && args.kind === Windows.ApplicationModel.Activation.ActivationKind.file) {
 
     if (args && args.kind === Windows.ApplicationModel.Activation.ActivationKind.file) {
−
       // Using args.raw to get the native StorageFile object
+
       // StorageFile للحصول على الكائن الأصلي args.raw استخدم
 
         Windows.Storage.FileIO.readTextAsync(args.raw.detail[0].files[0]).done(function (text) {
 
         Windows.Storage.FileIO.readTextAsync(args.raw.detail[0].files[0]).done(function (text) {
 
             console.log(text);
 
             console.log(text);
سطر 211: سطر 227:
 
     }
 
     }
 
}‎</syntaxhighlight>  
 
}‎</syntaxhighlight>  
−
== ملاحظات خاصة بمنصة ويندوز ==  
+
=== ملاحظات خاصة بمنصة ويندوز ===
−
 
+
* يمكنك الوصول إلى وسائط الحدث <code>activated</code> من الخاصية <code>args.raw.detail[0]‎</code>، إذ يمكنك استخدامها للحصول على مزيد من المعلومات حول الأنواع، أو لاستدعاء أحد توابع وسائط التنشيط.
−
يمكنك الوصول إلى وسائط الحدث activated من الخاصية <code>args.raw.detail[0]</code>، إذ يمكنك استخدامها للحصول على مزيد من المعلومات حول الأنواع، أو لاستدعاء أحد توابع وسائط التنشيط،
+
* تُنسخ أيضًا الوسائط الأصلية للحدث <code>activated</code> في <code>args.detail[0]‎</code>، إذ يمكن استخدامها احتياطًا في حالة فقدان إحدى خاصيات <code>args</code> الداخلية. انتقل إلى [https://issues.apache.org/jira/browse/CB-10653 هذه] الصفحة لمزيد من التفاصيل.
 +
* يمكن أن يُطلق الحدث <code>activated</code> قبل الحدث <code>deviceready</code>، لذا يجب عليك حفظ راية التنشيط (activation flag) وحفظ الوسائط <code>args</code> داخل سياق التطبيق في حال احتجت إليها ([https://issues.apache.org/jira/browse/CB-11924 حالة الهدف المشترك] [Share target]). ينبغي أن يحدث الاشتراك في الحدث <code>activated</code> قبل معالج الحدث <code>deviceready</code> (أو <code>app.bindEvents</code> بلغة قوالب كوردوفا).
  
−
يتم أيضًا نسخ الوسائط الأصلية للحدث activated في <code>args.detail[0]</code>، ويمكن استخدامها كاحتياط في حالة فقدان إحدى خاصيات args الداخلية.
+
== انظر أيضًا ==
−
انظر https://issues.apache.org/jira/browse/CB-10653 لمزيد من التفاصيل.  
+
* [[Cordova/hooks|الخطافات]].
 +
* [[Cordova/platforms android|منصة أندرويد]].
 +
* [[Cordova/platforms windows|منصة ويندوز]].
  
−
يمكن أن يُطلق الحدث <code>activated</code> قبل الحدث <code>deviceready</code>، لذا يجب عليك حفظ راية التنشيط (activation flag) وحفظ args داخل سياق التطبيق في حال احتجت إليها - على سبيل المثال في [https://issues.apache.org/jira/browse/CB-11924 Share target case]. ينبغي أن يحدث الاشتراك في الحدث <code>activated</code> قبل معالج الحدث <code>deviceready</code> (في <code>app.bindEvents</code> بلغة قوالب كوردوفا).
 
 
==مصادر==
 
==مصادر==
 
*[https://cordova.apache.org/docs/en/latest/cordova/events/events.html صفحة events في توثيق كوردوفا الرسمي.]
 
*[https://cordova.apache.org/docs/en/latest/cordova/events/events.html صفحة events في توثيق كوردوفا الرسمي.]

المراجعة الحالية بتاريخ 07:38، 2 ديسمبر 2020

توفر كوردوفا العديد من الأحداث التي يمكن استخدامها من قبل التطبيقات، إذ يمكن إضافة مُنصِتات (listeners) لها لتحسس وقوعها ومعالجتها.

إليك المثال التالي المكون من ملفين. الملف الأول هو ملف HTML بالشكل التالي:

<!DOCTYPE html>
<html>
    <head>
    <title>Device Ready Example</title>

    <script type="text/javascript" charset="utf-8" src="cordova.js"></script>
    <script type="text/javascript" charset="utf-8" src="example.js"></script>
    </head>
    <body onload="onLoad()">
    </body>
</html>

والملف الثاني هو ملف JavaScript: 

// example.js الملف
// انتظار تحميل الواجهة البرمجية للجهاز
//
function onLoad() {
    document.addEventListener("deviceready", onDeviceReady, false);
}
// الواجهات البرمجية للجهاز جاهزة
//
function onDeviceReady() {
    document.addEventListener("pause", onPause, false);
    document.addEventListener("resume", onResume, false);
    document.addEventListener("menubutton", onMenuKeyDown, false);
    // إضافة مستمعات بشكل مشابه لبقية الأحداث
}
function onPause() {
    //  pause معالجة الحدث
}
function onResume() {
    // resume معالجة الحدث
}
function onMenuKeyDown() {
    // menubutton معالجة الحدث
}
// إضافة معالجات لأحداث أخرى

ملاحظة: عادةً، يجب أن تستخدم التطبيقات التابع document.addEventListener لإرفاق مُنصِت (listener) بحدثٍ ما بمجرد وقوع الحدث deviceready.

يسرد الجدول التالي أحداث كوردوفا والمنصات المدعومة:

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

/الأحداث

أندرويد iOS ويندوز
deviceready ✔️ ✔️ ✔️
pause ✔️ ✔️ ✔️
resume ✔️ ✔️ ✔️
backbutton ✔️ ❌ ✔️
menubutton ✔️ ❌ ❌
searchbutton ✔️ ❌ ❌
startcallbutton ❌ ❌ ❌
endcallbutton ❌ ❌ ❌
volumedownbutton ✔️ ❌ ❌
volumeupbutton ✔️ ❌ ❌
activated ❌ ❌ ✔️

deviceready

يُطلق الحدث deviceready عند تحميل كوردوفا بالكامل. هذا الحدث ضروري لأي تطبيق، إذ يُخطِر بأنّ واجهات كوردوفا البرمجية الخاصة بالجهاز قد تم تحميلها، وأنه بالإمكان الوصول إليها.

تتألف كوردوفا من شيفرتين أساسيتين: الشيفرة الأصيلة (native) وشيفرة JavaScript. أثناء تحميل الشيفرة الأصيلة، يتم عرض صورة تحميل مُخصصة. من جهة أخرى، لا تُحمّل JavaScript إلا بعد تحميل شجرة DOM. وهذا يعني أن تطبيق الويب قد يستدعي دوال JavaScript قبل أن تصبح الشيفرة الأصيلة المقابلة متاحة.

يُطلق الحدث deviceready بمجرد تحميل كوردوفا بالكامل. وعندها يمكنك إجراء الاستدعاءات بأمان من الواجهات البرمجية لكوردوفا. عادةً ما تُرفق التطبيقات مُنصِتًا (listener) للحدث document.addEventListener بمجرد تحميل DOM الخاص بملف HTML.


يختلف سلوك الحدث deviceready عن الأحداث الأخرى. فأيُّ معالج أحداث (event handler) يتم تسجيله بعد إطلاق الحدث deviceready ستُسدعى دالة الرد (callback function) المرتبطة به على الفور. اطلع على المثال التالي: 

document.addEventListener("deviceready", onDeviceReady, false);
function onDeviceReady() {
    // يمكنك الآن استخدام الواجهة البرمجية للجهاز بأمان
}‎

pause

يُطلق الحدث pause عندما ترسل المنصة الأصلية التطبيقَ إلى الخلفية، يحدث هذا عادةً عندما ينتقل المستخدم إلى تطبيق آخر. 

document.addEventListener("pause", onPause, false);
function onPause() {
    // هنا pause عالج الحدث 
}‎

ملاحظات خاصة بالمنصة iOS

في مُعالج الحدث pause، لا تعمل أي استدعاءات للواجهة البرمجية لكوردوفا أو الإضافات المحلية التي تمر عبر لغة Objective-C، إلى جانب الاستدعاءات التفاعلية (interactive calls)، مثل التنبيهات أو الدالة console.log()‎، إذ لنْ تُعالَج إلا عند استئناف التطبيق عند التشغيل التالي.

الحدث resign المخصوص بنظام iOS هو بديل للحدث pause، إذ يرصد قيام المستخدمين بتمكين زر القفل Lock لأجل قفل الجهاز مع تشغيل التطبيق في المقدمة (foreground). إذا تم تمكين التطبيق (والجهاز) من استخدام المهام المتعددة (multi-tasking)، فسيُقرن هذا الحدث مع حدث pause لاحق؛ ولكن فقط على منصة iOS 5، تُدفع جميع التطبيقات متعددة المهام المقفلة في منصة iOS 5 إلى الخلفية.

لكي تبقى التطبيقات قيد التشغيل عند قفلها في منصة iOS 5، قم بتعطيل تعدد المهام في التطبيق عن طريق ضبط الخاصية UIApplicationExitsOnSuspend إلى القيمة YES. أمّا إن أردت تشغيله أثناء قفله على منصة iOS 4، فهذا الإعداد لا يهم.

resume

يُطلق الحدث resume عندما تسحب المنصة الأصلية التطبيق من الخلفية وتستأنف عمله. 

document.addEventListener("resume", onResume, false);
function onResume() {
    // هنا resume عالج الحدث
}‎

ملاحظات خاصة بمنصة IOS

تُنفذ الدوال التفاعلية المُستدعاة من أحد معالجات الحدث pause في وقت لاحق عند استئناف التطبيق، والذي يُشار إليه من الحدث resume. ويشمل ذلك التنبيهات، والدالة console.log()‎، وكل الاستدعاءات القادمة من الإضافات أو الواجهة البرمجية لكوردوفا، والتي تمر عبر لغة Objective-C.

  • الحدث active: الحدث active المخصوص بنظام iOS هو بديل للحدث resume، حيث يرصد قيام المستخدمين بتعطيل الزر Lock لأجل فتح (unlock) الجهاز مع تشغيل التطبيق في المقدمة. إذا تم تمكين التطبيق (والجهاز) من استخدام المهام المتعددة، فسيُقرن هذا مع حدث resume لاحق؛ ولكن فقط في المنصة iOS 5، ستُدفع جميع التطبيقات متعددة المهام المقفولة (locked) في منصة iOS 5 إلى الخلفية. إن أردت أن تبقى التطبيقات قيد التشغيل عند قفلها في المنصة iOS 5، قم بتعطيل تعدد المهام في التطبيق عن طريق ضبط الخاصية UIApplicationExitsOnSuspend إلى القيمة YES. أما إن أردت تشغيل التطبيق أثناء القفل على منصة iOS 4، فهذا الإعداد لا يهم.
  • الحدث resume: عندما يُستدعى من أحد معالجات الحدث resume، فالدوال التفاعلية مثل alert()‎ يجب أن تُغلّف داخل استدعاءٍ للدالة setTimeout()‎، مع ضبط قيمة المهلة (timeout) إلى القيمة 0 وإلا فسيختنق التطبيق.

إليك المثال التالي:

document.addEventListener("resume", onResume, false);
function onResume() {
    setTimeout(function() {
            // ضع ما تريد أن يحدث هنا
        }, 0);
}‎

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

ارجع إلى دليل دورة حياة تطبيق أندرويد لمزيد من التفاصيل حول بعض الملاحظات الخاصة بالحدث resume في أندرويد.

backbutton

يُطلق هذا الحدث عندما يضغط المستخدم على زر الرجوع.

لاستبدال السلوك الافتراضي لزر الرجوع، عليك تسجيل مُنصتٍ (listener) للحدث backbutton. فلم يعد ضروريًا استدعاء أي تابع آخر لتبديل سلوك الزر الخلفي الافتراضي. 

document.addEventListener("backbutton", onBackKeyDown, false);
function onBackKeyDown() {
    // معالجة عملية الضغط على الزر الخلفي
}‎

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

إن أردت العودة للسلوك الافتراضي (و الذي هو خروج التطبيق)، فأطلق خطأً في دالة رد النداء (callback) الخاصة بالحدث backbutton: 

document.addEventListener('backbutton', function (evt) {
    if (cordova.platformId !== 'windows') {
        return;
    }
    if (window.location.href !== firstPageUrl) {
        window.history.back();
    } else {
        throw new Error('Exit'); // هذا سيوقف التطبيق
    }
}, false);‎

menubutton

يُطلق هذا الحدث عندما يضغط المستخدم على زر القائمة (menu button).

إنشاء معالجٍ أحداث (event handler) يستبدل السلوك الافتراضي لزر القائمة. إليك المثال التالي: 

document.addEventListener("menubutton", onMenuKeyDown, false);
function onMenuKeyDown() {
    // معالجة عملية الضغط على زر العودة
}‎

searchbutton

يُطلق هذا الحدث عندما يضغط المستخدم على زر البحث في منصة أندرويد. إن كنت بحاجة إلى استبدال سلوك زر البحث الافتراضي على أندرويد، فيمكنك تسجيل مُنصِت للحدث searchbutton. 

document.addEventListener("searchbutton", onSearchKeyDown, false);
function onSearchKeyDown() {
    // معالجة عمليةالضغط على زر البحث
}‎

startcallbutton

يُطلق هذا الحدث عند قيام المستخدم بالضغط على زر بدء المكالمة. إذا احتجت إلى استبدال السلوك الافتراضي لبدء المكالمة، فيمكنك تسجيل مُنصِتٍ للحدث startcallbutton. 

document.addEventListener("startcallbutton", onStartCallKeyDown, false);
function onStartCallKeyDown() {
    // معالجة عملية الضغط على زر بدء مكالمة
}‎

endcallbutton

يُطلق هذا الحدث عندما يضغط المستخدم على زر إنهاء المكالمة. يستبدل هذا الحدث السلوك الافتراضي لعملية إنهاء المكالمة. 

document.addEventListener("endcallbutton", onEndCallKeyDown, false);
function onEndCallKeyDown() {
    // معالجة عملية الضغط على زر إنهاء المكالمة
}‎

volumedownbutton

يُطلق هذا الحدث عند قيام المستخدم بالضغط على زر خفض الصوت. إذا احتجت إلى استبدال السلوك الافتراضي لخفض الصوت، فيمكنك تسجيل منصتٍ للحدث volumedownbutton. 

document.addEventListener("volumedownbutton", onVolumeDownKeyDown, false);
function onVolumeDownKeyDown() {
    // معالجة عملية الضغط على رز خفض الصوت
}‎

volumeupbutton

يُطلق هذا الحدث عند قيام المستخدم بالضغط على زر رفع الصوت. إن كنت بحاجة إلى استبدال السلوك الافتراضي لرفع الصوت، فيمكنك تسجيل منصتٍ للحدث volumeupbutton. 

document.addEventListener("volumeupbutton", onVolumeUpKeyDown, false);
function onVolumeUpKeyDown() {
    // معالجة عملية الضغط على زر رفع الصوت
}‎

activated

يُطلق هذا الحدث عند تنشيط Windows Runtime. انظر توثيق MSDN لمزيد من التفاصيل وأنواع التنشيط. 

document.addEventListener("activated", activated, false);
function activated(args) {
    if (args && args.kind === Windows.ApplicationModel.Activation.ActivationKind.file) {
       // StorageFile للحصول على الكائن الأصلي args.raw استخدم
        Windows.Storage.FileIO.readTextAsync(args.raw.detail[0].files[0]).done(function (text) {
            console.log(text);
        }, function (err) {
            console.error(err);
        });
    }
}‎

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

  • يمكنك الوصول إلى وسائط الحدث activated من الخاصية args.raw.detail[0]‎، إذ يمكنك استخدامها للحصول على مزيد من المعلومات حول الأنواع، أو لاستدعاء أحد توابع وسائط التنشيط.
  • تُنسخ أيضًا الوسائط الأصلية للحدث activated في args.detail[0]‎، إذ يمكن استخدامها احتياطًا في حالة فقدان إحدى خاصيات args الداخلية. انتقل إلى هذه الصفحة لمزيد من التفاصيل.
  • يمكن أن يُطلق الحدث activated قبل الحدث deviceready، لذا يجب عليك حفظ راية التنشيط (activation flag) وحفظ الوسائط args داخل سياق التطبيق في حال احتجت إليها (حالة الهدف المشترك [Share target]). ينبغي أن يحدث الاشتراك في الحدث activated قبل معالج الحدث deviceready (أو app.bindEvents بلغة قوالب كوردوفا).

انظر أيضًا

مصادر

مجلوبة من "https://wiki.hsoub.com/index.php?title=Cordova/events&oldid=29908"