Cordova/plugins

الإضافة هي حزمة من الأكواد البرمجية التي تسمح لعارض كوردوفا (Cordova webview)، الذي يُعرض التطبيق من خلاله، التواصل مع المنصة الأصلية (native platform) التي يعمل عليها. توفر الإضافات إمكانية الوصول إلى وظائف الجهاز والمنصة غير المتوفرة عادةً للتطبيقات الشبكية (web-based apps). كل ميزات واجهة كوردوفا البرمجية (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 مسار واجهة JavaScript المشتركة. كما يحدد الوسم 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 واجهةً أماميةً (front-facing interface) ما يجعلها على الأرجح أهم جزء في الإضافة. يمكنك بناء شيفرة 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.

دالة رد نداء النجاح المُمررة إلى exec هي مرجعٌ إلى دالة رد النداء التي تخص window.echo. إذا أطلقت المنصة الأصلية دالة رد نداء الخطأ (error callback)، فسيستدعي ببساطة دالة النجاح، ويمرر إليها السلسلة النصية الافتراضية.

الواجهات الأصلية

بمجرد إنهاء أكواد JavaScript الخاصة بالإضافة، فسيكون عليك تكميلها بتنفيذ أصلي (native implementation) واحد على الأقل. يمكنك إيجاد تفاصيل كل منصة أدناه، وكلها تُبنَى على مثال الإضافة Echo المذكور أعلاه:

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

نشر الإضافات

يمكنك نشر إضافتك في سجل قائم على مدير حُزم npmjs-based registry) JavaScript)، لكن يوصى باستخدام npm registry. يمكن للمطورين الآخرين تثبيت إضافتك تلقائيًّا باستخدام إما plugman أو واجهة سطر الأوامر في كوردوفا.

لنشر الإضافة على مدير الحُزم 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 6.1.0 إمكانية تحديد اعتماديات (dependencies) الإضافة داخل ملف الإضافة package.json. يمكن للإضافات أن تحدد الاعتماديات لمختلف الإصدارات لأجل إرشاد واجهة سطر الأوامر إلى إصدار الإضافة المراد جلبه من مدير الحُزم npm. ستختار واجهة سطر الأوامر أحدث إصدار من الإضافة، والذي يتوافق مع المنصة والإضافات المثبتة في المشروع المحلي، بالإضافة إلى إصدار واجهة سطر الأوامر المحلية. إذا لم يكن أيٌّ من إصدارات الإضافة متوافقًا، فستُنبّه واجهة سطر الأوامر المستخدمَ بخصوص فشل المتطلبات، ثم ستعود إلى سلوكها القديم في جلب الإصدار الأحدث.

يُراد لهذه الميزة أن تستبدل الوسم <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-android" أو "Cordova-ios" أو "cordova-windows" ...إلخ.
  • إحدى إضافات كوردوفا: مثل "cordova-plugin-camera".
• SEMVER_RANGE: يجب أن تكون مجالًا كما هو محدد في حزمة semver.

ملاحظة: تشير الخاصية DEPENDENCY إلى منصة كوردوفا، وليس إلى نظام التشغيل، مثل 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).

الحد الأعلى

إضافة إلى إمكانية تحديد إصدار واحد، يمكن أن تحدد PLUGIN_VERSION في الكائن cordovaDependencies حدًا أعلى (Upper Bound) لتعديل مُدخلات الإصدارات القديمة من الإضافة. هذا مفيد عند حدوث تغيير انهيار في الخاصية 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
• إضافات ويندوز

مصادر

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