الإضافات في Cordova
"الإضافة" عبارة عن حزمة من الأكواد البرمجية التي تسمح لمعرض كوردوفا (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
تحتاج إلى مجلد مصدري صالح للتطبيق، مثل المجلد الجذري www
المضمّن في مشروع افتراضي تم إنشاؤه بواسطة واجهة سطر الأوامر، كما هو موضح في الدليل [../../cli/index.html Create your first app].
ثم قم بإجراء أمر كما ما يلي لاختبار ما إذا كانت متعلقات المنصة iOS تُحمّل بشكل صحيح:
plugman install --platform ios --project /path/to/my/project/www --plugin /path/to/my/plugin
لمزيد من التفاصيل حول خيارات plugman
، انظر صفحة [../../../plugin_ref/plugman.html Using Plugman to Manage Plugins]. لمزيد من المعلومات حول كيفية تصحيح الإضافات ، راجع صفحات الواجهات الأصلية للمنصات في أسفل هذه الصفحة.
واجهة JavaScript
توفر واجهة JavaScript الواجهة الأمامية، مما يجعلها على الأرجح أهم جزء في الإضافة. يمكنك بناء شيفرة JavaScript الخاصة بالإضافة بالطريقة التي تحب، ولكنك ستحتاج إلى استدعاء cordova.exec
للتواصل مع المنصة الأصلية، باستخدام الصياغة التالي:
cordova.exec(function(winParam) {},
function(error) {},
"service",
"action",
["firstArgument", "secondArgument", 42, false]);
المعاملات
function(winParam) {}
: دالة النجاح. بافتراض أن استدعاء exec
مر بنجاح، فستنُفذ هذه الدالة مع الوسائط التي مررتها إليها.
function(error) {}
: دالة الخطأ. إذا لم تكتمل العملية بنجاح، تنفذ هذه الدالة مع وسيط خطأ اختياري.
"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
هي مرجع إلى دالة الاستدعاء الخاصة بـ window.echo
. إذا أطلقت المنصة الأصلية استدعاء الخطأ (error callback)، فسيستدعي ببساطة استدعاء النجاح ويمرر إليها السلسلة النصية الافتراضية.
الواجهات الأصلية (Native Interfaces)
بمجرد تحديد JavaScript للإضافة خاصتك، فسيكون عليك تكميلها بتقديم أصلي (native implementation) واحد على الأقل. يمكنك إيجاد تفاصيل كل منصة أدناه، وكلها تُبنى على أساس مثال الإضافة Echo أعلاه: [../../platforms/android/plugin.html Android Plugins] [../../platforms/ios/plugin.html iOS Plugins] [../../platforms/windows/plugin.html Windows Plugins]
نشر الإضافات
يمكنك نشر إضافتك لك سجل قائم على مدير حُزم JavaScript (npmjs
)، لكن يوصى باستخدام 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، راجع الصفحة Publishing npm Packages في موقع npm.
دمج الإضافة في خاصية البحث عن الإضافات
لإظهار الإضافة في صفحة [/plugins/ Cordova Plugin Search]، أضف الكلمة المفتاحية ecosystem:cordova
إلى ملف package.json
الخاص بالإضافة قبل النشر.
للإشارة إلى أنّ الإضافة تدعم منصة معينة، أضف كلمة رئيسية وفق الصيغة **cordova-<platformName>**
إلى قائمة الكلمات الرئيسية في package.json. تقوم التعليمة createpackagejson
الخاصة ب plugman بعمل ذلك نيابة عنك، ولكن إذا لم تستخدمه لإنشاء package.json
، فيجب عليك تعديله يدويًا كما هو موضح أدناه.
على سبيل المثال، بالنسبة إلى الإضافات التي تدعم أندرويد و iOS و وويندوز، يجب أن تضاف الكلمات الرئيسية التالية في package.json
:
"keywords": [
"ecosystem:cordova",
"cordova-android",
"cordova-ios",
"cordova-windows"
]
للحصول على مثال أكثر تفصيلاً عن package.json، راجع صفحة package.json file of cordova-plugin-device.
تحديد ارتباطات Cordova (Cordova Dependencies)
أضافت Cordova 6.1.0 إمكانية تحديد ارتباطات الإضافة كجزء من ملف الإضافة package.json
. قد تسرد الإضافات الارتباطات لمختلف الإصدارات لإرشاد واجهة سطر الأوامر إلى إصدار الإضافة المراد جلبه من مدير الحُزم npm. ستختار واجهة سطر الأوامر أحدث إصدار من الإضافة، والذي يتوافق مع المنصة والإضافات المثبتة في المشروع المحلي، بالإضافة إلى إصدار واجهة سطر الأوامر (Cordova CLI) المحلية. إذا لم يكن أيٌّ من إصدارات الإضافة متوافقا، فستبنبه واجهة سطر الأوامر (CLI) المستخدم من فشل المتطلبات، وستعود إلى سلوكها القديم في جلب الإصدار الأحدث.
يُراد لهذه الميزة أن تستبدل [../../../plugin_ref/spec.html#engines-and-engine engines element] في الملف plugin.xml في نهاية المطاف. إدراج الارتباطات هو وسيلة جيدة لضمان ألا تنكسر إضافتك، أو تحدث أخطاء في البناء عند جلبه من مدير الحزم npm. إذا كان الإصدار الأخير من الإضافة غير متوافق مع المشروع، فستمنح واجهة سطر الأوامر لمطوّر التطبيق قائمة بمتطلبات المشروع التي يحتاج إلى تلبيتها، حتى يكون على دراية بمشاكل التوافقية، ولكي يحدّّث مشروعه حتى يستخدم إضافتك. يسمح هذا الإجراء للإضافة بالتجاوب مع التغييرات الكاسرة لعملها (breaking changes) دون الخوف من إرباك المطورين الذين سيحاولون بناء الإضافة انطلاقا من منصات وإضافات قديمة.
لتعيين ارتباطات الإضافة، قم بتعديل العنصر engines
في package.json
ليتضمن كائن cordovaDependencies
وفق الصيغة التالية:
"engines": {
"cordovaDependencies": {
PLUGIN_VERSION: {
DEPENDENCY: SEMVER_RANGE,
DEPENDENCY: SEMVER_RANGE,
...
},
...
}
}
- تحدد
PLUGIN_VERSION
إصدار الإضافة. يمكن أن تحدد إما إصدار واحد كما هو محدد في npm's semver package، أو تحدد حدًا أعلى للإصدار (انظر [#upper-bounds below]) DEPENDENCY
يمكن أن تكون واحدة من القيم التالية:- The Cordova CLI:
"cordova"
- إحدى منصات Cordova:
"cordova-android"
،"cordova-ios"
،"cordova-windows"
، إلخ. - إحدى إضافات Cordova مثل:
"cordova-plugin-camera"
، وما إلى ذلك. SEMVER_RANGE
: يجب أن تكون مجالًا كما هو محدد في npm's semver package
- NOTE: تشير
DEPENDENCY
إلى منصة Cordova، وليس إلى نظام التشغيل، مثلاcordova-android
بدلا من نظام التشغيل أندرويد.
قد يحتوي 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 (Not an arbitrary range!). سيتم تطبيق ذلك كلما تم منح قيم 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) يقيّدان منصة Cordova-ios. لا يتجاوز (override) الحدان العلويان التقييد المحدد سابقًا (0.0.1)، بل يتم الجمع بينها عبر المعامل AND ووقت التقييم. عندما تتحقق واجهة سطر الأوامر من إصدار 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 أخرى.