الإضافات في 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 أخرى.

مصادر

مجلوبة من «https://wiki.hsoub.com/index.php?title=Cordova/plugins&oldid=24130»