الفرق بين المراجعتين ل"Cordova/plugins"
سطر 2: | سطر 2: | ||
[[تصنيف: Cordova]] | [[تصنيف: Cordova]] | ||
[[تصنيف: plugins]] | [[تصنيف: plugins]] | ||
− | "'''الإضافة'''" عبارة عن حزمة من الأكواد البرمجية التي تسمح [[Cordova/webviews|لمعرض كوردوفا]] (Cordova webview) الذي يُعرض التطبيق من خلاله التواصل مع المنصة الأصلية (native platform) التي يعمل عليها. | + | "'''الإضافة'''" عبارة عن حزمة من الأكواد البرمجية التي تسمح [[Cordova/webviews|لمعرض كوردوفا]] (Cordova webview) الذي يُعرض التطبيق من خلاله التواصل مع المنصة الأصلية (native platform) التي يعمل عليها. توفر الإضافات إمكانية الوصول إلى وظائف الجهاز والمنصة غير المتوفرة عادةً للتطبيقات الشبكية (web-based apps). كل ميزات واجهة Cordova البرمجية (Cordova API) الرئيسية تُقدم كإضافات، فضلًا عن العديد من الإضافات الأخرى التي تتيح ميزات مثل ماسحات الرموز الشريطية (bar code scanners) أو اتصالات NFC، أو إضافات لتصميم واجهات التقويم الزمني. يمكنك البحث عن الإضافات المتوفرة على [https://cordova.apache.org/plugins/ صفحة البحث عن الإضافات]. |
− | |||
− | توفر الإضافات إمكانية الوصول إلى وظائف الجهاز والمنصة غير المتوفرة عادةً للتطبيقات الشبكية (web-based apps). كل ميزات واجهة Cordova البرمجية (Cordova API) الرئيسية تُقدم كإضافات، فضلًا عن العديد من الإضافات الأخرى التي تتيح ميزات مثل ماسحات الرموز الشريطية (bar code scanners) أو اتصالات NFC، أو إضافات لتصميم واجهات التقويم الزمني. يمكنك البحث عن الإضافات المتوفرة على [https://cordova.apache.org/plugins/ صفحة البحث عن الإضافات]. | ||
تشتمل الإضافات على واجهة [[JavaScript]] واحدة إلى جانب المكتبات الأصلية (native code libraries) المقابلة لكل منصة مدعومة. الهدف هو حجب الأكواد الأصلية (native code) وراء واجهة [[JavaScript]] مشتركة. | تشتمل الإضافات على واجهة [[JavaScript]] واحدة إلى جانب المكتبات الأصلية (native code libraries) المقابلة لكل منصة مدعومة. الهدف هو حجب الأكواد الأصلية (native code) وراء واجهة [[JavaScript]] مشتركة. | ||
سطر 32: | سطر 30: | ||
</platform> | </platform> | ||
</plugin></syntaxhighlight>لتحديد حزمة الإضافة، تستخدم الخاصية <code>id</code> الموجودة في الوسم <code>plugin</code> نفس تنسيق النطاق العكسي (reverse domain format) الذي تستخدمه التطبيقات التي ستُضاف إليها. يحدد الوسم <code>js-module</code> مسار واجهة [[JavaScript|جافاسكريبت]] المشتركة. كما يحدد الوسم <code>platform</code> الشيفرة الأصلية المقابلة (لمنصة <code>ios</code> في هذه الحالة). يغلّف (encapsulates) الوسمُ <code>config-file</code> وسمًا <code>feature</code> الذي تم إدخاله في ملف <code>config.xml</code> الخاص بالمنصة، لتنبيه المنصة بالمكتبة الإضافية. يحدد الوسمان <code>header-file</code> و <code>source-file</code> مسار ملفات المكتبة. | </plugin></syntaxhighlight>لتحديد حزمة الإضافة، تستخدم الخاصية <code>id</code> الموجودة في الوسم <code>plugin</code> نفس تنسيق النطاق العكسي (reverse domain format) الذي تستخدمه التطبيقات التي ستُضاف إليها. يحدد الوسم <code>js-module</code> مسار واجهة [[JavaScript|جافاسكريبت]] المشتركة. كما يحدد الوسم <code>platform</code> الشيفرة الأصلية المقابلة (لمنصة <code>ios</code> في هذه الحالة). يغلّف (encapsulates) الوسمُ <code>config-file</code> وسمًا <code>feature</code> الذي تم إدخاله في ملف <code>config.xml</code> الخاص بالمنصة، لتنبيه المنصة بالمكتبة الإضافية. يحدد الوسمان <code>header-file</code> و <code>source-file</code> مسار ملفات المكتبة. | ||
− | ==التحقق من صحة الإضافة باستخدام Plugman== | + | ==التحقق من صحة الإضافة باستخدام <code>Plugman</code>== |
− | يمكنك استخدام | + | يمكنك استخدام <code>[[Cordova/plugman|plugman]]</code> للتحقق مما إذا كانت الإضافة ستُثبت بشكل صحيح في كل المنصات. قم بتثبيت [[Cordova/plugman|<code>plugman</code>]] باستخدام تعليمة [http://nodejs.org/ node] التالية:<syntaxhighlight lang="console">npm install -g plugman</syntaxhighlight>تحتاج إلى مجلد مصدري (source directory) صالح للتطبيق، مثل المجلد الجذري <code>www</code> المضمّن في المشروع الافتراضي المُنشأ عبر [[Cordova/cli|واجهة سطر الأوامر]]، كما هو موضح في صفحة [https://cordova.apache.org/docs/en/latest/guide/cli/index.html أنشئ تطبيقك الأول]. |
− | ثم قم بإجراء | + | ثم قم بإجراء الأمر التالي لاختبار ما إذا كانت ارتباطات (dependencies) منصة iOS تُحمّل بالشكل المطلوب:<syntaxhighlight lang="console">plugman install --platform ios --project /path/to/my/project/www --plugin /path/to/my/plugin</syntaxhighlight>لمزيد من المعلومات حول كيفية تصحيح (''debug'') الإضافات، راجع صفحات واجهات المنصات الأصلية (platform's native interface) في أسفل هذه الصفحة. |
==واجهة JavaScript== | ==واجهة JavaScript== | ||
− | توفر واجهة [[JavaScript]] الواجهة الأمامية، | + | توفر واجهة [[JavaScript]] الواجهة الأمامية، ما يجعلها على الأرجح أهم جزء في الإضافة. يمكنك بناء شيفرة [[JavaScript]] الخاصة بالإضافة بالطريقة التي تحب، ولكنك ستحتاج إلى استدعاء <code>cordova.exec</code> للتواصل مع المنصة الأصلية باستخدام الصياغة التالي:<syntaxhighlight lang="javascript">cordova.exec(function(winParam) {}, |
function(error) {}, | function(error) {}, | ||
"service", | "service", | ||
سطر 43: | سطر 41: | ||
["firstArgument", "secondArgument", 42, false]);</syntaxhighlight> | ["firstArgument", "secondArgument", 42, false]);</syntaxhighlight> | ||
===المعاملات=== | ===المعاملات=== | ||
− | <code>function(winParam) {}</code> | + | <code>function(winParam) {}</code> |
− | <code> | + | دالة النجاح (success callback function). بافتراض أن استدعاء <code>exec</code> مر بنجاح، فستنُفذ هذه الدالة مع الوسائط التي مررتها إليها. |
− | <code> | + | <code>function(error) {}</code> |
− | + | دالة الخطأ (error callback function). إذا لم تكتمل العملية بنجاح، ستنفذ هذه الدالة مع وسيط اختياري. | |
− | <code>[/* arguments */]</code> | + | <code>"service"</code> |
− | ==مثال | + | |
− | يوضح هذا المثال إحدى الطرق الممكنة لتقديم واجهة [[JavaScript]] الخاصة بالإضافة:<syntaxhighlight>window.echo = function(str, callback) { | + | اسم الخدمة المراد استدعاؤها في المنصة الأصلية. يتوافق مع صنف أصلي، والذي ستجد معلومات أكثر تفصيلا عنه في الأدلة الأصلية المذكورة أدناه. |
+ | |||
+ | <code>"action"</code> | ||
+ | |||
+ | اسم الإجراء (action) المراد استدعاؤه في المنصة الأصلية. هذا يتوافق عمومًا مع تابع الصنف الأصلي. راجع الأدلة الأصلية المدرجة أدناه. | ||
+ | |||
+ | <code>[/* arguments */]</code> | ||
+ | |||
+ | مصفوفة من الوسائط لأجل تمريرها إلى البيئة الأصلية. | ||
+ | ==مثال JavaScript== | ||
+ | يوضح هذا المثال إحدى الطرق الممكنة لتقديم واجهة [[JavaScript]] الخاصة بالإضافة:<syntaxhighlight lang="javascript">window.echo = function(str, callback) { | ||
cordova.exec(callback, function(err) { | cordova.exec(callback, function(err) { | ||
callback('Nothing to echo.'); | callback('Nothing to echo.'); | ||
}, "Echo", "echo", [str]); | }, "Echo", "echo", [str]); | ||
− | };</syntaxhighlight>في هذا المثال، تربط الإضافة نفسها بالكائن <code>window</code> | + | };</syntaxhighlight>في هذا المثال، تربط الإضافة نفسها بالكائن <code>window</code> باعتبارها الدالة <code>echo</code>، والتي سيستدعيها مستخدموا الإضافة على النحو التالي:<syntaxhighlight lang="javascript">window.echo("echome", function(echoValue) { |
alert(echoValue == "echome"); // should alert true. | alert(echoValue == "echome"); // should alert true. | ||
− | });</syntaxhighlight>انظر إلى الوسائط الثلاثة الأخيرة المُمررة إلى الدالة <code>cordova.exec</code>. يستدعي الأول الخدمة <code>Echo</code>، والتي هي اسم صنف. ويطلب الثاني الإجراء <code>echo</code>، والذي هو تابعٌ داخل ذلك الصنف. أما الثالث فهو مصفوفة من الوسائط التي تحتوي السلسلة النصية المعادة، | + | });</syntaxhighlight>انظر إلى الوسائط الثلاثة الأخيرة المُمررة إلى الدالة <code>cordova.exec</code>. يستدعي الأول الخدمة <code>Echo</code>، والتي هي اسم صنف. ويطلب الثاني الإجراء <code>echo</code>، والذي هو تابعٌ داخل ذلك الصنف. أما الثالث فهو مصفوفة من الوسائط التي تحتوي السلسلة النصية المعادة، والتي هي الوسيط الأول للدالة <code>window.echo</code>. |
− | دالة النجاح (success callback) المُمررة | + | دالة النجاح (success callback) المُمررة إلى <code>exec</code> هي مرجعٌ إلى دالة الاستدعاء (callback function) الخاصة بـ <code>window.echo</code>. إذا أطلقت المنصة الأصلية دالة الخطأ (error callback)، فسيستدعي ببساطة دالة النجاح، ويمرر إليها السلسلة النصية الافتراضية. |
==الواجهات الأصلية (Native Interfaces)== | ==الواجهات الأصلية (Native Interfaces)== | ||
− | بمجرد | + | بمجرد إنهاء أكواد [[JavaScript]] للإضافة خاصتك، فسيكون عليك تكميلها بتقديم أصلي (native implementation) واحد على الأقل. يمكنك إيجاد تفاصيل كل منصة أدناه، وكلها تُبنى على مثال الإضافة <code>Echo</code> أعلاه: |
+ | * [[Cordova/plugins android|إضافات أندرويد]] | ||
+ | * [[Cordova/plugins ios|إضافات iOS]] | ||
+ | * [[plugins windows|إضافات ويندوز]] | ||
+ | |||
==نشر الإضافات== | ==نشر الإضافات== | ||
− | يمكنك نشر إضافتك | + | يمكنك نشر إضافتك في سجل قائم على مدير حُزم جافاسكريبت (<code>npmjs</code>-based registry)، لكن يوصى باستخدام [https://www.npmjs.com/ npm registry]. يمكن للمطورين الآخرين تثبيت إضافتك تلقائيا باستخدام إما [[Cordova/plugman|<code>plugman</code>]] أو [[Cordova/cli|واجهة سطر الأوامر]] (CLI). |
لنشر الإضافة على مدير الحُزم npm، يلزمك اتباع الخطوات التالية: | لنشر الإضافة على مدير الحُزم npm، يلزمك اتباع الخطوات التالية: | ||
− | قم بتثبيت <code>plugman</code>:<syntaxhighlight>$ npm install -g plugman</syntaxhighlight>قم بإنشاء ملف <code>package.json</code> للإضافة خاصتك:<syntaxhighlight>$ plugman createpackagejson /path/to/your/plugin</syntaxhighlight> | + | قم بتثبيت [[Cordova/plugman|<code>plugman</code>]]:<syntaxhighlight lang="console">$ npm install -g plugman</syntaxhighlight>قم بإنشاء ملف <code>package.json</code> للإضافة خاصتك:<syntaxhighlight lang="console">$ plugman createpackagejson /path/to/your/plugin</syntaxhighlight>انشرها:<syntaxhighlight lang="console">$ npm adduser # that is if you don't have an account yet |
− | + | $ npm publish /path/to/your/plugin</syntaxhighlight>لمزيد من التفاصيل حول استخدام npm، راجع صفحة [https://docs.npmjs.com/getting-started/publishing-npm-packages نشر حزم npm]. | |
− | انشرها:<syntaxhighlight>$ npm adduser # that is if you don't have an account yet | ||
− | $ npm publish /path/to/your/plugin</syntaxhighlight>لمزيد من التفاصيل حول استخدام npm، راجع | ||
==دمج الإضافة في خاصية البحث عن الإضافات== | ==دمج الإضافة في خاصية البحث عن الإضافات== | ||
− | لإظهار الإضافة في صفحة [/plugins/ | + | لإظهار الإضافة في صفحة [https://cordova.apache.org/plugins/ البحث عن الإضافات]، أضف الكلمة المفتاحية <code>ecosystem:cordova</code> إلى ملف <code>package.json</code> الخاص بالإضافة قبل نشرها. |
− | للإشارة إلى أنّ الإضافة تدعم منصة معينة، أضف كلمة رئيسية وفق الصيغة <code>**cordova-<platformName>**</code> إلى قائمة الكلمات الرئيسية في package.json. تقوم التعليمة <code>createpackagejson</code> الخاصة ب [[Cordova/plugman|plugman]] بعمل ذلك نيابة عنك، ولكن | + | للإشارة إلى أنّ الإضافة تدعم منصة معينة، أضف كلمة رئيسية وفق الصيغة <code>**cordova-<platformName>**</code> إلى قائمة الكلمات الرئيسية في <code>package.json</code>. حيث <code><platformName></code> يمثل اسم المنصة. تقوم التعليمة <code>createpackagejson</code> الخاصة ب [[Cordova/plugman|<code>plugman</code>]] بعمل ذلك نيابة عنك، ولكن يمكنك إنشاء <code>package.json</code>يدويًا كما هو موضح أدناه. |
− | على سبيل المثال، بالنسبة إلى الإضافات التي تدعم أندرويد و iOS و وويندوز، يجب أن تضاف الكلمات الرئيسية التالية | + | على سبيل المثال، بالنسبة إلى الإضافات التي تدعم أندرويد و iOS و وويندوز، يجب أن تضاف الكلمات الرئيسية التالية إلى الملف <code>package.json</code>:<syntaxhighlight lang="json">"keywords": [ |
"ecosystem:cordova", | "ecosystem:cordova", | ||
"cordova-android", | "cordova-android", | ||
"cordova-ios", | "cordova-ios", | ||
"cordova-windows" | "cordova-windows" | ||
− | ]</syntaxhighlight>للحصول على مثال أكثر تفصيلاً عن package. | + | ]</syntaxhighlight>للحصول على مثال أكثر تفصيلاً عن صياغة الملف <code>package.json</code>، راجع صفحة [https://github.com/apache/cordova-plugin-device/blob/master/package.json ملف package.json الخاص بالإضافة cordova-plugin-device]. |
==تحديد ارتباطات Cordova (Cordova Dependencies)== | ==تحديد ارتباطات Cordova (Cordova Dependencies)== | ||
− | أضافت | + | أضافت Cordova 6.1.0 إمكانية تحديد ارتباطات الإضافة داخل ملف الإضافة <code>package.json</code>. يمكن للإضافات أن تحدد الارتباطات لمختلف الإصدارات لأجل إرشاد [[Cordova/cli|واجهة سطر الأوامر]] إلى إصدار الإضافة المراد جلبه من مدير الحُزم npm. ستختار [[Cordova/cli|واجهة سطر الأوامر]] أحدث إصدار من الإضافة، والذي يتوافق مع المنصة والإضافات المثبتة في المشروع المحلي، بالإضافة إلى إصدار [[Cordova/cli|واجهة سطر الأوامر]] (Cordova CLI) المحلية. إذا لم يكن أيٌّ من إصدارات الإضافة متوافقا، فستُنبّه [[Cordova/cli|واجهة سطر الأوامر]] المستخدمَ بخصوص فشل المتطلبات، ثم ستعود إلى سلوكها القديم في جلب الإصدار الأحدث. |
− | يُراد لهذه الميزة أن تستبدل [../ | + | يُراد لهذه الميزة أن تستبدل الوسم <code>[https://cordova.apache.org/docs/en/latest/plugin_ref/spec.html#engines-and-engine <engines>]</code> في الملف <code>plugin.xml</code>. إدراج الارتباطات هو وسيلة جيدة لضمان ألا تنكسر إضافتك، أو تحدث أخطاء في البناء عند جلبها من مدير الحزم npm. إذا كان الإصدار الأخير من الإضافة غير متوافق مع المشروع، فستزوّد [[Cordova/cli|واجهة سطر الأوامر]] مطوّر التطبيق بقائمة تشمل متطلبات المشروع التي يحتاج إلى تلبيتها، حتى يكون على دراية بمشاكل التوافقية، ولكي يحدّّث مشروعه حتى يستخدم إضافتك. يسمح هذا الإجراء للإضافة بالتجاوب مع التغييرات المُكْدِية (breaking changes) دون الخوف من إرباك المطورين الذين سيحاولون بناء الإضافة انطلاقا من منصات وإضافات قديمة. |
− | لتعيين ارتباطات الإضافة، قم بتعديل العنصر <code>engines</code> في <code>package.json</code> ليتضمن | + | لتعيين ارتباطات الإضافة، قم بتعديل العنصر <code>engines</code> في ملف <code>package.json</code> ليتضمن الكائن <code>cordovaDependencies</code> وفق الصيغة التالية:<syntaxhighlight lang="json">"engines": { |
"cordovaDependencies": { | "cordovaDependencies": { | ||
PLUGIN_VERSION: { | PLUGIN_VERSION: { | ||
سطر 99: | سطر 109: | ||
} | } | ||
}</syntaxhighlight> | }</syntaxhighlight> | ||
− | *تحدد <code>PLUGIN_VERSION</code> إصدار الإضافة. يمكن أن تحدد إما | + | *تحدد <code>PLUGIN_VERSION</code> إصدار الإضافة. يمكن أن تحدد إما إصدارُا واحدًا كما هو مُعرّف في [https://www.npmjs.com/package/semver حزمة semver]، أو تحدد حدًا أعلى للإصدار (انظر أدناه) |
− | *<code>DEPENDENCY</code> يمكن أن تكون واحدة من القيم التالية: | + | *<code>DEPENDENCY</code>: يمكن أن تكون واحدة من القيم التالية: |
− | * | + | **[[Cordova/cli|واجهة سطر الأوامر]]: <code>"cordova"</code> |
− | *إحدى منصات Cordova: <code>"cordova-android"</code> | + | **إحدى منصات Cordova: <code>"cordova-android"</code>أو <code>"Cordova-ios"</code>أو <code>"cordova-windows"</code>، إلخ. |
− | *إحدى إضافات Cordova مثل: <code>"cordova-plugin-camera"</code> | + | **إحدى إضافات Cordova مثل: <code>"cordova-plugin-camera"</code>. |
− | *<code>SEMVER_RANGE</code>: يجب أن تكون مجالًا كما هو محدد في [https://www.npmjs.com/package/semver | + | *<code>SEMVER_RANGE</code>: يجب أن تكون مجالًا كما هو محدد في [https://www.npmjs.com/package/semver حزمة semver] |
− | + | '''ملاحظة:''' تشير الخاصية <code>DEPENDENCY</code> إلى منصة Cordova، وليس إلى نظام التشغيل، مثلا <code>cordova-android</code> وليس Android OS. | |
− | قد يحتوي <code>cordovaDependencies</code> على أي عدد من متطلبات <code>PLUGIN_VERSION</code> وأي عدد من قيود <code>DEPENDENCY</code>. سيتم افتراض أن إصدارات الإضافة التي لم تُدرج ارتباطاتها لها نفس معلومات الارتباطات لأعلى خاصية <code>PLUGIN_VERSION</code> مدرجة أسفلها. على سبيل المثال:<syntaxhighlight>"engines": { | + | |
+ | قد يحتوي الكائن <code>cordovaDependencies</code> على أي عدد من متطلبات <code>PLUGIN_VERSION</code> وأي عدد من قيود <code>DEPENDENCY</code>. سيتم افتراض أن إصدارات الإضافة التي لم تُدرج ارتباطاتها لها نفس معلومات الارتباطات لأعلى خاصية في <code>PLUGIN_VERSION</code> مدرجة أسفلها. على سبيل المثال:<syntaxhighlight lang="json">"engines": { | ||
"cordovaDependencies": { | "cordovaDependencies": { | ||
"1.0.0": { "cordova-android": "<3.0.0"}, | "1.0.0": { "cordova-android": "<3.0.0"}, | ||
"2.1.0": { "cordova-android": ">4.0.0"} | "2.1.0": { "cordova-android": ">4.0.0"} | ||
} | } | ||
− | }</syntaxhighlight>يُفترض أن جميع إصدارات الإضافة الموجودة | + | }</syntaxhighlight>يُفترض أن جميع إصدارات الإضافة الموجودة تحت المُدخل الأدنى (<code>1.0.0</code> في هذا المثال) ليس لها أي ارتباطات. كما يُفترض أن يكون لكل إصدارات الإضافة الموجودة بين <code>1.0.0</code> و <code>2.1.0</code> نفس الارتباطات التي لدي الإصدار <code>1.0.0</code> (منضة <code>Cordova-android</code> ذات إصدار أقل من <code>3.0.0</code>). لهذا يمكنك الاكتفاء بتحديث معلومات الكائن <code>cordovaDependencies</code> فقط عندما تكون هناك تغييرات مُكدِيَة (breaking changes). |
===الحد الأعلى (Upper Bounds)=== | ===الحد الأعلى (Upper Bounds)=== | ||
− | + | إضافة إلى إمكانية تحديد إصدار واحد، يمكن أن تحدد <code>PLUGIN_VERSION</code> في الكائن <code>cordovaDependencies</code> حدًا أعلى لتعديل المُدخلات للإصدارات القديمة من الإضافة. هذا مفيدًا عند حدوث تغيير مُكدي في الخاصية <code>DEPENDENCY</code>، وعندما تكون هناك حاجة لإضافة تقييد (constraint) جديد لكافة الإصدارات القديمة غير المدعومة من الإضافة. | |
+ | |||
+ | يجب كتابة هذه الحدود على هيئة <code><</code> متبوعة بإصدار [https://www.npmjs.com/package/semver semver] واحد (وليس مجال عشوائي). سيتم تطبيق ذلك كلما تم منح قيم الخاصية <code>DEPENDENCY</code> لإصدارات الإضافة الموجودة أسفل الإصدار المحدد. على سبيل المثال:<syntaxhighlight lang="json">"engines": { | ||
"cordovaDependencies": { | "cordovaDependencies": { | ||
"0.0.1": { "cordova-ios": ">1.0.0" }, | "0.0.1": { "cordova-ios": ">1.0.0" }, | ||
سطر 119: | سطر 132: | ||
"<2.0.0": { "cordova-ios": "<5.0.0" } | "<2.0.0": { "cordova-ios": "<5.0.0" } | ||
} | } | ||
− | }</syntaxhighlight>هنا | + | }</syntaxhighlight>لقد حددنا هنا إصدارًا واحدًا (<code>0.0.1</code>) للإضافة، وحدّان علويان (<code><1.0.0</code> و <code><2.0.0</code>) يُقيّدان (constrain) منصة <code>[[Cordova/plugins ios|Cordova-ios]]</code>. لا يتجاوز (override) الحدان العلويان التقييد المحدد سابقًا (<code>0.0.1</code>)، بل يتم الجمع بينها عبر المعامل AND في وقت التقييم (evaluation time). عندما تتحقق [[Cordova/cli|واجهة سطر الأوامر]] من إصدار <code>[[Cordova/plugins ios|Cordova-ios]]</code> الخاص بالمشروع، فإنّ التقييد (constraint) الذي سيُقيّم (evaluated) لأجل إصدار الإضافة <code>0.0.1</code> سيكون ناتج التعبير التالي:<syntaxhighlight>cordova-ios >1.0.0 AND cordova-ios <2.0.0 AND cordova-ios <5.0.0</syntaxhighlight>تذكر أن قيم <code>PLUGIN_VERSION</code> المسموح بها هي الإصدارات الفردية (single versions) أو الحدود العلوية (upper bounds)؛ ولا تُدعم مجالات [https://www.npmjs.com/package/semver semver] الأخرى. |
+ | |||
+ | == انظر أيضا == | ||
+ | * [[Cordova/plugins android|إضافات أندرويد]] | ||
+ | * [[Cordova/plugins ios|إضافات iOS]] | ||
+ | * [[plugins windows|إضافات ويندوز]] | ||
+ | |||
==مصادر== | ==مصادر== | ||
*[https://cordova.apache.org/docs/en/latest/guide/hybrid/plugins/index.html قسم الإضافات في التوثيق الرسمي لكوردوفا.] | *[https://cordova.apache.org/docs/en/latest/guide/hybrid/plugins/index.html قسم الإضافات في التوثيق الرسمي لكوردوفا.] |
مراجعة 17:08، 20 نوفمبر 2018
"الإضافة" عبارة عن حزمة من الأكواد البرمجية التي تسمح لمعرض كوردوفا (Cordova webview) الذي يُعرض التطبيق من خلاله التواصل مع المنصة الأصلية (native platform) التي يعمل عليها. توفر الإضافات إمكانية الوصول إلى وظائف الجهاز والمنصة غير المتوفرة عادةً للتطبيقات الشبكية (web-based apps). كل ميزات واجهة Cordova البرمجية (Cordova API) الرئيسية تُقدم كإضافات، فضلًا عن العديد من الإضافات الأخرى التي تتيح ميزات مثل ماسحات الرموز الشريطية (bar code scanners) أو اتصالات NFC، أو إضافات لتصميم واجهات التقويم الزمني. يمكنك البحث عن الإضافات المتوفرة على صفحة البحث عن الإضافات.
تشتمل الإضافات على واجهة JavaScript واحدة إلى جانب المكتبات الأصلية (native code libraries) المقابلة لكل منصة مدعومة. الهدف هو حجب الأكواد الأصلية (native code) وراء واجهة JavaScript مشتركة.
يوضح هذا القسم خطوات إنشاء إضافة بسيطة، والتي تمرر سلسلة نصية من JavaScript إلى المنصة الأصلية، والعكس بالعكس، يمكنك استخدامها كنموذج لبناء ميزات أكثر تعقيدًا. يناقش هذا القسم البنية الأساسية للإضافات وواجهة JavaScript المقدمة. للحصول على مزيد من المعلومات بخصوص الواجهات الأصلية (native interfaces) المقابلة، انظر القائمة في نهاية هذا القسم.
بالإضافة إلى هذه الإرشادات، فقبل أن تكتب إضافة جديدة، من الأفضل أن تلقي نظرة على الإضافات الموجودة للحصول على إرشادات.
بناء الإضافة
يستخدم مطورو التطبيقات تعليمة واجهة سطر الأوامر cordova plugin add
لإضافة إضافة معينة إلى مشروع. الوسيط المُعطى لهذه التعليمة هو عنوان مستودع git الذي يحتوي على شيفرة الإضافة. يقدم هذا المثال الإضافة Device:
cordova plugin add https://git-wip-us.apache.org/repos/asf/cordova-plugin-device.git
يجب أن يحتوي مستودع الإضافة على ملف البيان plugin.xml
في المجلد الجذري. هناك عدة طرق لإعداد هذا الملف، لمزيد من التفاصيل راجع صفحة مواصفات الإضافات. توفر هذه النسخة المختصرة من الإضافة Device
مثالاً بسيطًا يمكن استخدامه كنموذج:
<?xml version="1.0" encoding="UTF-8"?>
<plugin xmlns="http://apache.org/cordova/ns/plugins/1.0"
id="cordova-plugin-device" version="0.2.3">
<name>Device</name>
<description>Cordova Device Plugin</description>
<license>Apache 2.0</license>
<keywords>cordova,device</keywords>
<js-module src="www/device.js" name="device">
<clobbers target="device" />
</js-module>
<platform name="ios">
<config-file target="config.xml" parent="/*">
<feature name="Device">
<param name="ios-package" value="CDVDevice"/>
</feature>
</config-file>
<header-file src="src/ios/CDVDevice.h" />
<source-file src="src/ios/CDVDevice.m" />
</platform>
</plugin>
لتحديد حزمة الإضافة، تستخدم الخاصية id
الموجودة في الوسم plugin
نفس تنسيق النطاق العكسي (reverse domain format) الذي تستخدمه التطبيقات التي ستُضاف إليها. يحدد الوسم js-module
مسار واجهة جافاسكريبت المشتركة. كما يحدد الوسم platform
الشيفرة الأصلية المقابلة (لمنصة ios
في هذه الحالة). يغلّف (encapsulates) الوسمُ config-file
وسمًا feature
الذي تم إدخاله في ملف config.xml
الخاص بالمنصة، لتنبيه المنصة بالمكتبة الإضافية. يحدد الوسمان header-file
و source-file
مسار ملفات المكتبة.
التحقق من صحة الإضافة باستخدام Plugman
يمكنك استخدام plugman
للتحقق مما إذا كانت الإضافة ستُثبت بشكل صحيح في كل المنصات. قم بتثبيت plugman
باستخدام تعليمة node التالية:
npm install -g plugman
تحتاج إلى مجلد مصدري (source directory) صالح للتطبيق، مثل المجلد الجذري www
المضمّن في المشروع الافتراضي المُنشأ عبر واجهة سطر الأوامر، كما هو موضح في صفحة أنشئ تطبيقك الأول.
ثم قم بإجراء الأمر التالي لاختبار ما إذا كانت ارتباطات (dependencies) منصة iOS تُحمّل بالشكل المطلوب:
plugman install --platform ios --project /path/to/my/project/www --plugin /path/to/my/plugin
لمزيد من المعلومات حول كيفية تصحيح (debug) الإضافات، راجع صفحات واجهات المنصات الأصلية (platform's native interface) في أسفل هذه الصفحة.
واجهة JavaScript
توفر واجهة JavaScript الواجهة الأمامية، ما يجعلها على الأرجح أهم جزء في الإضافة. يمكنك بناء شيفرة JavaScript الخاصة بالإضافة بالطريقة التي تحب، ولكنك ستحتاج إلى استدعاء cordova.exec
للتواصل مع المنصة الأصلية باستخدام الصياغة التالي:
cordova.exec(function(winParam) {},
function(error) {},
"service",
"action",
["firstArgument", "secondArgument", 42, false]);
المعاملات
function(winParam) {}
دالة النجاح (success callback function). بافتراض أن استدعاء exec
مر بنجاح، فستنُفذ هذه الدالة مع الوسائط التي مررتها إليها.
function(error) {}
دالة الخطأ (error callback function). إذا لم تكتمل العملية بنجاح، ستنفذ هذه الدالة مع وسيط اختياري.
"service"
اسم الخدمة المراد استدعاؤها في المنصة الأصلية. يتوافق مع صنف أصلي، والذي ستجد معلومات أكثر تفصيلا عنه في الأدلة الأصلية المذكورة أدناه.
"action"
اسم الإجراء (action) المراد استدعاؤه في المنصة الأصلية. هذا يتوافق عمومًا مع تابع الصنف الأصلي. راجع الأدلة الأصلية المدرجة أدناه.
[/* arguments */]
مصفوفة من الوسائط لأجل تمريرها إلى البيئة الأصلية.
مثال JavaScript
يوضح هذا المثال إحدى الطرق الممكنة لتقديم واجهة JavaScript الخاصة بالإضافة:
window.echo = function(str, callback) {
cordova.exec(callback, function(err) {
callback('Nothing to echo.');
}, "Echo", "echo", [str]);
};
في هذا المثال، تربط الإضافة نفسها بالكائن window
باعتبارها الدالة echo
، والتي سيستدعيها مستخدموا الإضافة على النحو التالي:
window.echo("echome", function(echoValue) {
alert(echoValue == "echome"); // should alert true.
});
انظر إلى الوسائط الثلاثة الأخيرة المُمررة إلى الدالة cordova.exec
. يستدعي الأول الخدمة Echo
، والتي هي اسم صنف. ويطلب الثاني الإجراء echo
، والذي هو تابعٌ داخل ذلك الصنف. أما الثالث فهو مصفوفة من الوسائط التي تحتوي السلسلة النصية المعادة، والتي هي الوسيط الأول للدالة window.echo
.
دالة النجاح (success callback) المُمررة إلى exec
هي مرجعٌ إلى دالة الاستدعاء (callback function) الخاصة بـ window.echo
. إذا أطلقت المنصة الأصلية دالة الخطأ (error callback)، فسيستدعي ببساطة دالة النجاح، ويمرر إليها السلسلة النصية الافتراضية.
الواجهات الأصلية (Native Interfaces)
بمجرد إنهاء أكواد JavaScript للإضافة خاصتك، فسيكون عليك تكميلها بتقديم أصلي (native implementation) واحد على الأقل. يمكنك إيجاد تفاصيل كل منصة أدناه، وكلها تُبنى على مثال الإضافة Echo
أعلاه:
نشر الإضافات
يمكنك نشر إضافتك في سجل قائم على مدير حُزم جافاسكريبت (npmjs
-based registry)، لكن يوصى باستخدام npm registry. يمكن للمطورين الآخرين تثبيت إضافتك تلقائيا باستخدام إما plugman
أو واجهة سطر الأوامر (CLI).
لنشر الإضافة على مدير الحُزم npm، يلزمك اتباع الخطوات التالية:
قم بتثبيت plugman
:
$ npm install -g plugman
قم بإنشاء ملف package.json
للإضافة خاصتك:
$ plugman createpackagejson /path/to/your/plugin
انشرها:
$ npm adduser # that is if you don't have an account yet
$ npm publish /path/to/your/plugin
لمزيد من التفاصيل حول استخدام npm، راجع صفحة نشر حزم npm.
دمج الإضافة في خاصية البحث عن الإضافات
لإظهار الإضافة في صفحة البحث عن الإضافات، أضف الكلمة المفتاحية ecosystem:cordova
إلى ملف package.json
الخاص بالإضافة قبل نشرها.
للإشارة إلى أنّ الإضافة تدعم منصة معينة، أضف كلمة رئيسية وفق الصيغة **cordova-<platformName>**
إلى قائمة الكلمات الرئيسية في package.json
. حيث <platformName>
يمثل اسم المنصة. تقوم التعليمة createpackagejson
الخاصة ب plugman
بعمل ذلك نيابة عنك، ولكن يمكنك إنشاء package.json
يدويًا كما هو موضح أدناه.
على سبيل المثال، بالنسبة إلى الإضافات التي تدعم أندرويد و iOS و وويندوز، يجب أن تضاف الكلمات الرئيسية التالية إلى الملف package.json
:
"keywords": [
"ecosystem:cordova",
"cordova-android",
"cordova-ios",
"cordova-windows"
]
للحصول على مثال أكثر تفصيلاً عن صياغة الملف package.json
، راجع صفحة ملف package.json الخاص بالإضافة cordova-plugin-device.
تحديد ارتباطات Cordova (Cordova Dependencies)
أضافت Cordova 6.1.0 إمكانية تحديد ارتباطات الإضافة داخل ملف الإضافة package.json
. يمكن للإضافات أن تحدد الارتباطات لمختلف الإصدارات لأجل إرشاد واجهة سطر الأوامر إلى إصدار الإضافة المراد جلبه من مدير الحُزم npm. ستختار واجهة سطر الأوامر أحدث إصدار من الإضافة، والذي يتوافق مع المنصة والإضافات المثبتة في المشروع المحلي، بالإضافة إلى إصدار واجهة سطر الأوامر (Cordova CLI) المحلية. إذا لم يكن أيٌّ من إصدارات الإضافة متوافقا، فستُنبّه واجهة سطر الأوامر المستخدمَ بخصوص فشل المتطلبات، ثم ستعود إلى سلوكها القديم في جلب الإصدار الأحدث.
يُراد لهذه الميزة أن تستبدل الوسم <engines>
في الملف plugin.xml
. إدراج الارتباطات هو وسيلة جيدة لضمان ألا تنكسر إضافتك، أو تحدث أخطاء في البناء عند جلبها من مدير الحزم npm. إذا كان الإصدار الأخير من الإضافة غير متوافق مع المشروع، فستزوّد واجهة سطر الأوامر مطوّر التطبيق بقائمة تشمل متطلبات المشروع التي يحتاج إلى تلبيتها، حتى يكون على دراية بمشاكل التوافقية، ولكي يحدّّث مشروعه حتى يستخدم إضافتك. يسمح هذا الإجراء للإضافة بالتجاوب مع التغييرات المُكْدِية (breaking changes) دون الخوف من إرباك المطورين الذين سيحاولون بناء الإضافة انطلاقا من منصات وإضافات قديمة.
لتعيين ارتباطات الإضافة، قم بتعديل العنصر engines
في ملف package.json
ليتضمن الكائن cordovaDependencies
وفق الصيغة التالية:
"engines": {
"cordovaDependencies": {
PLUGIN_VERSION: {
DEPENDENCY: SEMVER_RANGE,
DEPENDENCY: SEMVER_RANGE,
...
},
...
}
}
- تحدد
PLUGIN_VERSION
إصدار الإضافة. يمكن أن تحدد إما إصدارُا واحدًا كما هو مُعرّف في حزمة semver، أو تحدد حدًا أعلى للإصدار (انظر أدناه) DEPENDENCY
: يمكن أن تكون واحدة من القيم التالية:- واجهة سطر الأوامر:
"cordova"
- إحدى منصات Cordova:
"cordova-android"
أو"Cordova-ios"
أو"cordova-windows"
، إلخ. - إحدى إضافات Cordova مثل:
"cordova-plugin-camera"
.
- واجهة سطر الأوامر:
SEMVER_RANGE
: يجب أن تكون مجالًا كما هو محدد في حزمة semver
ملاحظة: تشير الخاصية DEPENDENCY
إلى منصة Cordova، وليس إلى نظام التشغيل، مثلا cordova-android
وليس Android OS.
قد يحتوي الكائن cordovaDependencies
على أي عدد من متطلبات PLUGIN_VERSION
وأي عدد من قيود DEPENDENCY
. سيتم افتراض أن إصدارات الإضافة التي لم تُدرج ارتباطاتها لها نفس معلومات الارتباطات لأعلى خاصية في PLUGIN_VERSION
مدرجة أسفلها. على سبيل المثال:
"engines": {
"cordovaDependencies": {
"1.0.0": { "cordova-android": "<3.0.0"},
"2.1.0": { "cordova-android": ">4.0.0"}
}
}
يُفترض أن جميع إصدارات الإضافة الموجودة تحت المُدخل الأدنى (1.0.0
في هذا المثال) ليس لها أي ارتباطات. كما يُفترض أن يكون لكل إصدارات الإضافة الموجودة بين 1.0.0
و 2.1.0
نفس الارتباطات التي لدي الإصدار 1.0.0
(منضة Cordova-android
ذات إصدار أقل من 3.0.0
). لهذا يمكنك الاكتفاء بتحديث معلومات الكائن cordovaDependencies
فقط عندما تكون هناك تغييرات مُكدِيَة (breaking changes).
الحد الأعلى (Upper Bounds)
إضافة إلى إمكانية تحديد إصدار واحد، يمكن أن تحدد PLUGIN_VERSION
في الكائن cordovaDependencies
حدًا أعلى لتعديل المُدخلات للإصدارات القديمة من الإضافة. هذا مفيدًا عند حدوث تغيير مُكدي في الخاصية DEPENDENCY
، وعندما تكون هناك حاجة لإضافة تقييد (constraint) جديد لكافة الإصدارات القديمة غير المدعومة من الإضافة.
يجب كتابة هذه الحدود على هيئة <
متبوعة بإصدار semver واحد (وليس مجال عشوائي). سيتم تطبيق ذلك كلما تم منح قيم الخاصية DEPENDENCY
لإصدارات الإضافة الموجودة أسفل الإصدار المحدد. على سبيل المثال:
"engines": {
"cordovaDependencies": {
"0.0.1": { "cordova-ios": ">1.0.0" },
"<1.0.0": { "cordova-ios": "<2.0.0" },
"<2.0.0": { "cordova-ios": "<5.0.0" }
}
}
لقد حددنا هنا إصدارًا واحدًا (0.0.1
) للإضافة، وحدّان علويان (<1.0.0
و <2.0.0
) يُقيّدان (constrain) منصة Cordova-ios
. لا يتجاوز (override) الحدان العلويان التقييد المحدد سابقًا (0.0.1
)، بل يتم الجمع بينها عبر المعامل AND في وقت التقييم (evaluation time). عندما تتحقق واجهة سطر الأوامر من إصدار Cordova-ios
الخاص بالمشروع، فإنّ التقييد (constraint) الذي سيُقيّم (evaluated) لأجل إصدار الإضافة 0.0.1
سيكون ناتج التعبير التالي:
cordova-ios >1.0.0 AND cordova-ios <2.0.0 AND cordova-ios <5.0.0
تذكر أن قيم PLUGIN_VERSION
المسموح بها هي الإصدارات الفردية (single versions) أو الحدود العلوية (upper bounds)؛ ولا تُدعم مجالات semver الأخرى.