الفرق بين المراجعتين لصفحة: «Cordova/plugman»

المراجعة الحالية بتاريخ 12:30، 1 ديسمبر 2020

منذ الإصدار 3.0 وما بعده، أصبحت كوردوفا تنفِّذ كل الواجهات البرمجية الخاصة بالجهاز (device APIs) على شكل إضافات، لكن لا تفعِّلها افتراضيًا. كما أنَّها تدعم طريقتين مختلفتين لإضافة وإزالة الإضافات، اعتمادًا على سير العمل (workflow) المُعتمد (اطلع على الصفحة "نظرة عامة"):

إن كنت تستخدم سير عمل عابر للمنصات (cross-platform)، فعليك استخدام الأمر cordova في واجهة سطر الأوامر لكي تضيف الإضافات، كما هو موضح في صفحة واجهة سطر الأوامر . تُعدل واجهة سطر الأوامر الإضافات في جميع المنصات المحددة في نفس الوقت.
إن كنت تستخدم سير عمل مرتكز على منصة واحدة، فعليك استخدام الأمر منخفض المستوى Plugman في واجهة سطر الأوامر لكل منصة مستهدفة على حِدة.

يقدم هذا القسم تفاصيل عن كيفية استخدام الأداة Plugman. لمزيد من المعلومات حول استخدام Plugman كوحدة عقدية (node module)، أو لتعديل الشيفرة المصدرية، فاطلع على الملف README في هذه الصفحة.

تثبيت Plugman

لتثبيت Plugman، يجب أن يكونnode مثبتًا على جهازك. بعد ذلك، يمكنك تنفيذ الأمر التالي من أي مكان في بيئة العمل لتثبيت Plugman بشكل عام (globally) حتى يكون متاحًا من أي مجلد:

$ npm install -g plugman‎

ينبغي أيضًا أن يكون git مضافًا إلى المتغير العام PATH لتتمكن من تثبيت الإضافات عن بُعد مباشرة من عناوين git.

تنبيه: إن وجدت أنك بعد تثبيت plugman بواسطة npm لا تزال غير قادر على تنفيذ أوامر plugman، فتأكد من إضافة المجلد /npm/ إلى المتغير العام PATH.

ملاحظة: يمكنك تخطي هذه الخطوة إن لم تُرد إفساد مجال الأسماء العام npm بتثبيت Plugman بشكل عام (globally). في هذه الحالة، سيكون هناك المجلد node_modules داخل مشروعك يتضمن Plugman عندما تنشئ مشروع كوردوفا باستخدام أدوات الصدفة (shell). ولأنك لم تُثبّت Plugman بشكل عام، فسيكون عليك استدعاء node مع كل أوامر Plugman، مثل الأمر: node ./node_modules/plugman/main.js -version.

سنفترض في بقية هذا الدليل أنك قمت بتثبيت Plugman بشكل عام، ما يعني أنه بمقدورك استدعاؤها عبر الأمر plugman وحده.

إنشاء مشروع كوردوفا

قبل أن تتمكن من استخدام Plugman، سيكون عليك إنشاء مشروع كوردوفا. يمكنك القيام بذلك إما بواجهة سطر الأوامر أو ببرامج الصدفة منخفضة المستوى (lower level shell scripts).

كيفية إضافة الإضافات

بمجرد تثبيت Plugman وإنشاء مشروع كوردوفا، يمكنك أت تضيف إضافات إلى المنصة عبر الأمر التالي:

$ plugman install --platform <ios|android> --project <directory> --plugin <name|url|path> [--plugins_dir <directory>] [--www <directory>] [--variable <name>=<value> [--variable <name>=<value> ...]]

باستخدام الحد الأدنى من المعاملات، يثبِّت هذا الأمر الإضافة في مشروع كوردوفا. من اللازم تحديد منصة وموضع مشروع كوردوفا الخاص بها. يجب عليك أيضًا تحديد إضافة عقِب العبارة ‎--plugin عبر المعاملات التالية:

name: اسم المجلد الذي يتضمّن محتويات الإضافة. يجب أن يكون مجلدًا موجودًا داخل المسار ‎--plugins_dir (انظر أدناه لمزيد من المعلومات) أو إضافة في سجل (registry) كوردوفا.
url: عنوان يبدأ بـ https://‎ أو git://‎، ويشير إلى مستودع git صالح وقابل للنسخ، ويحتوي على ملف plugin.xml. ستُنسخ محتويات هذا المستودع في المجلد ‎--plugins_dir.
path: مسار إلى مجلد يحتوي على إضافة صالحة مرفقة بالملف plugin.xml. ستُنسخ محتويات هذا المسار في المجلد ‎--plugins_dir.

معاملات أخرى:

