Cordova/plugins

"الإضافة" عبارة عن حزمة من الأكواد البرمجية التي تسمح لمعرض كوردوفا (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 المذكور أعلاه:

• إضافات أندرويد
• إضافات iOS
• إضافات ويندوز

نشر الإضافات

يمكنك نشر إضافتك في سجل قائم على مدير حُزم جافاسكريبت (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 Bound)

إضافة إلى إمكانية تحديد إصدار واحد، يمكن أن تحدد 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 الأخرى.

انظر أيضا

• إضافات أندرويد
• إضافات iOS
• إضافات ويندوز

مصادر

• قسم الإضافات في التوثيق الرسمي لكوردوفا.