الفرق بين المراجعتين لصفحة: «Cordova/events»
أنشأ الصفحة ب'<noinclude>{{DISPLAYTITLE:الأحداث في كوردوفا}}</noinclude> تصنيف: Cordova تصنيف: events توقر كوردوفا العديد من...' |
لا ملخص تعديل |
||
سطر 1: | سطر 1: | ||
<noinclude>{{DISPLAYTITLE:الأحداث في كوردوفا}}</noinclude> | <noinclude>{{DISPLAYTITLE:الأحداث في كوردوفا}}</noinclude> | ||
[[تصنيف: Cordova]] | [[تصنيف: Cordova]] | ||
[[تصنيف: events]] | [[تصنيف: events]] | ||
توفر كوردوفا العديد من الأحداث التي يمكن استخدامها من قبل التطبيقات. فيمكن لشيفرة التطبيقات إضافة مُنصِتات (listeners) لتلك الأحداث. | |||
إليك مثالًا عن ذلك.، المثال مكون من ملفين. | |||
<syntaxhighlight lang="javascript"><!DOCTYPE html> | |||
ملف [[HTML]]:<syntaxhighlight lang="javascript"><!DOCTYPE html> | |||
<html> | <html> | ||
<head> | <head> | ||
سطر 16: | سطر 17: | ||
</html></syntaxhighlight> | </html></syntaxhighlight> | ||
ملف [[JavaScript|جافاسركيبت]]: | |||
<syntaxhighlight lang="javascript">// example.js | <syntaxhighlight lang="javascript">// example.js الملف | ||
// | // انتظار تحميل الواجهة البرمجية للجهاز | ||
// | // | ||
function onLoad() { | function onLoad() { | ||
document.addEventListener("deviceready", onDeviceReady, false); | document.addEventListener("deviceready", onDeviceReady, false); | ||
} | } | ||
// | // الواجهات البرمجية للجهاز جاهزة | ||
// | // | ||
function onDeviceReady() { | function onDeviceReady() { | ||
سطر 32: | سطر 33: | ||
} | } | ||
function onPause() { | function onPause() { | ||
// | // pause معالجة الحدث | ||
} | } | ||
function onResume() { | function onResume() { | ||
// | // resume معالجة الحدث | ||
} | } | ||
function onMenuKeyDown() { | function onMenuKeyDown() { | ||
// | // menubutton معالجة الحدث | ||
} | } | ||
// | // إضافة معالجات لأحداث أخرى</syntaxhighlight> | ||
''' | '''ملاحظة''': في العادة، يجب أن تستخدم التطبيقات التابع <code>document.addEventListener</code> لإرفاق مُنصِت (listener) بحدثٍ ما بمجرد وقوع الحدث <code>deviceready</code>. | ||
يسرد الجدول التالي أحداث كوردوفا والمنصات المدعومة: | يسرد الجدول التالي أحداث كوردوفا والمنصات المدعومة: | ||
المنصات المدعومة / | {| class="wikitable" | ||
الأحداث | !المنصات المدعومة | ||
أندرويد | /الأحداث | ||
iOS | !أندرويد | ||
!iOS | |||
!ويندوز | |||
|- | |||
| <code>deviceready</code> | |||
|نعم | |||
|نعم | |||
|نعم | |||
|- | |||
!<code>pause</code> | |||
|نعم | |||
|نعم | |||
|نعم | |||
|- | |||
| <code>resume</code> | |||
|نعم | |||
|نعم | |||
|نعم | |||
|- | |||
!<code>backbutton</code> | |||
|نعم | |||
|لا | |||
|نعم | |||
|- | |||
| <code>menubutton</code> | |||
|نعم | |||
|لا | |||
|لا | |||
|- | |||
!<code>searchbutton</code> | |||
|نعم | |||
|لا | |||
|لا | |||
|- | |||
!<code>startcallbutton</code> | |||
|لا | |||
|لا | |||
|لا | |||
|- | |||
!<code>endcallbutton</code> | |||
|لا | |||
|لا | |||
|لا | |||
|- | |||
!<code>volumedownbutton</code> | |||
|نعم | |||
|لا | |||
|لا | |||
|- | |||
!<code>volumeupbutton</code> | |||
|نعم | |||
|لا | |||
|لا | |||
|- | |||
!<code>activated</code> | |||
|لا | |||
|لا | |||
|نعم | |||
|} | |||
deviceready | == <code>deviceready</code> == | ||
يُطلق الحدث <code>deviceready</code> عند تحميل كوردوفا بالكامل. هذا الحدث ضروري لأي تطبيق. إذ يُخطِر بأنّ واجهات كوردوفا البرمجية الخاصة بالجهاز قد تم تحميلها، وأنه بالإمكان الوصول إليها. | |||
تتألف كوردوفا من شيفرتين أساسيتين: الشيفرة الأصلية (native) وشيفرة [[JavaScript|جافاسكريبت]]. أثناء تحميل الشيفرة الأصلية، يتم عرض صورة تحميل مُخصصة. من جهة أخرى، لا تُحمّل [[JavaScript|جافاسكريبت]] إلا بعد تحميل الدوم (DOM). هذا يعني أن تطبيق الويب قد يستدعي دوال [[JavaScript|جافاسكريبت]] قبل أن تصبح الشيفرة الأصلية المقابلة متاحة. | |||
يُطلق الحدث <code>deviceready</code> بمجرد تحميل كوردوفا بالكامل. وبمجرد إطلاقه، يمكنك إجراء الاستدعاءات بأمان من الواجهات البرمجية لكوردوفا. عادةً ما ترُفق التطبيقات مُنصِتًا (listener) للحدث <code>document.addEventListener</code> بمجرد تحميل الدوم (DOM) الخاص بملف HTML. | |||
يختلف سلوك الحدث <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() { | ||
// | // يمكنك الآن استخدام الواجهة البرمجية للجهاز بأمان | ||
}</syntaxhighlight> | }</syntaxhighlight> | ||
pause | == <code>pause</code> == | ||
يُطلق الحدث <code>pause</code> عندما ترسل المنصة الأصلية التطبيقَ إلى الخلفية، يحدث هذا عادةً عندما ينتقل المستخدم إلى تطبيق آخر. | |||
مثال:<syntaxhighlight lang="javascript">document.addEventListener("pause", onPause, false); | |||
<syntaxhighlight lang="javascript">document.addEventListener("pause", onPause, false); | |||
function onPause() { | function onPause() { | ||
// Handle the pause event | // Handle the pause event | ||
}</syntaxhighlight> | }</syntaxhighlight> | ||
== ملاحظات خاصة بمنصة iOS == | === ملاحظات خاصة بمنصة iOS === | ||
الحدث | في مُعالج الحدث <code>pause</code>، لا تعمل أي استدعاءات للواجهة البرمجية لكوردوفا أو الإضافات المحلية التي تمر عبر لغة Objective-C، إلى جانب أي استدعاءات تفاعلية (interactive calls)، مثل التنبيهات أو الدالة <code>console.log()</code>. إذ لنْ تُعالج إلا عند استئناف التطبيق عند التشغيل الموالي. | ||
الحدث <code>resign</code> المخصوص بنظام iOS هو بديل للحدث <code>pause</code>، ويرصد قيام المستخدمين بتمكين زر القفل <code>Lock</code> لأجل قفل الجهاز مع تشغيل التطبيق في المقدمة (foreground). إذا تم تمكين التطبيق (والجهاز) من اسخدام المهام المتعددة (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>resume</code> == | |||
يُطلق الحدث <code>resume</code> عندما تسحب المنصة الأصلية التطبيق من الخلفية. | يُطلق الحدث <code>resume</code> عندما تسحب المنصة الأصلية التطبيق من الخلفية. | ||
== مثال سريع == | == مثال سريع == |
مراجعة 15:27، 1 ديسمبر 2018
توفر كوردوفا العديد من الأحداث التي يمكن استخدامها من قبل التطبيقات. فيمكن لشيفرة التطبيقات إضافة مُنصِتات (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>
ملف جافاسركيبت:
// 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);
// Add similar listeners for other events
}
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) وشيفرة جافاسكريبت. أثناء تحميل الشيفرة الأصلية، يتم عرض صورة تحميل مُخصصة. من جهة أخرى، لا تُحمّل جافاسكريبت إلا بعد تحميل الدوم (DOM). هذا يعني أن تطبيق الويب قد يستدعي دوال جافاسكريبت قبل أن تصبح الشيفرة الأصلية المقابلة متاحة.
يُطلق الحدث 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() {
// Handle the pause event
}
ملاحظات خاصة بمنصة 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() {
// Handle the resume event
}
ملاحظات خاصة بمنصة IOS
تُنفذ الدوال التفاعلية المُستدعاة من أحد معالجات الحدث [#pause pause] في وقت لاحق عند استئناف التطبيق، والذي يُشار إليه بواسطة الحدث resume
. ويشمل هذا التنبيهات، والدالة console.log()
، وكل الاستدعاءات القادمة من الإضافات أو الواجهة البرمجية لكوردوفا، والتي تمر عبر Objective-C.
الحدث active
الحدث active
المخصوص بنظام iOS هو بديل للحدث resume
، ويرصد قيام المستخدمين بتعطيل الزر Lock لفتح (unlock) الجهاز مع تشغيل التطبيق في المقدمة. إذا تم تمكين التطبيق (والجهاز) لاستخدم المهام المتعددة، فسيُقرن هذا مع حدث resume
لاحق، ولكن فقط في المنصة iOS 5. في الواقع، تُدفع جميع التطبيقات المقفولة في منصة iOS 5 التي تم تمكين ميزة تعدد المهام بها إلى الخلفية. لكي تبقى التطبيقات قيد التشغيل عند قفلها في المنصة iOS 5، قم بتعطيل تعدد المهام في التطبيق عن طريق ضبط الخاصية UIApplicationExitsOnSuspend عند القيمة YES
. ولتشغيل التطبيق أثناء القفل على منصة iOS 4، فلا يهم هذا الإعداد.
الحدث resume
عندما يُستدعى من معالجٍ للحدث resume
، فالدوال التفاعلية مثل alert()
يجب أن تُغلّف داخل استدعاءٍ للدالة setTimeout()
، مع ضبط قيمة المهلة (timeout) عدن 0، وإلا فسيختنق التطبيق. مثلا:
document.addEventListener("resume", onResume, false);
function onResume() {
setTimeout(function() {
// TODO: do your thing!
}, 0);
}
ملاحظات خاصة بمنصة أندرويد
ارجع إلى [../../guide/platforms/android/index.html#lifecycle-guide Android Life Cycle Guide] لمزيد من التفاصيل حول خصوصيات الحدث resume
في أندرويد.
backbutton
يُطلق هذا الحدث عندما يضغط المستخدم على زر الرجوع. لتجاوز السلوك الافتراضي للزر الرجوع، فعليك تسجيل مُنصتٍ (listener) للحدث backbutton
. لم يعد ضروريًا استدعاء أي تابع آخر لتجاوز سلوك الزر الخلفي.
مثال سريع
document.addEventListener("backbutton", onBackKeyDown, false);
function onBackKeyDown() {
// Handle the back button
}
ملاحظات خاصة بمنصة ويندوز
اطلق خطأً في دالة الرد (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'); // This will suspend the app
}
}, false);
menubutton
يُطلق هذا الحدث عندما يضغط المستخدم على زر القائمة (menu button). تطبيق معالجٍ أحداث يتجاوز السلوك الافتراضي لزر القائمة.
مثال سريع
document.addEventListener("menubutton", onMenuKeyDown, false);
function onMenuKeyDown() {
// Handle the back button
}
searchbutton
يُطلق هذا الحدث عندما يضغط المستخدم على زر البحث في منصة أندرويد. إن كنت بحاجة إلى تجاوز سلوك زر البحث الافتراضي على أندرويد، فيمكنك تسجيل مُنصِت للحدث "searchbutton".
مثال سريع
document.addEventListener("searchbutton", onSearchKeyDown, false);
function onSearchKeyDown() {
// Handle the search button
}
startcallbutton
يُطلق هذا الحدث عند قيام المستخدم بالضغط على زر بدء المكالمة. إذا احتجت إلى تجاوز السلوك الافتراضي لبدء المكالمة، فيمكنك تسجيل مُنصِتٍ للحدث startcallbutton
.
مثال سريع
document.addEventListener("startcallbutton", onStartCallKeyDown, false);
function onStartCallKeyDown() {
// Handle the start call button
}
endcallbutton
يُطلق هذا الحدث عندما يضغط المستخدم على زر إنهاء المكالمة. يتجاوز هذا الحدث السلوك الافتراضي لنهاية المكالمة.
مثال سريع
document.addEventListener("endcallbutton", onEndCallKeyDown, false);
function onEndCallKeyDown() {
// Handle the end call button
}
volumedownbutton
يُطلق هذا الحدث عند قيام المستخدم بالضغط على زر خفض مستوى الصوت. إذا احتجت إلى تجاوز السلوك الافتراضي لخفض الصوت، فيمكنك تسجيل منصتٍ للحدث volumedownbutton
.
مثال سريع
document.addEventListener("volumedownbutton", onVolumeDownKeyDown, false);
function onVolumeDownKeyDown() {
// Handle the volume down button
}
volumeupbutton
يُطلق هذا الحدث عند قيام المستخدم بالضغط على زر رفع الصوت. إن كنت بحاجة إلى تجاوز سلوك رفع الصوت الافتراضي، فيمكنك تسجيل منصتٍ للحدث volumeupbutton
.
مثال سريع
document.addEventListener("volumeupbutton", onVolumeUpKeyDown, false);
function onVolumeUpKeyDown() {
// Handle the volume up button
}
activated
يُطلق هذا الحدث عند تنشيط Windows Runtime. انظر صفحة MSDN docs لمزيد من التفاصيل وأنواع التنشيط.
مثال سريع
document.addEventListener("activated", activated, false);
function activated(args) {
if (args && args.kind === Windows.ApplicationModel.Activation.ActivationKind.file) {
// Using args.raw to get the native StorageFile object
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 الداخلية.
انظر https://issues.apache.org/jira/browse/CB-10653 لمزيد من التفاصيل.
يمكن أن يُطلق الحدث activated
قبل الحدث deviceready
، لذا يجب عليك حفظ راية التنشيط (activation flag) وحفظ args داخل سياق التطبيق في حال احتجت إليها - على سبيل المثال في Share target case. ينبغي أن يحدث الاشتراك في الحدث activated
قبل معالج الحدث deviceready
(في app.bindEvents
بلغة قوالب كوردوفا).