‎--plugins_dir: قيمته الافتراضية تساوي ‎<project>/cordova/plugins، ولكن يمكن أن يكون أي مجلد يحتوي على مجلدات فرعية مقابلة لكل إضافة مجلوبة (fetched).
‎--www: قيمته الافتراضية تساوي موضع مجلد المشروع www، ولكن قد يكون أي مجلد يمكن استخدامه كموضع لأصول (assets) مشروع كوردوفا.
‎--variable: يسمح بتحديد متغيرات معينة وقتَ التثبيت، وهو ضروري لبعض الإضافات التي تتطلب مفاتيح واجهة برمجية (API keys) أو غيرها من المعاملات المخصصة والمعرفة من قبل المستخدم. يرجى الاطلاع على صفحة plugin specification لمزيد من المعلومات.

إزالة الإضافات

لإزالة إضافةٍ محددةٍ، كل ما عليك فعله هو تمرير الأمر uninstall مرفقًا بمعرف (ID) الإضافة:

$ plugman uninstall --platform <ios|android> --project <directory> --plugin <id> [--www <directory>] [--plugins_dir <directory>]

أوامر طلب المساعدة

يوفر Plugman الأمر help لاستخدامه لأجل الحصول على المساعدة في حال واجهتك مشكلة، إذ سيعرض قائمةً بجميع أوامر Plugman المتاحة مع توضيح طريقة صياغتها:

plugman -help
plugman  # same as above‎

ملاحظة: قد يظهر الأمر plugman -help بعض أوامر السّجل (registry-related commands) الإضافية. هذه الأوامر مخصصة لمطوري الإضافات، وقد لا تنفَّذ على سجلات الإضافات القادمة من طرف ثالث.

يمكنك أيضًا إضافة الراية ‎--debug|-d إلى أي أمرٍ من أوامر Plugman لتنفيذه في الوضع المفصّل (verbose mode)، حيث سيعرض رسائل تصحيح الأخطاء الداخلية عند إصدارها، وقد يساعدك في تعقب مصدر المشكلة، مثل مشكلة عدم إيجاد الملفات.

# Adding Android battery-status plugin to "myProject":
plugman -d install --platform android --project myProject --plugin cordova-plugin-battery-status

وأخيرًا، يمكنك استخدام الراية ‎--version|-v لمعرفة إصدار Plugman الذي تستخدمه.

plugman -v‎

إجراءات السجلات (Registry Actions)

هناك عدد من أوامر plugman التي يمكن استخدامها للتفاعل مع سجل الإضافات (Plugin registry). يرجى ملاحظة أن أوامر السجلات هذه مخصوصة بسجل الإضافات plugins.cordova.io، وقد لا تُنفَّذ (implemented) من قبل سجلات الإضافات القادمة من طرف ثالث.

البحث عن الإضافات

يمكنك استخدام Plugman للبحث في سجل الإضافات (Plugin registry) عن مُعرِّف (id) الإضافة التي تُطابق لائحة من الكلمات الرئيسية مفصولة بمسافات بيضاء.

plugman search <plugin keywords>‎

تغيير سجل الإضافة

يمكنك الحصول على سجل الإضافة الحالية التي يستخدمها plugman أو تعيين عنوانها. لكن يجب عليك عمومًا تركه عند القيمة http://registry.cordova.io، إلا إن كنت ترغب في استخدام سجل إضافة من طرف ثالث.

plugman config set registry <url-to-registry>
plugman config get registry

الحصول على معلومات عن الإضافات

يمكنك الحصول على معلومات حول أي إضافة مُخزّنة في مستودع الإضافات عبر الأمر التالي:

plugman info <id>‎

سيتصل هذا الأمر بسجل الإضافة وسيجلب معلومات عنها مثل رقم إصدار الإضافة.

تثبيت الإضافات الأساسية

توضح الأمثلة أدناه كيف تضيف الإضافات بحسب الحاجة، بحيث أن كل الواجهات البرمجية لكوردوفا التي تستخدمها في مشروعك ستستمر بالعمل حتى بعد الترقية إلى الإصدار 3.0.

مع كل أمرٍ (command)، سيكون عليك تحديد المنصة المستهدفة، والإشارة إلى مجلد المشروع في المنصة. إليك الأمثلة التالية:

cordova-plugin-battery-status

plugman install --platform <ios|android> --project <directory> --plugin cordova-plugin-battery-status‎

cordova-plugin-camera

plugman install --platform <ios|android> --project <directory> --plugin cordova-plugin-camera‎

cordova-plugin-console

plugman install --platform <ios|android> --project <directory> --plugin cordova-plugin-console‎

cordova-plugin-contacts

plugman install --platform <ios|android> --project <directory> --plugin cordova-plugin-contacts‎

cordova-plugin-device

plugman install --platform <ios|android> --project <directory> --plugin cordova-plugin-device‎

cordova-plugin-device-motion (accelerometer)‎

plugman install --platform <ios|android> --project <directory> --plugin cordova-plugin-device-motion‎

cordova-plugin-device-orientation (compass)‎

plugman install --platform <ios|android> --project <directory> --plugin cordova-plugin-device-orientation‎

