الملف Plugin.xml في كوردوفا
يحدد الملف Plugin.xml بنية وإعدادات الإضافة. ويحتوي على العديد من العناصر التي يمكن استخدامها لتحديد تفاصيل الإضافة.
plugin
العنصر plugin هو العنصر الجذري (top-level) لبيان (manifest) الإضافة.
| الخاصيات (النوع)
فقط للمنصة: |
الوصف |
|---|---|
xmlns (سلسلة نصية)
|
مطلوب
مجال اسماء (namespace) الإضافة، |
id (سلسلة نصية)
|
مطلوب
مُعرف نمط (style identifier) مدير الحُزم npm الخاص بالإضافة. |
version (سلسلة نصية)
|
مطلوب
رقم إصدار الإضافة. يمكن اعتماد صياغة الإصدار الرمزي Semver. |
مثال:
<?xml version="1.0" encoding="UTF-8"?>
<plugin xmlns="http://apache.org/cordova/ns/plugins/1.0"
xmlns:android="http://schemas.android.com/apk/res/android"
id="my-plugin-id"
version="1.0.2">
engines و engine
تحدد العناصر الفرعية من العنصر<engines> إصدارات بيئات العمل المستندة إلى Apache Cordova، والتي تدعمها هذه الإضافة. ستعيد واجهة سطر الأوامر عند الخروج قيمةً غير معدومة لكل الإضافات التي لا يلبي مشروعها المستهدف القيود المحددة من طرف الوسم engine. في حال عدم تحديد أي وسم، فستحاول واجهة سطر الأوامر التثبيت في مجلد مشروع كوردوفا المحدد بطريقة عمياء.
ملاحظة: في الإصدار Cordova 6.1.0 وما بعده، المكان الموصى به لتحديد المنصة أو الإضافة أو ارتباطات (dependencies) واجهة سطر الأوامر هو الملف package.json الخاص بالإضافة. انظر صفحة تحديد ارتباطات كوردوفا لمزيد من المعلومات.
| الخاصيات (النوع)
فقط للمنصة: |
الوصف |
|---|---|
name (سلسلة نصية)
|
مطلوب
تمثل هذه الخاصية اسم المحرك (engine). فيما يلي المحركات الافتراضية المدعومة:
يمكنك أيضًا تحديد إطار عمل مخصص إضافة للبيئات الافتراضية. |
version (سلسلة نصية)
|
مطلوب
إصدار إطار العمل اللازم حتى يتم تثبيته. الإصدار الرمزي (Semver) مدعوم. |
scriptSrc (سلسلة نصية)
|
لإطارات العمل المُخصصة فقط
مطلوب ملف البرنامج النصي الذي يُعلِم الأمر |
platform (سلسلة نصية)
|
لإطارات العمل المُخصصة فقط
مطلوب المنصات التي يدعمها إطار العمل خاصتك. يمكنك استخدام الحرف العام |
أمثلة
<engines>
<engine name="cordova-android" version="=1.8.0" />
</engines>
قد تحدد عناصر المحرك (Engine) أيضًا التطابقات غير المضبوطة باستخدام المحارف ">" و ">=" إلخ. وذلك لتجنب التكرار وتقليل أعباء الصيانة والمراجعة عند تحديث المنصة.
<engines>
<engine name="cordova-android" version=">=1.8.0" />
</engines>
كذلك تدعم وسوم <engine> افتراضيًا جميع المنصات التي تعمل عليها كوردوفا. تحديد الوسم engine يعني أنّ جميع إصدارات كوردوفا، وعلى كل المنصات، يجب أن تتطابق مع قيمة الخاصية version الواردة في الوسم engine. يمكنك أيضًا سرد قائمة من منصات محددة مع إصداراتها لتجاوز الاختيار العام للوسم engine:
<engines>
<engine name="cordova" version=">=1.7.0" />
<engine name="cordova-android" version=">=1.8.0" />
<engine name="cordova-ios" version=">=1.7.1" />
</engines>
مثال على بيئة عمل مخصصة:
<engines>
<engine name="my_custom_framework" version="1.0.0" platform="android" scriptSrc="path_to_my_custom_framework_version"/>
<engine name="another_framework" version=">0.2.0" platform="ios|android" scriptSrc="path_to_another_framework_version"/>
<engine name="even_more_framework" version=">=2.2.0" platform="*" scriptSrc="path_to_even_more_framework_version"/>
</engines>
name
يُستخدم الوسم name لتحديد اسم الإضافة. هذا الوسم لا يدعم (لحد الساعة) إعدادات اللغة المحلية.
مثال:
<name>Foo</name>
description
يُستخدم العنصر description لتحديد وصفٍ للإضافة. هذا العنصر لا يدعم (لحد الساعة) اللغات المحلية.
مثال:
<description>Foo plugin description</description>
author
يحتوي العنصر author على اسم مؤلف الإضافة.
مثال:
<author>Foo plugin author</author>
keywords
يحتوي العنصر keywords على كلمات رئيسية مفصولة بفواصل لوصف الإضافة.
مثال:
<keywords>foo,bar</keywords>
license
يُستخدم هذا العنصر لتحديد ترخيص الإضافة.
مثال:
<license>Apache 2.0 License</license>
asset
يُستخدم هذا العنصر لسرد الملفات أو المجلدات المراد نسخها إلى مجلد التطبيق www. عناصر <asset> المتشعبة في عناصر <platform> ستحدد أصول الويب (web assets) الخاصة بالمنصة.
الخاصيات(النوع)
فقط للمنصة: الوصف src (سلسلة نصية) مطلوب
تحدد هذه الخاصية المكان الذي يوجد فيه الملف أو المجلد في حزمة الإضافة، نسبةً إلى المستند plugin.xml. إن لم يكن الملف موجودًا في الموضع src المحدد، فستتوقف واجهة سطر الأوامر وستعكس عملية التثبيت، وستطلق تنبيهًا حول التعارض، ثم تخرج مع إعادة قيمة غير معدومة.
target (سلسلة نصية)
مطلوب
تحدد هذه الخاصية المكان الذي يجب أن يوجد فيه الملف أو المجلد في تطبيق كوردوفا، نسبةً إلى المجلد www. إن كان هناك ملف موجود سلفًا في الموضع المستهدف، فستتوقف واجهة سطر الأوامر، ثم ستعكس عملية التثبيت، وتطلق تنبيهًا حول التعارض، ثم ستخرج مع إعادة قيمة غير معدومة.
أمثلة
<!-- a single file, to be copied in the root directory -->
<asset src="www/foo.js" target="foo.js" />
<!-- a directory, also to be copied in the root directory -->
<asset src="www/foo" target="foo" />
يمكن أيضًا استهداف الأصول (Assets) في المجلدات الفرعية. سيؤدي هذا إلى إنشاء مجلد js/experimental داخل المجلد www، ما لم يكن موجودًا بالفعل، وسينسخ الملف new-foo.js ويعيد تسميته عند القيمة foo.js.
<asset src="www/new-foo.js" target="js/experimental/foo.js" />
js-module
تتضمن معظم الإضافات ملف جافااسكريبت واحدًا أو أكثر. يقابل كل وسم <js-module> ملف جافااسكريبت، ويُعفي مستخدمي الإضافة من إضافة الوسم <script> لكل ملف. لا تقم بتغليف (wrap) الملف باستخدام cordova.define، إذ تتم إضافته تلقائيًا. يتم تغليف الوحدة في دالة مجهولة (closure)، مع الوحدة ، والتصدير (exports)، والاستيراد (require) في نطاق، كما هو معتاد في الوحدات غير المتزامنة AMD. تشعيب (Nesting) عناصر <js-module> ضمن الوسم <platform> سيُصرّح بارتباطات وحدة جافااسكريبت الخاصة بالمنصة.
الخاصيات(النوع)
فقط للمنصة:
الوصف
src (سلسلة نصية)
تحدد هذه الخاصية مرجعًا لملف في مجلد الإضافة نسبةً إلى الملف plugin.xml. إذا لم يتم حل src إلى ملف موجود، ستوقف واجهة سطر الأوامر التثبيت وتعكسه، وتطلق إشعارًا بالمشكلة، ثم تخرج مع إعادة قيمة غير معدومة.
name (سلسلة نصية)
يوفر الجزء الأخير من اسم الوحدة النمطية. يمكن أن يكون ما تريده عادةً، ولا يهمك إلا إن كنت تريد استخدام كوردوفا.require لاستيراد أجزاء أخرى من الإضافات في شفرة جافاا سكريبت. اسم الوحدة النمطية لـ <js-module> هو معرف الإضافة متبوعًا بقيمة الاسم.
مثال:
عند تثبيت الإضافة في المثال أدناه، يُنسخ الملف socket.js في المسار www/plugins/my-plugin-id/socket.js، ويُضاف في كمُدخلة (entry) إلى الملف www/cordova_plugins.js. في وقت التحميل، تستخدم الشيفرة البرمجية في الملف cordova.js الواجهة البرمجية XHR لقراءة كل الملفات وإدارج الوسم <script> في ملف HTML.
<js-module src="socket.js" name="Socket">
</js-module>
في هذا المثال أيضًا، باعتبار أن مُعرف (id) الإضافة يساوي chrome-socket، فسيكون اسم الوحدة هو chrome-socket.Socket.
clobbers
هذا الوسم مسموح به داخل العنصر <js-module>. وتستخدم لتحديد مجال الاسماء في الكائن window حيث يتم إدراج module.exports. يمكنك إدارج ما تشاء من وسوم <clobbers>. وسيتم إنشاء أي كائن غير متوفر في الكائن window.
الخاصيات (النوع)
فقط للمنصة: الوصف target (سلسلة نصية) مجال الأسماء حيث يتم إدراج module.exports.
مثال:
<js-module src="socket.js" name="Socket">
<clobbers target="chrome.socket" />
</js-module>
يُدرج module.exports هنا في الكائن window بحيث يمكن الوصول إليه بالتعبير window.chrome.socket.
merges
هذا الوسم مسموح به داخل العنصر <js-module>. ويُستخدم لتحديد مجال الاسماء المرتبط بالكائن window حيث يُدمج module.exports مع القيمة الموجودة. إذا كان هناك مفتاح موجود سلفًا، فسيتجاوز (overrides) إصدار الوحدة الإصدار الأصلي. يمكنك إدارج أي عدد تريد من الوسوم <merges>. الكائنات غير المتوفر في الكائن window سيتم إنشاؤها.
الخاصيات(النوع)
فقط للمنصة: الوصف target (سلسلة نصية) مجال الاسماء حيث يتم دمج module.exports.
مثال:
<js-module src="socket.js" name="Socket">
<merges target="chrome.socket" />
</js-module>
في هذا المثال يُدمج module.exports مع أي قيمة موجودة في window.chrome.socket.
runs
هذا الوسم مسموح به داخل العنصر <js-module>. إذ يستدعي ضرورة تحديد شيفرتك البرمجية عبر cordova.require، دون أن تكون مثبتة في كائن window. هذا مفيد عند تهيئة الوحدة ،أو إرفاق معالجات الأحداث (event handlers) و غير ذلك. يمكن استخدام وسم <runs/> واحد فقط. لاحظ أن تضمين <runs/> مع <clobbers/> أو <merges/> فيه تكرار، لأنهم يستوردون الوحدة عبر الأمر cordova.require.
مثال:
<js-module src="socket.js" name="Socket">
<runs/>
</js-module>
dependency
يسمح لك الوسم <dependency> بتحديد الإضافات الأخرى التي تعتمد عليها الإضافة الحالية. تتم الإشارة إلى الإضافات بواسطة معرفات مدير الحُزم npm، أو عن طريق عنوان مستودع github.
الخاصيات(النوع)
فقط للمنصة:
الوصف
id (سلسلة نصية)
توفر معرف الإضافة.
url (سلسلة نصية)
عنوان URL الخاص بالإضافة. يجب أن يشير هذا العنوان إلى مستودع git، والذي ستحاول واجهة سطر الأوامر استنساخه.
commit (سلسلة نصية)
مرجع لمستودع git مفهوم من قبل git checkout: فرع أو وسم (على سبيل المثال، master، 0.3.1)، أو تجزئة التزام commit hash (على سبيل المثال، 975ddb228af811dd8bb37ed1dfd092a3d05295f9).
subdir (سلسلة نصية)
تحدد هذه الخاصية أن ارتباطات الإضافة المستهدفة موجودة كمجلد فرعي في مستودع git. وهذا مفيد لأنه يسمح بأن يحتوي المستودع على العديد من الإضافات ذات الصلة، كل منها محددة بشكل فردي.
إذا قمت بتعيين url في الوسم <dependency> عند القيمة "." وقمت بتوفير subdir، فستُثبّت الإضافة المرتبطة من نفس مستودع git المحلي أو البعيد باغتبارها الإضافة الأم (parent plugin) التي تحدد الوسم <dependency>.
لاحظ أن subdir تحدد دومًا مسارًا نسبة إلى جذر المستودع git، وليس الإضافة الأم. يبفى هذا صحيحًا حتى لو قمت بتثبيت الإضافة عبر مسار محلي موجه مباشرة إليه.ستجد واجهة سطر الأوامر جذر مستودع git، ثم ستجد الإضافة الأخرى من هناك.
version (سلسلة نصية)
إصدار الإضافة المعتمد عليها. الإصدار الرمزي (Semver) مدعوم.
أمثلة
<dependency id="cordova-plugin-someplugin" url="https://github.com/myuser/someplugin" commit="428931ada3891801" subdir="some/path/here" />
<dependency id="cordova-plugin-someplugin" version="1.0.1">
platform
يعرّف هذا الوسم المنصات التي لها أكواد برمجية أصلية مرتبطة بها، أو تتطلب تعديلات على ملفات الإعدادات الخاصة بها. يمكن للأدوات التي تستخدم هذه المواصفات التعرف على المنصات المدعومة وتثبيت الشيفرة البرمجية في مشروعات كوردوفا. الإضافات التي ليس لها وسوم <platform> يُفترض أن تكون بلغة جافااسكريبت فقط، وبالتالي ستكون قابلة للتثبيت على كل المنصات.
الخاصيات(النوع)
فقط للمنصة: الوصف name (سلسلة نصية) مطلوب القيم المسموح بها: ios و android و windows و browser و osx تجعل هذه الخاصية المنصة مدعومة، مع ربط العنصرالفرعي (element's children) بتلك المنصة.
مثال:
<platform name="android">
<!-- android-specific elements -->
</platform>
source-file
نحدبد الشيفرة المصدرية القابلة للتنفيذ التي يجب تثبيتها في المشروع. الخاصيات(النوع)
فقط للمنصة:
الوصف
src (سلسلة نصية)
مطلوب
موقع الملف نسبةً إلى الملف plugin.xml. إذا تعذر العثور على الملف src، فستوقف واجهة سطر الأوامر التثبيت وتعكسه، وتطلق تنبيهًا حول المشكلة، ثم تخرج مع إعادة قيمة غير معدومة.
target-dir (سلسلة نصية)
المجلد الذي يجب أن تُنسخ الملفات فيه، نسبةً إلى جذر مشروع كوردوفا. من الناحية العملية، يعد هذا أكثر أهمية للمنصات القائمة على جافاا، حيث يجب وضع الملفات الموجودة في الحزمة com.alunny.foo داخل المجلد com/alunny/foo. بالنسبة للمنصات التي لا يكون للمجلد المصدري أهمية كبيرة، فيجب حذف هذه الخاصية.
framework (قيمة منطقية)
القيمة الافتراضية: false
عند تعيين هذه الخاصية عند القيمة true، فستضيف أيضًا الملف المحدد كإطار عمل للمشروع.
compiler-flags (سلسلة نصية) في حال تعيين هذه الخاصية، فستعيّن رايات المُصرّف (compiler flags) المحددة الملف المصدري المحدد.
أمثلة:
<!-- android -->
<source-file src="src/android/Foo.java" target-dir="src/com/alunny/foo" />
<!-- ios -->
<source-file src="src/ios/CDVFoo.m" />
<source-file src="src/ios/someLib.a" framework="true" />
<source-file src="src/ios/someLib.a" compiler-flags="-fno-objc-arc" />
header-file
هذا الوسم يشبه <source-file>، ولكنه مخصص للمنصات مثل iOS و Android، التي تميز بين الملفات المصدرية (source files)، والمفات الرئيسية (headers) والموارد. هذا الوسم غير مدعو من قبل ويندوز.
الخاصيات(النوع)
فقط للمنصة:
الوصف
src (سلسلة نصية)
مطلوب
موقع الملف نسبةً إلى plugin.xml. إذا تعذر العثور على الملف src، فستوقف واجهة سطر الأوامر التثبيت وتعكسه، وتطلق تنبيهًا حول المشكلة، ثم تخرج مع إعادة قيمة غير معدومة.
target-dir (سلسلة نصية)
المجلد حيث يجب نسخ الملفات، يُحدد نسبةُ إلى جذر مشروع كوردوفا.
مثال:
لمنصة iOS:
<header-file src="CDVFoo.h" />
resource-file
هذا الوسم يشبه <source-file>، ولكنه مخصوص بمنصات مثل iOS و Android التي تميز بين الملفات المصدرية والمفات الرئيسية والموارد.
الخاصيات(النوع)
فقط للمنصة:
الوصف
src (سلسلة نصية)
مطلوب
موقع الملف بالنسبة إلى plugin.xml. إذا تعذر العثور على الملف src، فستوقف واجهة سطر الأوامر التثبيت وتعكسه، وتطلق تنبيهًا حول المشكلة، ثم تخرج مع إعادة قيمة غير معدومة.
target (سلسلة نصية)
المسار حيث سيُنسخ الملف داخل المجلد خاصتك.
arch (سلسلة نصية)
القيم المسموح بها: x86 أو x64 أو ARM.
تشير هذه الخاصية إلى أنه يجب ألا يتم تضمين الملف إلا عند بناء الهيكل (architecture) المحددة.
device-target
القيم المسموح بها: win (أو windows) أو phone أو all.
تشير هذه الخاصية إلى أنه لا ينبغي تضمين الملف إلا عند البناء لأجل نوع الجهاز المستهدف.
versions
تشير هذه الخاصية إلى أنه لا ينبغي تضمين الملف إلا عند البناء لأجل الإصدارات التي تطابق سلسلة النصية المحددة. قيمة هذه الخاصية يمكن أن تكون أي سلسلة نصية تحدد مجالًا لإصدار دلالي (node semantic version) صالح.
reference
تشير هذه الخاصية إلى أنه يجب الرجوع إلى الملف من src بدلاً من نسخه إلى الوجهة المستهدفة. سيظهر الملف في Visual Studio مع اسم الملف المحدد من طرف target، ولكنه سيشير إلى src المقابل، بحسب الهيكل (architecture).
أمثلة:
لأجهزة الأندرويد:
<resource-file src="FooPluginStrings.xml" target="res/values/FooPluginStrings.xml" />
لويندوز:
<resource-file src="src/windows/win81/MobServices.pri" target="win81\MobServices.pri" device-target="windows" versions="8.1" arch="x64"/>
<!-- Example of referencing -->
<resource-file src="x86/foo.dll" target="foo.dll" arch="x86" reference="true" />
<resource-file src="x64/foo.dll" target="foo.dll" arch="x64" reference="true" />
NOTE: يجب استخدام target الخطوط المائلة العكسية ("\") لتجنب الخطأ DEP2100 deploy في Visual Studio.
config-file
يحدد هذا الوسم ملف إعداد XML ليتم تعديله، ويحدد أين ينبغي أن يحدث التعديل في ذلك المستند، وما الذي ينبغي تعديله. هناك نوعان من الملفات تم اختبارها وتعديلها عبر هذا العنصر، وهما الملفان xml و plist. لا يسمح العنصر config-file إلا بإلحاق وسوم فرعية جديدة لشجرة مستند XML. الوسوم الفرعية هي عناصر XML حرفية ليتم إدراجها في الوثيقة المستهدفة.
الخاصيات(النوع)
فقط للمنصة:
الوصف
target (سلسلة نصية)
تحدد هذه الخاصية الملف المراد تعديله، والمسار نسبة لجذر مشروع كوردوفا. إن لم يكن الملف المحدد موجودًا، فستتجاهل الأداة التعديلات على الإعدادات وستستمر في التثبيت.
يمكن أن يتضمن الهدف المحرف العام (*). في هذه الحالة، ستبحث واجهة سطر الأوامر عوديًا (recursively) في بنية مجلد المشروع، وستستخدم أول تطابق.
على منصة iOS، لا يُعرف موقع ملفات الإعدادات المنسوبة إلى جذر مجلد المشروع، لذلك فإعطاء الخاصية target القيمة config.xml سيُترجم إلى cordova-ios-project/MyAppName/config.xml.
parent (سلسلة نصية)
محدد XPath يشير إلى أصل العناصر المراد إضافتها إلى ملف الإعداد. إن استخدمت محددًا مطلقًا (absolute selectors)، فيمكنك استخدام المحرف العام (*) لتحديد العنصر الجذري، على سبيل المثال، /*/plugins. إذا لم يتم حل المحدد إلى وسم فرعي (child) من المستند المحدد، فستوقف الأداة عملية التثبيت وتعكسها، وتطلق تنبيًها، ثم تخرج وتعيد قيمة غير معدومة.
بالنسبة لملفات plist، تحدد الخاصية parent المفتاح الأصلي (parent key) الذي ينبغي أن يُدرج فيه عنصر XML المحدد.
after (سلسلة نصية)
قائمة مرتبة حسب الأولوية للوسوم الإخوة (siblings) المقبولة التي ينبغي إضافة مقتطف XML بعدها. هذه الخاصية مفيدة لتحديد التغييرات في الملفات التي تتطلب ترتيبًا صارمًا لعناصر XML، كما هو الحال في this.
device-target (سلسلة نصية)
القيم المسموح بها: win و phone و all.
هذه الخاصية قابلة للتطبيق عند التأثير على اسم الاسم الوصفي package.appxmanifest، تشير هذه الخاصية إلى أنه يجب ألا يُعدّل الملف إلا عند البناء لأجل نوع الجهاز المستهدف المحدد.
versions (سلسلة نصية)
تُطبق هذه الخاصية عند التأثير على الاسم الوصفي package.appxmanifest، تشير هذه الخاصية إلى أنه يجب ألا تُعدّل ملفان بيان (manifests) التطبيق الخاصة بإصدارات ويندوز المحددة إلا في الإصدارات التي تطابق السلسلة النصية في الخاصية versions. يمكن أن تكون القيمة أي سلسلة نصية تحتوي مجالًا صالحًا للإصدارات الدلالية (semantic version).
أمثلة:
بالنسبة لـ XML:
<config-file target="AndroidManifest.xml" parent="/manifest/application">
<activity android:name="com.foo.Foo" android:label="@string/app_name">
<intent-filter>
</intent-filter>
</activity>
</config-file>
بالنسبة لـ plist:
<config-file target="*-Info.plist" parent="CFBundleURLTypes">
<array>
<dict>
<key>PackageName</key>
<string>$PACKAGE_NAME</string>
</dict>
</array>
</config-file>
بالنسبة للخاصيات المخصوصة بويندوز:
<config-file target="package.appxmanifest" parent="/Package/Capabilities" versions="<8.1.0">
<Capability Name="picturesLibrary" />
<DeviceCapability Name="webcam" />
</config-file>
<config-file target="package.appxmanifest" parent="/Package/Capabilities" versions=">=8.1.0" device-target="phone">
<DeviceCapability Name="webcam" />
</config-file>
المثال أعلاه سيجعل المنصات السابقة للإصدار 8.1 (ويندوز 8، على وجه التحديد) مُطالبة باستيراد مكتبة webcam والمكتبة العامة picturesLibrary، مع تطبيق مكتبة الجهاز webcam حصريًا على مشاريع ويندوز 8.1 التي تُبنى لأجل Windows Phone. أما منصات Windows 8.1 المكتبية فلا تُعدل.
edit-config
هذا الوسم مشابهٌ للوسم config-file، يعرّف edit-config ملف إعداد XML المراد تعديله، وأين ينبغي إجراء التعديل في ذلك المفد، وما الذي يجب تعديله. بدلاً من إلحاق وسوم فرعية (children) جديدة لشجرة مستند XML، يقوم edit-config بإجراء تعديلات على خاصيات عناصر XML. هناك وضعان سيحددان نوع التعديل الذي سيُجرى على الخاصيات، وهما merge و overwrite. الوسم edit-config لديه وسم فرعي واحد، والذي سيحتوي على الخاصيات المراد إضافتها.
الخاصيات(النوع)
فقط للمنصة:
الوصف
file (سلسلة نصية)
الملف المراد تعديله، والمسار نسبة إلى المجلد الجذري لمشروع كوردوفا. إن لم يكن الملف المحدد موجودا، فستتجاهل الأداة تغييرات الإعدادات وستستمر في عملية التثبيت.
يمكن أن يتضمن الهدف عناصر عامة (*). في هذه الحالة، ستبحث واجهة سطر الأوامر عوديًا (recursively) في مجلد المشروع، وستستخدم أول تطابق.
على منصة iOS، لا يُعرف موقع ملفات الإعداد نسبةً إلى المجلد الجذري للمشروع، لذلك فتحديد الهدف عند القيمة config.xml سينتج عنه cordova-ios-project/MyAppName/config.xml.
target (سلسلة نصية)
محدد XPath يشير إلى العنصر المستهدف المراد تعديل خاصياته. إن كنت تستخدم محددات مطلقة (absolute selectors)، فيمكنك استخدام محرف عام (*) لتحديد العنصر الجذري (root element)، على سبيل المثال، /*/plugins. إذا لم تكن نتيجة حل المُحدد وسمًا فرعيًا (child) من المستند المحدد، فستوقف الأداة عملية التثبيت وتعكسها، وتطلق تنبيهًا، ثم ستخرج مع إعادة قيمة غير معدومة.
mode (سلسلة نصية)
تعيّن هذه الخاصية الوضع الذي سيحدد نوع التعديلات التي سيتم إجراؤها على الخاصيات.
merge - يضيف هذا الوضع الخاصيات المحددة إلى العنصر المستهدف. سيتم استبدال قيم الخاصيات إن كانت الخاصيات المحددة موجودة سلفًا في العنصر المستهدف.
overwrite - يستبدل هذا الوضع كل الخاصيات في العنصر المستهدف بالخاصيات المحددة.
مثال:
<!-- plugin-1 -->
<edit-config file="AndroidManifest.xml" target="/manifest/uses-sdk" mode="merge">
<uses-sdk android:minSdkVersion="16" android:maxSdkVersion="23" />
</edit-config>
<edit-config file="AndroidManifest.xml" target="/manifest/application/activity[@android:name='MainActivity']" mode="overwrite">
<activity android:name="MainActivity" android:label="NewLabel" android:configChanges="orientation|keyboardHidden" />
</edit-config>
AndroidManifest.xml قبل إضافة plugin-1:
<manifest android:hardwareAccelerated="true" android:versionCode="1" android:versionName="0.0.1" package="io.cordova.hellocordova" xmlns:android="http://schemas.android.com/apk/res/android">
...
<activity android:configChanges="orientation|keyboardHidden|keyboard|screenSize|locale" android:label="@string/activity_name" android:launchMode="singleTop" android:name="MainActivity" android:theme="@android:style/Theme.DeviceDefault.NoActionBar" android:windowSoftInputMode="adjustResize">
...
</activity>
...
<uses-sdk android:minSdkVersion="14" android:targetSdkVersion="23" />
</manifest>
AndroidManifest.xml بعد إضافة plugin-1:
<manifest android:hardwareAccelerated="true" android:versionCode="1" android:versionName="0.0.1" package="io.cordova.hellocordova" xmlns:android="http://schemas.android.com/apk/res/android">
...
<activity android:configChanges="orientation|keyboardHidden" android:label="NewLabel" android:name="MainActivity">
...
</activity>
...
<uses-sdk android:maxSdkVersion="23" android:minSdkVersion="16" android:targetSdkVersion="23" />
</manifest>
إدارة تعارضات edit-config
لا يمكن أن تعدل أكثر من إضافة واجدة نفس الخاصيات، لأنها قد تتسبب في مشاكل في التطبيق. وسيُطلق خطأ، ويفشل تثبيت الإضافة. يجب حل الوسوم المتعارضة edit-config قبل إضافة الإضافة. أدخل تعديلات على الوسوم المتعارضة لأجل حل التعارض، ثم أزل الإضافات المحدّثة وأعد إضافتها.
هناك خيار يمكن استخدامه إن أردت تثبيت الإضافة على الرغم من التعارضات. يمكن استخدام الراية --force مع الأمر cordova plugin add. وسيجبر كوردوفا على أن تضيف الإضافة، هذا سيؤدي إلى عكس التغييرات المتعارضة التي أجرتها الإضافات الأخرى لتجنب المشاكل. يجب استخدام --force بحذر، لأن عكس التغييرات التي أجرتها الإضافات الأخرى قد يتسبب بمشاكل في عمل التطبيق.
إن لاحظت وجود مشاكل في عمل الإضافات، فأزلها جميعًا ثم أعد إضافتها.
مثال:
لتفترض أن الإضافة plugin-1 الواردة أعلاه مثبتة بالفعل. محاولة تثبيت الإضافة plugin-2 أدناه ستؤدي إلى حدوث خطأ نظرًا لكون الإضافة plugin-1 قد عدّلت سلفًا العنصر uses-sdk الموجود في AndroidManifest.xml.
<!-- plugin-2 -->
<edit-config file="AndroidManifest.xml" target="/manifest/uses-sdk" mode="merge">
<uses-sdk android:minSdkVersion="15" />
</edit-config>
يمكن إضافة plugin-2 بطريقتين، وهما:
إحدى الطرق الممكنة لحل التعارضات هي إزالة الوسم edit-config من plugin-2 ودمجه في الوسم edit-config الخاص بالإضافة plugin-1 (على افتراض أن plugin-1 ليس لها أي مشكلة مع هذا التغيير). أزل كلا الإضافتين، ثم أعد إضافتهما مع هذه التغييرات. يُفترض أن تُضاف الإضافة plugin-2 بدون مشاكل هذه المرة.
إزالة edit-config من plugin-2 ودمجها في plugin-1:
<!-- plugin-1 -->
<edit-config file="AndroidManifest.xml" target="/manifest/uses-sdk" mode="merge">
<uses-sdk android:minSdkVersion="15" android:maxSdkVersion="23" />
</edit-config>
<edit-config file="AndroidManifest.xml" target="/manifest/application/activity[@android:name='MainActivity']" mode="overwrite">
<activity android:name="MainActivity" android:label="NewLabel" android:configChanges="orientation|keyboardHidden" />
</edit-config>
الملف AndroidManifest.xml الناتج بعد إزالة وإعادة إضافة كلا الإضافتين:
<manifest android:hardwareAccelerated="true" android:versionCode="1" android:versionName="0.0.1" package="io.cordova.hellocordova" xmlns:android="http://schemas.android.com/apk/res/android">
...
<activity android:configChanges="orientation|keyboardHidden" android:label="NewLabel" android:name="MainActivity">
...
</activity>
...
<uses-sdk android:maxSdkVersion="23" android:minSdkVersion="15" android:targetSdkVersion="23" />
</manifest>
الطريقة الثانية لإضافة plugin-2 تتضمن إضافة الإضافة مع الراية --force. سيتم التراجع عن التغييرات المتعارضة في edit-config من plugin-1 وسيتم تطبيق تغييرات plugin-2. الملف AndroidManifest.xml الناتج سيتضمن التغيير uses-sdk من plugin-2 والتغيير activity من plugin-1. لاحظ أنه تم تجاوز التغيير uses-sdk وحده من plugin-1 لأنه التغيير الوحيد المتعارض.
الملف AndroidManifest.xml الناتج بعد فرض إضافة plugin-2:
<manifest android:hardwareAccelerated="true" android:versionCode="1" android:versionName="0.0.1" package="io.cordova.hellocordova" xmlns:android="http://schemas.android.com/apk/res/android">
...
<activity android:configChanges="orientation|keyboardHidden" android:label="NewLabel" android:name="MainActivity">
...
</activity>
...
<uses-sdk android:minSdkVersion="15" android:targetSdkVersion="23" />
</manifest>
ملاحظة: التغييرات المعكوسة عبر الراية --force ستُفقد بشكل دائم. ولن تعود بعد إزالة الإضافة الذي أُضيفت بالقوة. إن كنت ستحتاج التغييرات المعكوسة، فينبغي إزالة جميع الإضافات المرتبطة وإعادة إضافتها.
plugins-plist
يحدد هذا الوسم مفتاحًا (key) وقيمة لإلحاقهما بالملف AppInfo.plist الصحيح في مشروع iOS Cordova. هذا الوسم صار مُتجاوزًا، لأنه لا ينطبق إلا على cordova-ios 2.2.0 وما قبله. استخدم الوسم <config-file> لإصدارات كوردوفا الأحدث.
مثال:
<plugins-plist key="Foo" string="CDVFoo" />
lib-file
الوسم lib-file يشبه الملفات المصدرية (source)، والموارد (resource)، والملفات الرئيسية (header files)، ولكنه مخصوص بمنصات مثل BlackBerry 10 التي تستخدم المكتبات التي ينشئها المستخدم. بالنسبة لمنصة ويندوز، يسمح الوسم <lib-file> بتضمين العنصر <SDKReference> في ملفات مشروع ويندوز التي تم إنشاؤها.
الخاصيات(النوع)
فقط للمنصة:
الوصف
src (سلسلة نصية)
مطلوب
موقع الملف نسبةً إلى الملف plugin.xml. إذا تعذر العثور على src، فستوقف واجهة سطر الأوامر التثبيت وتعكسه، وتصدر تنبيهًا بشأن المشكلة، ثم تخرج مع إعادة قيمة غير معدومة.
بالنسبة لمنصة ويندوز، فهذه الخاصية تشير إلى اسم إطار العمل SDK المراد تضمينها (والذي ستُستخدم كقيمة للخاصية Include الخاصة بالعنصر المولد <SDKReference>).
arch (سلسلة نصية)
تمثل هذه الخاصية البنية (architecture) التي بُنِي الملف .so على أساسها، والتي ستكون إما device أو simulator.
بالنسبة لمنصة ويندوز، هذه الخاصية ستشير إلى أنه لا يجب تضمين العنصر <SDKReference> إلا عند البناء لأجل البنية المحددة. القيم المدعومة هي x86 أو x64 أو ARM.
device-target (سلسلة نصية)
القيم المسموح بها: win (أو windows) أو phone أو all.
تشير هذه الخاصية إلى أنه لا يجب تضمين العنصر <SDKReference> إلا عند البناء لأجل نوع الجهاز المحدد.
versions (سلسلة نصية)
تشير هذه الخاصية إلى أنه لا يجب تضمين <SDKReference> إلا عند البناء لأجل الإصدارات التي تطابق السلسلة النصية المحددة. قيمة هذه الخاصية قد تكون أي سلسلة نصية تحتوي مجال إصدارات دلالية (semantic version range) صالحة
بالنسبة للأندرويد، يُستخدم العنصر <lib-file> لتثبيت الملفات .jar في المشروع libs directory. ولا يدعم إلا الخاصية src التي تحتوي على المسار النسبي لملف .jar.
أمثلة:
<lib-file src="src/BlackBerry10/native/device/libfoo.so" arch="device" />
<lib-file src="src/BlackBerry10/native/simulator/libfoo.so" arch="simulator" />
لويندوز:
<lib-file src="Microsoft.WinJS.2.0, Version=1.0" arch="x86" />
<lib-file src="Microsoft.WinJS.2.0, Version=1.0" versions=">=8.1" />
<lib-file src="Microsoft.WinJS.2.0, Version=1.0" target="phone" />
<lib-file src="Microsoft.WinJS.2.0, Version=1.0" target="win" versions="8.0" arch="x86" />
framework
يحدد هذ الوسم الإطار (عادة ما يكون جزءًا من نظام التشغيل أو المنصة) الذي تعتمد عليه الإضافة. الخاصيات(النوع)
فقط للمنصة:
الوصف
src (سلسلة نصية)
مطلوب
تحدد هذه الخاصية اسم الإطار، أو المسار النسبي لإطارٍ مُضمّنٍ كجزء من ملفات الإضافات.
custom (قيمة منطقية)
توضح هذه الخاصية ما إذا كان الإطار مضمّنًا كجزء من ملفات الإضافات.
weak (قيمة منطقية)
القيمة الافتراضية: false
تبيّن ما إذا كان ينبغي أن يكون الإطار موصولًا بروابط ضعيفة (weakly linked).
type (سلسلة نصية)
تبيّن نوع الإطار المراد إضافته.
parent (سلسلة نصية)
القيمة الافتراضية: .
تضبط هذه الخاصية المسار النسبي إلى المجلد الذي يحتوي على المشروع الفرعي الذي تريد إضافة المرجع إليه. القيمة الافتراضية، .، تعني مشروع التطبيق.
arch (سلسلة نصية)
القيم المسموح بها: x86 أو x64 أو ARM.
تشير هذه الخاصية إلى أنه لا يجب تضمين الملف إلا عند البناء لأجل الهيكل (architecture) المحدد.
device-target (سلسلة نصية)
القيم المسموح بها: win (أو windows) أو phone أو all.
تشير هذه الخاصية إلى أنه لا يجب تضمين الإطار إلا عند البناء لأجل نوع الجهاز المحدد.
versions (سلسلة نصية)
تشير هذه الخاصية إلى أنه لا يجب تضمين الإطار إلا عند البناء لأجل الإصدارات التي تطابق السلسلة النصية المحددة. يمكن أن تكون القيمة أي سلسلة نصية تحتوي مجالًا صالحًا للإصدارات الدلالية (semantic version).
target-dir (سلسلة نصية)
تشير هذه الخاصية إلى المجلد الفرعي الذي سيُنسخ فيه الإطار. من الناحية العملية، أهمية هذه الخاصية تتجلى عندما تحتوي الإضافة على إصدارات مختلفة للإطار، لمُختلف بنيات الشرائح (chip architectures) أو الأجهزة، ولكنها تشترك في نفس الاسم. تتيح لك هذه الخاصية تحديد مجلدات فرعية مختلفة لكل إصدارٍ من الإطار، بحيث لا تتداخل مع بعضها البعض.
implementation (سلسلة)
تعيّن هذه الخاصية المسار النسبي إلى الملف .dll الذي يحتوي على تقديم (implementation) المُكوِّن WinMD، المكتوب بلغة في C++.
spec (سلسلة نصية)
تُقرن هذه الخاصية بالخاصية type="podspec"، وتمثل السلسلة النصية التي تحتوي مواصفات CocoaPod التي تريد تثبيتها (المكتبة الثابتة فقط). CocoaPod ليست مدعومة إلا في cordova-ios 4.3.0 و cordova-cli 6.4.0. بالنسبة للإضافة الخاصة بك، تأكد من إضافة وسم <engine> المناسبة، و ارتباطات package.json الملف [../guide/hybrid/plugins/index.html#specifying-cordova-dependencies dependencies] لضمان التوافق مع الإصدارات السابقة.
embed (قيمة منطقية)
القيمة الافتراضية: false
تُقرن هذه الخاصية مع custom="true"، تُعطى هذه الخاصية القيمة true إن كنت ترغب في تضمين الإطار المخصص في حزمة التطبيق (app bundle)، بحيث يمكن تحميلها ديناميكيًا في وقت التشغيل (إطار ديناميكي). هذا سيضع إطارك المخصص في القسم "Embedded Binaries" في إعدادات مشروع Xcode. هذه الخاصية مدعومة فقط عند الجمع بين cordova-ios@4.4.0 و cordova-cli@7.0.0
أمثلة:
لمنصة iOS:
<framework src="libsqlite3.dylib" />
<framework src="social.framework" weak="true" />
<framework src="relative/path/to/my.framework" custom="true" />
<framework src="GoogleCloudMessaging" type="podspec" spec="~> 1.2.0" />
على منصة أندرويد (اعتبارًا من cordova-android@4.0.0)، يُستخدم الوسم framework لتضمين ارتباطات مُدير المشاريع Maven، أو لتضمين مشروعات المكتبة المجمعة.
<!-- Depend on latest version of GCM from play services -->
<framework src="com.google.android.gms:play-services-gcm:+" />
<!-- Depend on v21 of appcompat-v7 support library -->
<framework src="com.android.support:appcompat-v7:21+" />
<!-- Depend on library project included in plugin -->
<framework src="relative/path/FeedbackLib" custom="true" />
يمكن استخدام الوسم Framework أيضًا لتضمين الملفات .gradle المخصصة في الملف build.gradle الخاص بالمشروع الرئيسي:
<framework src="relative/path/rules.gradle" custom="true" type="gradleReference" />
على ويندوز، سيؤدي استخدام custom='true' و type='projectReference' إلى إضافة مرجع إلى المشروع، والذي سيُضاف إلى خطوتي الربط + التصريف (compile+link) لمشروع كوردوفا. هذه هي الطريقة الوحيدة حاليًا التي تُمكّن إطارًا مخصصًا من استهداف عدة بنيات (architectures)، حيث تُبنى بشكل صريح على شكل ارتباطات من قبل تطبيق كوردوفا الذي أنشأ المرجع.
<framework src="path/to/project/LibProj.csproj" custom="true" type="projectReference"/>
أمثلة على استخدام هذه الخاصيات المخصوصة بويندوز:
<framework src="src/windows/example.dll" arch="x64" />
<framework src="src/windows/example.dll" versions=">=8.0" />
<framework src="src/windows/example.vcxproj" type="projectReference" target="win" />
<framework src="src/windows/example.vcxproj" type="projectReference" target="all" versions="8.1" arch="x86" />
<framework src="src/windows/example.dll" target-dir="bin/x64" arch="x64" custom="true"/>
هذا مثال آخر على استخدام خاصيات مخصوصة بويندوز لإضافة مرجع إلى مكوّنات WinMD، المكتوبة بلغتي C# و C++، والتي ستكون واجهتها البرمجية (API) متاحة في وقت التشغيل:
<!-- C# component that consists of one .winmd file -->
<framework src="lib\windows\component.winmd" versions="<10.0" />
<!-- C++ component with separated metadata and implementation-->
<framework src="lib\windows\x86\cppcomponent.winmd"
implementation="lib\windows\x86\cppcomponent.dll"
target-dir="component\x86" arch="x86" versions=">=10.0" />
info
يحتوي هذا الوسم على معلومات إضافية لأجل تقديمها للمستخدمين. هذا مفيد عندما تحتاج إلى خطوات إضافية لا يمكن أتمتتها بسهولة، أو تتجاوز إمكانيات واجهة سطر الأوامر. تُطبع محتويات هذا الوسم عندما تثبّت واجهة سطر الأوامر الإضافة.
مثال:
<info>
You need to install __Google Play Services__ from the `Android Extras` section using the Android SDK manager (run `android`).
You need to add the following line to the `local.properties`:
android.library.reference.1=PATH_TO_ANDROID_SDK/sdk/extras/google/google_play_services/libproject/google-play-services_lib
</info>
hook
يمثل هذا الوسمُ برنامجك النصي (script) المخصص والذي سيٌستدعى من قبل كوردوفا عند وقوع حدثٍ معينٍ (على سبيل المثال، بعد إضافة الإضافة أو عند استدعاء سلسلة تحضير المنصة). هذا مفيد عندما تحتاج إلى توسيع وظائف كوردوفا. راجع صفحة [../guide/appdev/hooks/index.html Hooks Guide] لمزيد من المعلومات.
مثال:
<hook type="after_plugin_install" src="scripts/afterPluginInstall.js" />
uses-permission
في بعض الحالات، قد تحتاج الإضافة إلى إجراء تغييرات على الإعدادات اعتمادًا على التطبيق المستهدف. على سبيل المثال، للتسجيل في خدمة C2DM على أندرويد، سيتطلب التطبيق الذي يحمل رقم تعريفه my-app-id إذنًا على النحو التالي:
<uses-permission android:name="my-app-id.permission.C2D_MESSAGE"/>
في هذه الحالة، حيث لا يكون المحتوى المدرج من الملف plugin.xml معروفًا في وقت مبكر، فيمكن الإشارة إلى المتغيرات بعلامة الدولار ("$") متبوعة بسلسلة من الحروف الكبيرة، أو الأرقام، أو الشرطات السفلية. في المثال أعلاه، سيتضمن الملف plugin.xml هذا الوسم:
<uses-permission android:name="$PACKAGE_NAME.permission.C2D_MESSAGE"/>
تستبدل واجهة سطر الأوامر مراجع المتغيرات بالقيمة المحددة، أو بسلسلة نصية فارغة إذا لم يتم العثور عليها. قد تُرصد قيمة مرجع المتغير (في هذه الحالة، من الملف AndroidManifest.xml)، أو تُحدد من قبل مستخدم الأداة؛ تعتمد تفاصيل العملية على الأداة المستخدمة.
يمكن أن تطلب Plugman من المستخدمين تحديد المتغيرات المطلوبة في الإضافة. على سبيل المثال، يمكن تحديد مفاتيح الواجهة البرمجية لـ C2M ولخرائط Google كوسائط لسطر الأوامر:
plugman --platform android --project /path/to/project --plugin name|git-url|path --variable API_KEY=!@CFATGWE%^WGSFDGSDFW$%^#$%YTHGsdfhsfhyer56734
بعض أسماء المتغيرات محجوزة، مثل الاسم $PACKAGE_NAME. فهذا هو معرف نمط النطاق العكسي (reverse-domain style identifier) للحزمة، ويقابله CFBundleIdentifier على منصة iOS، والخاصية package في العنصر الجذري manifest في الملف AndroidManifest.xml.
preference
كما هو موضح في القسم السابق، قد تتطلب الإضافة أحيانًا من المستخدم تحديد قيمٍ لمتغيراته. لجعل تلك المتغيرات إلزامية، يجب أن يحتوي الوسم <platform> على وسم <preference>. تتحقق واجهة سطر الأوامر من أن هذه التفضيلات الإلزامية متوفرة. وإلا فينبغي أن تنبه المستخدم إلى كيفية تمرير المتغير، وتخرج مع إعادة قيمة مخالفة للصفر. يمكن الإشارة إلى التفضيلات في أماكن أخرى في الملف plugin.xml باستخدام الصياغة $PREFERENCE_NAME.
الخاصيات(النوع)
فقط للمنصة: الوصف name (سلسلة نصية) مطلوب اسم المتغير. لا يمكن أن يحتوي إلا على الأحرف الكبيرة والأرقام والشرطات السفلية. default (سلسلة نصية) القيمة الافتراضية للمتغير. في حال تحديده، فستُستخدم قيمته، ولن يُطلق أي خطأ عندما لا يدخل المستخدم أي قيمة.
مثال:
<preference name="MY_CUSTOM_STRING" default="default-value" />
<!--
The preference may be referenced elsewhere in plugin.xml like so:
-->
<config-file target="./res/values/strings.xml" parent="/resources">
<string name="custom">$MY_CUSTOM_STRING</string>
</config-file>