الفرق بين المراجعتين ل"Cordova/hooks"
جميل-بيلوني (نقاش | مساهمات) ط |
(تحديث) |
||
سطر 40: | سطر 40: | ||
| rowspan="2" |يُنفّذ قبل وبعد تصريف (compiling) تطبيقك. | | rowspan="2" |يُنفّذ قبل وبعد تصريف (compiling) تطبيقك. | ||
|- | |- | ||
− | |<code> | + | |<code>after_compile</code> |
|- | |- | ||
|<code>before_deploy</code> | |<code>before_deploy</code> | ||
سطر 75: | سطر 75: | ||
|- | |- | ||
|<code>after_clean</code> | |<code>after_clean</code> | ||
− | |||
− | |||
− | |||
− | |||
|- | |- | ||
|<code>before_plugin_add</code> | |<code>before_plugin_add</code> | ||
سطر 97: | سطر 93: | ||
|- | |- | ||
|<code>after_plugin_ls</code> | |<code>after_plugin_ls</code> | ||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
|- | |- | ||
|<code>before_plugin_install</code> | |<code>before_plugin_install</code> | ||
سطر 125: | سطر 115: | ||
<hook type="before_build" src="scripts/appBeforeBuild.js" /> | <hook type="before_build" src="scripts/appBeforeBuild.js" /> | ||
<hook type="before_plugin_install" src="scripts/appBeforePluginInstall.js" /> | <hook type="before_plugin_install" src="scripts/appBeforePluginInstall.js" /> | ||
+ | |||
<platform name="android"> | <platform name="android"> | ||
− | <hook type="before_build" src="scripts/ | + | <hook type="before_build" src="scripts/android/appAndroidBeforeBuild.bat" /> |
− | <hook type="before_build" src="scripts/ | + | <hook type="before_build" src="scripts/android/appAndroidBeforeBuild.js" /> |
− | <hook type="before_plugin_install" src="scripts/ | + | <hook type="before_plugin_install" src="scripts/android/appAndroidBeforePluginInstall.js" /> |
... | ... | ||
</platform> | </platform> | ||
+ | |||
<platform name="windows"> | <platform name="windows"> | ||
<hook type="before_build" src="scripts/windows/appWinBeforeBuild.bat" /> | <hook type="before_build" src="scripts/windows/appWinBeforeBuild.bat" /> | ||
سطر 136: | سطر 128: | ||
<hook type="before_plugin_install" src="scripts/windows/appWinBeforePluginInstall.js" /> | <hook type="before_plugin_install" src="scripts/windows/appWinBeforePluginInstall.js" /> | ||
... | ... | ||
− | </platform> | + | </platform> |
+ | </syntaxhighlight> | ||
=== الملف plugin.xml (خطافات الإضافات) === | === الملف plugin.xml (خطافات الإضافات) === | ||
سطر 142: | سطر 135: | ||
<syntaxhighlight lang="xml"><hook type="before_plugin_install" src="scripts/beforeInstall.js" /> | <syntaxhighlight lang="xml"><hook type="before_plugin_install" src="scripts/beforeInstall.js" /> | ||
<hook type="after_build" src="scripts/afterBuild.js" /> | <hook type="after_build" src="scripts/afterBuild.js" /> | ||
+ | |||
<platform name="android"> | <platform name="android"> | ||
<hook type="before_plugin_install" src="scripts/androidBeforeInstall.js" /> | <hook type="before_plugin_install" src="scripts/androidBeforeInstall.js" /> | ||
<hook type="before_build" src="scripts/androidBeforeBuild.js" /> | <hook type="before_build" src="scripts/androidBeforeBuild.js" /> | ||
... | ... | ||
− | </platform> | + | </platform> |
+ | </syntaxhighlight> | ||
− | + | ستُفعَّل خطافات الإضافات <code>before_plugin_install</code> و <code>after_plugin_install</code> و <code>before_plugin_uninstall</code> حصريًا عند تثبيت أو إلغاء تثبيت الإضافات. | |
=== عبر المجلد <code>/hooks</code> (مهمل) === | === عبر المجلد <code>/hooks</code> (مهمل) === | ||
سطر 178: | سطر 173: | ||
before_plugin_install | before_plugin_install | ||
after_plugin_install | after_plugin_install | ||
− | + | after_platform_add</syntaxhighlight> | |
===== المثال 2 (<code>cordova build</code>) ===== | ===== المثال 2 (<code>cordova build</code>) ===== | ||
سطر 187: | سطر 182: | ||
before_compile | before_compile | ||
after_compile | after_compile | ||
− | + | after_build</syntaxhighlight> | |
== واجهة البرنامج النصي (Script Interface) == | == واجهة البرنامج النصي (Script Interface) == | ||
− | |||
− | |||
− | |||
− | |||
− | |||
=== JavaScript === | === JavaScript === | ||
سطر 204: | سطر 194: | ||
يحتوي الكائن <code>context</code> على نوع الخطاف، والمسار الكامل للنص البرمجي المُنفّذ، وخيارات الخُطاف، ووسائط [[Cordova/cli|واجهة سطر الأوامر]] المُمررة إلى كوردوفا، وكائن كوردوفا عالي المستوى (top-level) وفق التنسيق التالي: | يحتوي الكائن <code>context</code> على نوع الخطاف، والمسار الكامل للنص البرمجي المُنفّذ، وخيارات الخُطاف، ووسائط [[Cordova/cli|واجهة سطر الأوامر]] المُمررة إلى كوردوفا، وكائن كوردوفا عالي المستوى (top-level) وفق التنسيق التالي: | ||
<syntaxhighlight lang="javascript">{ | <syntaxhighlight lang="javascript">{ | ||
− | + | // نوع الخطاف في طور التنفيذ | |
− | + | hook: 'before_plugin_install', | |
− | + | ||
− | + | // المسار المطلق للملف البرمجي للخطاف المُنفذ حاليا | |
− | + | scriptLocation: '/foo/scripts/appBeforePluginInstall.js', | |
− | + | ||
− | + | // أمر سطر الأوامر الذي أدى إلى الخطاف الذي يُنفذ حاليا | |
− | + | cmdLine: 'cordova plugin add plugin-withhooks', | |
− | + | ||
+ | // الخيارات المرتبطة بالعملية الحالية | ||
+ | // تنبيه: محتوى هذا الكائن يختلف بحسب العملية، وهو غير مُوثق حاليا | ||
+ | opts: { | ||
+ | projectRoot: '/foo', | ||
+ | |||
+ | cordova: { | ||
+ | platforms: ['android'], | ||
+ | plugins: ['plugin-withhooks'], | ||
+ | version: '0.21.7-dev' | ||
}, | }, | ||
− | + | ||
− | + | // معلومات حول الإضافة التي يُعمل عليها حاليا | |
− | + | // لن يُمّرّر الكائن إلا إلى البرامج النصية الخاصة بخطافات الإضافات. | |
− | + | plugin: { | |
− | + | id: 'plugin-withhooks', | |
− | + | pluginInfo: { /* ... */ }, | |
− | + | platform: 'android', | |
+ | dir: '/foo/plugins/plugin-withhooks' | ||
} | } | ||
}, | }, | ||
− | |||
− | |||
− | + | // مرجع إلى الواجهة البرمجية لكوردوفا | |
+ | cordova: { /* ... */ } | ||
+ | }</syntaxhighlight> | ||
− | يمكنك أيضًا استيراد (require) وحدات كوردوفا إضافية في برنامجك النصي باستخدام <code>context.requireCordovaModule</code> بالطريقة التالية: | + | يمكنك أيضًا استيراد (require) وحدات كوردوفا إضافية في برنامجك النصي باستخدام <code>context.requireCordovaModule</code> بالطريقة التالية: <syntaxhighlight lang="javascript">const cordovaCommon = context.requireCordovaModule('cordova-common'); |
− | <syntaxhighlight lang="javascript"> | + | </syntaxhighlight> |
− | يمكنك جعل برامجك النصية متزامنة باستخدام | + | يمكنك جعل برامجك النصية متزامنة باستخدام [[JavaScript/Promise|الوعود]] (Promises). هذا مثال ينتظر ثانية ثم يطبع عدد المللي ثواني التي مرت أثناء الانتظار: |
− | <syntaxhighlight lang="javascript">module.exports = | + | <syntaxhighlight lang="javascript">module.exports = context => { |
− | + | return new Promise(resolve => { | |
− | + | const start = Date.now(); | |
− | + | setTimeout(() => resolve(Date.now() - start), 1000); | |
− | + | }).then(msWaited => { | |
− | + | console.log(`${context.scriptLocation} waited ${msWaited} ms`); | |
− | + | }); | |
− | + | };</syntaxhighlight> | |
− | |||
'''ملاحظة''': لا تَُستخدم واجهة البرنامج النصي لمٌحمِّل الوحدة (module loader) إلا مع ملفات <code>.js</code> المعرّفة من طرف الملفين <code>config.xml</code> و <code>plugin.xml</code>. | '''ملاحظة''': لا تَُستخدم واجهة البرنامج النصي لمٌحمِّل الوحدة (module loader) إلا مع ملفات <code>.js</code> المعرّفة من طرف الملفين <code>config.xml</code> و <code>plugin.xml</code>. | ||
لأغراض التوافق، يتم تشغيل ملفات الخطاف المحددة بواسطة المجلد <code>/hooks</code> عبر الأمر <code>Node child_process spawn</code>، راجع قسم "ليست JavaScript" التالي. | لأغراض التوافق، يتم تشغيل ملفات الخطاف المحددة بواسطة المجلد <code>/hooks</code> عبر الأمر <code>Node child_process spawn</code>، راجع قسم "ليست JavaScript" التالي. | ||
− | === | + | === بغير JavaScript === |
− | + | تُشغّل البرامج النصية التي لا تستخدم [[JavaScript|JavaScript]] عبر الأمر <code>Node child_process spawn</code> من المجلد الجذري للمشروع، مع تمرير المجلد الجذري كوسيط أول. وتُمرر جميع الخيارات الأخرى إلى البرنامج النصي باستخدام متغيرات البيئة: | |
{| class="wikitable" | {| class="wikitable" | ||
سطر 271: | سطر 270: | ||
'''ملاحظة''': نوصي بشدة بأن تكتب خطافاتك باستخدام [[Node.js]]، حتى تكون عابرةً للمنصات (cross-platform)، انظر قسم JavaScript أعلاه لمزيد من التفاصيل. | '''ملاحظة''': نوصي بشدة بأن تكتب خطافاتك باستخدام [[Node.js]]، حتى تكون عابرةً للمنصات (cross-platform)، انظر قسم JavaScript أعلاه لمزيد من التفاصيل. | ||
+ | === ملاحظات خاصة بمنصة ويندوز === | ||
+ | إن كنت تعمل على ويندوز، وفي حال لم يكن ملف برنامجك النصي ([[JavaScript]] أو غيره) من النوع <code>bat</code> (وهو أمر موصى به، إن كنت تريد أن يعمل برنامجك النصي في أنظمة تشغيل أخرى غير ويندوز)، فإن [[Cordova/cli|واجهة سطر الأوامر]] ستتوقع وجود سطر shebang (سطر يبدأ بالسلسلة النصية "<code>#!</code>") كسطر أول لتعرف المترجم (interpreter) الذي يجب استخدامه لتشغيل البرنامج النصي. يجب أن يطابق سطر shebang الصيغة التالية: | ||
+ | <syntaxhighlight lang="shell">#!/usr/bin/env python | ||
+ | </syntaxhighlight> | ||
== مثال عملي == | == مثال عملي == | ||
يوضح هذا المثال كيفية استخدام خطافات كوردوفا لطباعة حجم الملف المُنشأ <code>.apk</code> لمنصة أندرويد في مخرجات وحدة التحكم (console). | يوضح هذا المثال كيفية استخدام خطافات كوردوفا لطباعة حجم الملف المُنشأ <code>.apk</code> لمنصة أندرويد في مخرجات وحدة التحكم (console). | ||
− | + | أنشئ تطبيقًا فارغًا، وأضف التعريف التالي إلى الملف <code>config.xml</code> لجعل كوردوفا تشغّل البرنامج النصي <code>afterBuild.js</code> بعد كل عملية بناء للمنصة. | |
<syntaxhighlight lang="xml"><hook type="after_build" src="scripts/afterBuild.js" /></syntaxhighlight> | <syntaxhighlight lang="xml"><hook type="after_build" src="scripts/afterBuild.js" /></syntaxhighlight> | ||
أنشئ الملف <code>scripts/afterBuild.js</code>، وأضف إليه المحتويات التالية. سنستخدم إصدارًا متزامنًا للتابع <code>fs.stat</code> لشرح كيفية استخدام ميزة التزامن بواسطة الخطافات. | أنشئ الملف <code>scripts/afterBuild.js</code>، وأضف إليه المحتويات التالية. سنستخدم إصدارًا متزامنًا للتابع <code>fs.stat</code> لشرح كيفية استخدام ميزة التزامن بواسطة الخطافات. | ||
− | <syntaxhighlight lang="javascript">module.exports = function(ctx) { | + | <syntaxhighlight lang="javascript">const fs = require('fs'); |
+ | const util = require('util'); | ||
+ | const stat = util.promisify(fs.stat); | ||
+ | |||
+ | module.exports = function(ctx) { | ||
// تأكد من أن أندرويد جزء من البناء | // تأكد من أن أندرويد جزء من البناء | ||
− | if (ctx.opts.platforms. | + | if (!ctx.opts.platforms.includes('android')) return; |
− | + | ||
− | + | const platformRoot = path.join(ctx.opts.projectRoot, 'platforms/android'); | |
− | + | const apkFileLocation = path.join(platformRoot, 'build/outputs/apk/android-debug.apk'); | |
− | + | ||
− | + | return stat(apkFileLocation).then(stats => { | |
− | + | console.log(`Size of ${apkFileLocation} is ${stats.size} bytes`); | |
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
}); | }); | ||
− | + | }; | |
− | + | </syntaxhighlight> | |
يُمرّر المعامل <code>ctx</code> في المثال أعلاه من طرف كوردوفا، حيث يعطي معلومات عن سياق التنفيذ، مثل المسار الكامل للبرنامج النصي، والمنصة المستهدفة، ووسائط [[Cordova/cli|واجهة سطر الأوامر]]، وما إلى ذلك؛ ويعرض أيضًا وظائف إضافية للمساعدة. انظر قسم واجهة البرنامج النصي أعلاه لمزيد من التفاصيل. | يُمرّر المعامل <code>ctx</code> في المثال أعلاه من طرف كوردوفا، حيث يعطي معلومات عن سياق التنفيذ، مثل المسار الكامل للبرنامج النصي، والمنصة المستهدفة، ووسائط [[Cordova/cli|واجهة سطر الأوامر]]، وما إلى ذلك؛ ويعرض أيضًا وظائف إضافية للمساعدة. انظر قسم واجهة البرنامج النصي أعلاه لمزيد من التفاصيل. | ||
سطر 306: | سطر 305: | ||
cordova build | cordova build | ||
.. | .. | ||
− | Size of path\to\app\platforms\android\build\outputs\apk\android-debug.apk is 1821193 | + | Size of path\to\app\platforms\android\build\outputs\apk\android-debug.apk is 1821193 bytes |
+ | </syntaxhighlight> | ||
يمكن العثور على المزيد من الأمثلة المفيدة في هذا المقال: [http://devgirl.org/2013/11/12/three-hooks-your-cordovaphonegap-project-needs/ ثلاث خطافات تحتاجها تطبيقات Phone Gap]. | يمكن العثور على المزيد من الأمثلة المفيدة في هذا المقال: [http://devgirl.org/2013/11/12/three-hooks-your-cordovaphonegap-project-needs/ ثلاث خطافات تحتاجها تطبيقات Phone Gap]. |
المراجعة الحالية بتاريخ 11:09، 2 ديسمبر 2020
خُطافات كوردوفا (Cordova Hooks) هي نصوصٌ برمجية خاصة يمكن إضافتها من قِبل مطوري التطبيقات والإضافات، أو حتى من طرف نظام البناء (build) الخاص بك لتخصيص أوامر كوردوفا. تسمح لك خطافات كوردوفا بالقيام بأنشطة خاصة ترافق أوامر كوردوفا. على سبيل المثال، قد تكون لديك أداة مخصصة للتحقق من تنسيق التعليمات البرمجية في ملف JavaScript خاصتك وتود تشغيل هذه الأداة قبل كل عملية بناء. في مثل هذه الحالة، يمكنك استخدام الخطاف 'before_build
' وجعل كوردوفا تشغّل هذه الأداة المخصصة وقت التشغيل، بحيث تُستدعَى قبل كل عملية بناء.
قد ترتبط الخطافات بأنشطة تطبيقك، كما هو الحال في الخطافين before_build
و after_build
وغيرهما، أو قد ترتبط بإضافات تطبيقك. على سبيل المثال، يطبَّق الخطافان before_plugin_add
و after_plugin_add
وغيرهما على الأنشطة المتعلقة بالإضافة. يمكن ربط هذه الخطافات بجميع الإضافات داخل التطبيق، أو يمكن أن تكون مخصوصة بإضافة واحدة فقط.
أنواع الخطافات
تدعم كوردوفا أنواع الخطافات التالية:
نوع الخطاف | أوامر كوردوفا المقابلة | الشرح |
---|---|---|
before_platform_add
|
cordova platform add
|
يُنفّذ هذا الخُطّاف قبل وبعد إضافة المنصة. |
after_platform_add
| ||
before_platform_rm
|
cordova platform rm
|
يُنفّذ قبل وبعد إزالة المنصة. |
after_platform_rm
| ||
before_platform_ls
|
cordova platform ls
|
يُنفّذ قبل وبعد إدراج المنصات المثبتة والمتاحة. |
after_platform_ls
| ||
before_prepare
|
cordova prepare cordova platform add cordova build cordova run
|
ينفّذ قبل وبعد تحضير (preparing) تطبيقك. |
after_prepare
| ||
before_compile
|
cordova compile cordova build
|
يُنفّذ قبل وبعد تصريف (compiling) تطبيقك. |
after_compile
| ||
before_deploy
|
cordova emulate cordova run
|
يُنفّذ قبل نشر التطبيق. |
before_build
|
cordova build
|
يُنفّذ قبل وبعد بناء التطبيق. |
after_build
| ||
before_emulate
|
cordova emulate
|
يُنفّذ قبل وبعد محاكاة التطبيق. |
after_emulate
| ||
before_run
|
cordova run
|
يُنفّذ قبل وبعد تشغيل التطبيق. |
after_run
| ||
before_serve
|
cordova serve
|
يُنفّذ قبل وبعد تخديم (serving) التطبيق. |
after_serve
| ||
before_clean
|
cordova clean
|
يُنفّذ قبل وبعد تنظيف (cleaning) التطبيق. |
after_clean
| ||
before_plugin_add
|
cordova plugin add
|
يُنفّذ قبل وبعد إضافة الإضافة. |
after_plugin_add
| ||
before_plugin_rm
|
cordova plugin rm
|
يُنفّذ قبل وبعد إزالة الإضافة. |
after_plugin_rm
| ||
before_plugin_ls
|
cordova plugin ls
|
يُنفّذ قبل وبعد عرض قائمة تضم الإضافات الموجودة في تطبيقك. |
after_plugin_ls
| ||
before_plugin_install
|
cordova plugin add
|
يُنفّذ قبل وبعد تثبيت الإضافة (على المنصات). يتم تنفيذ خطافات الإضافات في plugin.xml فقط عند إضافة الإضافات.
|
after_plugin_install
| ||
before_plugin_uninstall
|
cordova plugin rm
|
يُنفّذ قبل إلغاء تثبيت الإضافة (من المنصات). يتم تنفيذ خطافات الإضافات في plugin.xml فقط عند تثبيت إضافة.
|
طرق تعريف الخطافات
الملف Config.xml
يمكن تعريف الخطافات في الملف config.xml
الخاص بالمشروع باستخدام الوسم <hook>
.
إليك المثال التالي:
<hook type="before_build" src="scripts/appBeforeBuild.bat" />
<hook type="before_build" src="scripts/appBeforeBuild.js" />
<hook type="before_plugin_install" src="scripts/appBeforePluginInstall.js" />
<platform name="android">
<hook type="before_build" src="scripts/android/appAndroidBeforeBuild.bat" />
<hook type="before_build" src="scripts/android/appAndroidBeforeBuild.js" />
<hook type="before_plugin_install" src="scripts/android/appAndroidBeforePluginInstall.js" />
...
</platform>
<platform name="windows">
<hook type="before_build" src="scripts/windows/appWinBeforeBuild.bat" />
<hook type="before_build" src="scripts/windows/appWinBeforeBuild.js" />
<hook type="before_plugin_install" src="scripts/windows/appWinBeforePluginInstall.js" />
...
</platform>
الملف plugin.xml (خطافات الإضافات)
كمطور للإضافات، يمكنك تعريف برامج الخطافات النصية باستخدام الوسم <hook>
في الملف plugin.xml
على النحو التالي:
<hook type="before_plugin_install" src="scripts/beforeInstall.js" />
<hook type="after_build" src="scripts/afterBuild.js" />
<platform name="android">
<hook type="before_plugin_install" src="scripts/androidBeforeInstall.js" />
<hook type="before_build" src="scripts/androidBeforeBuild.js" />
...
</platform>
ستُفعَّل خطافات الإضافات before_plugin_install
و after_plugin_install
و before_plugin_uninstall
حصريًا عند تثبيت أو إلغاء تثبيت الإضافات.
عبر المجلد /hooks
(مهمل)
لتنفيذ إجراء مخصص عند إطلاق نوع الخطاف المقابل، استخدم نوع الخطاف كاسمٍ لمجلدٍ فرعي داخل المجلد 'hooks
'، وضع ملف البرنامج النصي هناك، كما هو موضح في المثال التالي:
# سينفذ ملف السكربت تلقائيًا بعد كل عملية بناء
hooks/after_build/after_build_custom_action.js
عند استخدام هذه الخطافات، سيتم تشغيلها كملفات قابلة للتنفيذ (executable)، وليس كوحدات JavaScript قابلة للتحميل.
تذكر أن تجعل برنامجك النصي قابلًا للتنفيذ في هذه الحالة.
ملاحظة: هذه الطريقة أصبحت مهملة، لذا استخدم بدلًا منها الوسم hook
في الملفين config.xml
و plugin.xml
.
ترتيب تنفيذ الخطافات
بناء على تعريف الخطاف
يمكن تعريف النصوص البرمجية (scripts) للخطافات عن طريق إضافتها إلى المجلد المحدد مسبقًا (/hooks
)، أو عبر ملفات الإعداد (config.xml
و plugin.xml
)، بحيث تُشغّل وفق الترتيب التالي:
- خطافات التطبيق الموجودة في المجلد
/hook
؛ - خطافات التطبيق من الملف
config.xml
؛ - خطافات الإضافات من الملف
plugins/.../plugin.xml
.
بناءً على الترتيب الداخلي للتنفيذ
الترتيب الداخلي لتنفيذ الخطافات ثابت.
المثال 1 (cordova platform add
)
إن كانت هناك خطافات مرتبطة مع before_platform_add
و after_platform_add
و before_prepare
و after_prepare
و before_plugin_install
و after_plugin_install
(وعلى افتراض أن لديك إضافةً واحدةً مثبتة في مشروعك)، فإن إضافة منصة جديدة سيُؤدي إلى تنفيذ الخطافات وفق الترتيب التالي:
before_platform_add
before_prepare
after_prepare
before_plugin_install
after_plugin_install
after_platform_add
المثال 2 (cordova build
)
إن كانت هناك خطافات مرتبطة مع before_prepare
و after_prepare
و before_compile
و after_compile
و before_build
و after_build
، فسيؤدي تشغيل الأمر build
إلى تنفيذ الخطافات وفق الترتيب التالي:
before_build
before_prepare
after_prepare
before_compile
after_compile
after_build
واجهة البرنامج النصي (Script Interface)
JavaScript
إن كنت تكتب الخطافات باستخدام Node.js، فيجب عليك استخدام تعريف الوحدة التالي:
module.exports = function(context) {
...
}
يحتوي الكائن context
على نوع الخطاف، والمسار الكامل للنص البرمجي المُنفّذ، وخيارات الخُطاف، ووسائط واجهة سطر الأوامر المُمررة إلى كوردوفا، وكائن كوردوفا عالي المستوى (top-level) وفق التنسيق التالي:
{
// نوع الخطاف في طور التنفيذ
hook: 'before_plugin_install',
// المسار المطلق للملف البرمجي للخطاف المُنفذ حاليا
scriptLocation: '/foo/scripts/appBeforePluginInstall.js',
// أمر سطر الأوامر الذي أدى إلى الخطاف الذي يُنفذ حاليا
cmdLine: 'cordova plugin add plugin-withhooks',
// الخيارات المرتبطة بالعملية الحالية
// تنبيه: محتوى هذا الكائن يختلف بحسب العملية، وهو غير مُوثق حاليا
opts: {
projectRoot: '/foo',
cordova: {
platforms: ['android'],
plugins: ['plugin-withhooks'],
version: '0.21.7-dev'
},
// معلومات حول الإضافة التي يُعمل عليها حاليا
// لن يُمّرّر الكائن إلا إلى البرامج النصية الخاصة بخطافات الإضافات.
plugin: {
id: 'plugin-withhooks',
pluginInfo: { /* ... */ },
platform: 'android',
dir: '/foo/plugins/plugin-withhooks'
}
},
// مرجع إلى الواجهة البرمجية لكوردوفا
cordova: { /* ... */ }
}
يمكنك أيضًا استيراد (require) وحدات كوردوفا إضافية في برنامجك النصي باستخدام context.requireCordovaModule
بالطريقة التالية:
const cordovaCommon = context.requireCordovaModule('cordova-common');
يمكنك جعل برامجك النصية متزامنة باستخدام الوعود (Promises). هذا مثال ينتظر ثانية ثم يطبع عدد المللي ثواني التي مرت أثناء الانتظار:
module.exports = context => {
return new Promise(resolve => {
const start = Date.now();
setTimeout(() => resolve(Date.now() - start), 1000);
}).then(msWaited => {
console.log(`${context.scriptLocation} waited ${msWaited} ms`);
});
};
ملاحظة: لا تَُستخدم واجهة البرنامج النصي لمٌحمِّل الوحدة (module loader) إلا مع ملفات .js
المعرّفة من طرف الملفين config.xml
و plugin.xml
.
لأغراض التوافق، يتم تشغيل ملفات الخطاف المحددة بواسطة المجلد /hooks
عبر الأمر Node child_process spawn
، راجع قسم "ليست JavaScript" التالي.
بغير JavaScript
تُشغّل البرامج النصية التي لا تستخدم JavaScript عبر الأمر Node child_process spawn
من المجلد الجذري للمشروع، مع تمرير المجلد الجذري كوسيط أول. وتُمرر جميع الخيارات الأخرى إلى البرنامج النصي باستخدام متغيرات البيئة:
اسم متغير البيئة | الشرح |
---|---|
CORDOVA_VERSION
|
إصدار واجهة سطر أوامر كوردوفا (Cordova-CLI). |
CORDOVA_PLATFORMS
|
قائمة مفصولة بفواصل تحتوي المنصات التي ينطبق عليها الأمر (مثل android, ios). |
CORDOVA_PLUGINS
|
قائمة مفصولة بفواصل لمُعرفات (IDs) الإضافات التي ينطبق عليها الأمر (مثل cordova-plugin-file-transfer, cordova-plugin-file). |
CORDOVA_HOOK
|
مسار الخُطاف الذي يتم تنفيذه. |
CORDOVA_CMDLINE
|
وسائط واجهة سطر الأوامر المُمررة إلى كوردوفا (مثل cordova run ios --emulate). |
إن أعاد البرنامج النصي قيمة مخالفة للصفر، فسيتم إنهاء الأمر الأب (parent command) لكوردوفا.
ملاحظة: نوصي بشدة بأن تكتب خطافاتك باستخدام Node.js، حتى تكون عابرةً للمنصات (cross-platform)، انظر قسم JavaScript أعلاه لمزيد من التفاصيل.
ملاحظات خاصة بمنصة ويندوز
إن كنت تعمل على ويندوز، وفي حال لم يكن ملف برنامجك النصي (JavaScript أو غيره) من النوع bat
(وهو أمر موصى به، إن كنت تريد أن يعمل برنامجك النصي في أنظمة تشغيل أخرى غير ويندوز)، فإن واجهة سطر الأوامر ستتوقع وجود سطر shebang (سطر يبدأ بالسلسلة النصية "#!
") كسطر أول لتعرف المترجم (interpreter) الذي يجب استخدامه لتشغيل البرنامج النصي. يجب أن يطابق سطر shebang الصيغة التالية:
#!/usr/bin/env python
مثال عملي
يوضح هذا المثال كيفية استخدام خطافات كوردوفا لطباعة حجم الملف المُنشأ .apk
لمنصة أندرويد في مخرجات وحدة التحكم (console).
أنشئ تطبيقًا فارغًا، وأضف التعريف التالي إلى الملف config.xml
لجعل كوردوفا تشغّل البرنامج النصي afterBuild.js
بعد كل عملية بناء للمنصة.
<hook type="after_build" src="scripts/afterBuild.js" />
أنشئ الملف scripts/afterBuild.js
، وأضف إليه المحتويات التالية. سنستخدم إصدارًا متزامنًا للتابع fs.stat
لشرح كيفية استخدام ميزة التزامن بواسطة الخطافات.
const fs = require('fs');
const util = require('util');
const stat = util.promisify(fs.stat);
module.exports = function(ctx) {
// تأكد من أن أندرويد جزء من البناء
if (!ctx.opts.platforms.includes('android')) return;
const platformRoot = path.join(ctx.opts.projectRoot, 'platforms/android');
const apkFileLocation = path.join(platformRoot, 'build/outputs/apk/android-debug.apk');
return stat(apkFileLocation).then(stats => {
console.log(`Size of ${apkFileLocation} is ${stats.size} bytes`);
});
};
يُمرّر المعامل ctx
في المثال أعلاه من طرف كوردوفا، حيث يعطي معلومات عن سياق التنفيذ، مثل المسار الكامل للبرنامج النصي، والمنصة المستهدفة، ووسائط واجهة سطر الأوامر، وما إلى ذلك؛ ويعرض أيضًا وظائف إضافية للمساعدة. انظر قسم واجهة البرنامج النصي أعلاه لمزيد من التفاصيل.
يمكنك الآن إضافة نظام أندرويد وتنفيذ عملية البناء.
cordova platform add android
..
cordova build
..
Size of path\to\app\platforms\android\build\outputs\apk\android-debug.apk is 1821193 bytes
يمكن العثور على المزيد من الأمثلة المفيدة في هذا المقال: ثلاث خطافات تحتاجها تطبيقات Phone Gap.