cordova-plugin-dialogs

plugman install --platform <ios|android> --project <directory> --plugin cordova-plugin-dialogs‎

cordova-plugin-file

plugman install --platform <ios|android> --project <directory> --plugin cordova-plugin-file‎

cordova-plugin-file-transfer

plugman install --platform <ios|android> --project <directory> --plugin cordova-plugin-file-transfer‎

cordova-plugin-geolocation

plugman install --platform <ios|android> --project <directory> --plugin cordova-plugin-geolocation‎

cordova-plugin-globalization

plugman install --platform <ios|android> --project <directory> --plugin cordova-plugin-globalization‎

cordova-plugin-inappbrowser

plugman install --platform <ios|android> --project <directory> --plugin cordova-plugin-inappbrowser‎

cordova-plugin-media

plugman install --platform <ios|android> --project <directory> --plugin cordova-plugin-media‎

cordova-plugin-media-capture

plugman install --platform <ios|android> --project <directory> --plugin cordova-plugin-media-capture‎

cordova-plugin-network-information

plugman install --platform <ios|android> --project <directory> --plugin cordova-plugin-network-information‎

cordova-plugin-splashscreen

plugman install --platform <ios|android> --project <directory> --plugin cordova-plugin-splashscreen‎

cordova-plugin-vibration

plugman install --platform <ios|android> --project <directory> --plugin cordova-plugin-vibration‎

انظر أيضًا

دليل تطوير الإضافات

مصادر

صفحة Using Plugman to Manage Plugins في توثيق كوردوفا الرسمي.

@@ سطر 27: / سطر 27: @@
 بمجرد تثبيت <code>Plugman</code> وإنشاء مشروع كوردوفا، يمكنك أت تضيف إضافات إلى المنصة عبر الأمر التالي:
-<syntaxhighlight lang="console">$ plugman install --platform <ios|android> --project <directory> --plugin <name|url|path> [--plugins_dir <directory>] [--www <directory>] [--variable <name>=<value> [--variable <name>=<value> ...]]‎</syntaxhighlight>
+<syntaxhighlight lang="console">$ plugman install --platform <ios|android> --project <directory> --plugin <name|url|path> [--plugins_dir <directory>] [--www <directory>] [--variable <name>=<value> [--variable <name>=<value> ...]]
+</syntaxhighlight>
 باستخدام الحد الأدنى من المعاملات، يثبِّت هذا الأمر الإضافة في مشروع كوردوفا. من اللازم تحديد منصة وموضع مشروع كوردوفا الخاص بها. يجب عليك أيضًا تحديد إضافة عقِب العبارة ‎<code>--plugin</code> عبر المعاملات التالية:
@@ سطر 42: / سطر 43: @@
 لإزالة إضافةٍ محددةٍ، كل ما عليك فعله هو تمرير الأمر <code>uninstall</code> مرفقًا بمعرف (ID) الإضافة:
-<syntaxhighlight lang="console">$ plugman uninstall --platform <ios|android> --project <directory> --plugin <id> [--www <directory>] [--plugins_dir <directory>]‎</syntaxhighlight>
+<syntaxhighlight lang="console">$ plugman uninstall --platform <ios|android> --project <directory> --plugin <id> [--www <directory>] [--plugins_dir <directory>]
+</syntaxhighlight>
 == أوامر طلب المساعدة ==
@@ سطر 54: / سطر 56: @@
 يمكنك أيضًا إضافة الراية ‎<code>--debug|-d</code> إلى أي أمرٍ من أوامر <code>Plugman</code> لتنفيذه في الوضع المفصّل (verbose mode)، حيث سيعرض رسائل تصحيح الأخطاء الداخلية عند إصدارها، وقد يساعدك في تعقب مصدر المشكلة، مثل مشكلة عدم إيجاد الملفات.
 <syntaxhighlight lang="console"># Adding Android battery-status plugin to "myProject":
-plugman -d install --platform android --project myProject --plugin cordova-plugin-battery-status‎</syntaxhighlight>
+plugman -d install --platform android --project myProject --plugin cordova-plugin-battery-status
+</syntaxhighlight>
 وأخيرًا، يمكنك استخدام الراية ‎<code>--version|-v</code> لمعرفة إصدار <code>Plugman</code> الذي تستخدمه.
@@ سطر 70: / سطر 73: @@
 يمكنك الحصول على سجل الإضافة الحالية التي يستخدمها <code>plugman</code> أو تعيين عنوانها. لكن يجب عليك عمومًا تركه عند القيمة <code><nowiki>http://registry.cordova.io</nowiki></code>، إلا إن كنت ترغب في استخدام سجل إضافة من طرف ثالث.
 <syntaxhighlight lang="console">plugman config set registry <url-to-registry>
-plugman config get registry‎</syntaxhighlight>
+plugman config get registry
+</syntaxhighlight>
 === الحصول على معلومات عن الإضافات ===