الفرق بين المراجعتين ل"Cordova/plugin ref"

من موسوعة حسوب
اذهب إلى التنقل اذهب إلى البحث
سطر 34: سطر 34:
  
 
== <code>engines</code> و <code>engine</code> ==
 
== <code>engines</code> و <code>engine</code> ==
−
تحدد العناصر الفرعية من العنصر<code><engines></code> إصدارات بيئات العمل المستندة إلى Apache Cordova، والتي تدعمها هذه الإضافة. ستعيد [[Cordova/cli|واجهة سطر الأوامر]] عند الخروج قيمةً غير معدومة لكل الإضافات التي لا يلبي مشروعها المستهدف القيود المحددة من طرف الوسم <code>engine</code>. في حال عدم تحديد أي وسم، فستحاول [[Cordova/cli|واجهة سطر الأوامر]] التثبيت في مجلد مشروع كوردوفا المحدد بطريقة عمياء.   
+
تحدد العناصر الفرعية من العنصر<code><engines></code> إصدارات بيئات العمل المستندة إلى Apache Cordova، والتي تدعمها هذه الإضافة. ستعيد [[Cordova/cli|واجهة سطر الأوامر]] عند الخروج قيمةً غير معدومة لكل الإضافات التي لا يلبي مشروعها المستهدف القيود المحددة من طرف الوسم <code>engine</code>. في حال عدم تحديد أي وسم، فستحاول [[Cordova/cli|واجهة سطر الأوامر]] التثبيت في مجلد مشروع كوردوفا المحدد دون القيام بأي عملية تحقق.   
  
 
'''ملاحظة''': في الإصدار '''Cordova 6.1.0‎''' وما بعده، المكان الموصى به لتحديد المنصة أو الإضافة أو ارتباطات (dependencies) [[Cordova/cli|واجهة سطر الأوامر]] هو الملف <code>package.json</code> الخاص بالإضافة. انظر صفحة [https://cordova.apache.org/docs/en/latest/guide/hybrid/plugins/index.html#specifying-cordova-dependencies تحديد ارتباطات كوردوفا] لمزيد من المعلومات.   
 
'''ملاحظة''': في الإصدار '''Cordova 6.1.0‎''' وما بعده، المكان الموصى به لتحديد المنصة أو الإضافة أو ارتباطات (dependencies) [[Cordova/cli|واجهة سطر الأوامر]] هو الملف <code>package.json</code> الخاص بالإضافة. انظر صفحة [https://cordova.apache.org/docs/en/latest/guide/hybrid/plugins/index.html#specifying-cordova-dependencies تحديد ارتباطات كوردوفا] لمزيد من المعلومات.   
سطر 56: سطر 56:
  
 
* <code>android-sdk</code> (تعيد أعلى مستوى لواجهة أندرويد البرمجية المثبتة)  
 
* <code>android-sdk</code> (تعيد أعلى مستوى لواجهة أندرويد البرمجية المثبتة)  
−
* <code>windows-sdk</code> (تعيد إصدار إطار العمل الأصلية SDK الخاصة بويندوز)  
+
* <code>windows-sdk</code> (تعيد إصدار إطار العمل الأصلي SDK الخاص بويندوز)  
 
* <code>apple-xcode</code> (تعيد إصدار xcode)  
 
* <code>apple-xcode</code> (تعيد إصدار xcode)  
 
* <code>apple-ios</code> (تعيد أعلى إصدار مثبت من منصة iOS)  
 
* <code>apple-ios</code> (تعيد أعلى إصدار مثبت من منصة iOS)  
سطر 65: سطر 65:
 
|مطلوب  
 
|مطلوب  
  
−
إصدار  إطار العمل اللازم حتى يتم تثبيته. الإصدار الرمزي (Semver) مدعوم.  
+
إصدار  إطار العمل اللازم لكي يتم تثبيته. الإصدار الرمزي (Semver) مدعوم.  
 
|-
 
|-
 
|<code>scriptSrc</code> (سلسلة نصية)
 
|<code>scriptSrc</code> (سلسلة نصية)
سطر 92: سطر 92:
 
</engines>‎</syntaxhighlight>  
 
</engines>‎</syntaxhighlight>  
  
−
كذلك تدعم وسوم <code><engine></code> افتراضيًا جميع المنصات التي تعمل عليها كوردوفا. تحديد الوسم <code>engine</code> يعني أنّ جميع إصدارات كوردوفا، وعلى كل المنصات، يجب أن تتطابق مع قيمة الخاصية <code>version</code> الواردة في الوسم <code>engine</code>. يمكنك أيضًا سرد قائمة من منصات محددة مع إصداراتها لتجاوز الاختيار العام للوسم <code>engine</code>:  
+
كذلك تدعم وسوم <code><engine></code> افتراضيًا جميع المنصات التي تعمل عليها كوردوفا. تحديد الوسم <code>engine</code> يعني أنّ جميع إصدارات كوردوفا، على كل المنصات، يجب أن تتطابق مع قيمة الخاصية <code>version</code> الواردة في الوسم <code>engine</code>. يمكنك أيضًا سرد قائمة من منصات محددة مع إصداراتها لتجاوز الاختيار العام للوسم <code>engine</code>:  
 
<syntaxhighlight lang="xml"><engines>
 
<syntaxhighlight lang="xml"><engines>
 
   <engine name="cordova" version=">=1.7.0" />
 
   <engine name="cordova" version=">=1.7.0" />
سطر 161: سطر 161:
 
<asset src="www/foo" target="foo" />‎</syntaxhighlight>  
 
<asset src="www/foo" target="foo" />‎</syntaxhighlight>  
  
−
يمكن أيضًا استهداف الأصول (Assets) في المجلدات الفرعية. وسيؤدي ذلك إلى إنشاء مجلد <code>js/experimental</code> داخل المجلد <code>www</code>، ما لم يكن موجودًا بالفعل، وسينسخ الملف <code>new-foo.js</code> ويعيد تسميته بالقيمة <code>foo.js</code>.  
+
يمكن أيضًا استهداف الأصول (Assets) في المجلدات الفرعية. وسيؤدي ذلك إلى إنشاء مجلد <code>js/experimental</code> داخل <code>www</code>، ما لم يكن موجودًا بالفعل، وسينسخ الملف <code>new-foo.js</code> وسيُعطى الاسم <code>foo.js</code>.  
 
<syntaxhighlight lang="xml"><asset src="www/new-foo.js" target="js/experimental/foo.js" />‎</syntaxhighlight>
 
<syntaxhighlight lang="xml"><asset src="www/new-foo.js" target="js/experimental/foo.js" />‎</syntaxhighlight>
  
 
== <code>js-module</code> ==
 
== <code>js-module</code> ==
−
معظم الإضافات تتضمن ملف [[JavaScript|جافاسكريبت]] واحدًا على الأقل. كل وسم <code><js-module></code> يقابل ملف [[JavaScript|جافاسكريبت]]، إذ يُعفي مستخدمي الإضافة من إضافة وسم <code><script></code> لكل ملف. لا تقم بتغليف (wrap) الملف عبر<code>cordova.define</code>، لأنه سيُضاف تلقائيًا. يتم تغليف الوحدة في دالة مجهولة (closure)، حيث module و exports واrequire في النطاق، كما هو معتاد في الوحدات غير المتزامنة AMD. تشعيب (Nesting) عناصر <code><js-module></code> ضمن الوسم <code><platform></code> سيُصرّح بارتباطات (bindings) وحدة [[JavaScript|جافاسكريبت]] الخاصة بالمنصة.  
+
معظم الإضافات تتضمن ملف [[JavaScript|جافاسكريبت]] واحدًا على الأقل. كل وسم <code><js-module></code> يقابل ملف [[JavaScript|جافاسكريبت]]، إذ يُعفي مستخدمي الإضافة من إضافة وسم <code><script></code> لكل ملف.
 +
 
 +
لا تقم بتغليف (wrap) الملف بواسطة <code>cordova.define</code>، لأنه سيُضاف تلقائيًا. يتم تغليف الوحدة في دالة مجهولة (closure)، حيث ستكون module و exports وrequire في النطاق، كما هو معتاد في الوحدات غير المتزامنة AMD.
 +
 
 +
تشعيب (Nesting) عناصر <code><js-module></code> ضمن الوسم <code><platform></code> سيُصرّح بارتباطات (bindings) وحدة [[JavaScript|جافاسكريبت]] الخاصة بالمنصة.  
 
{| class="wikitable"
 
{| class="wikitable"
 
!الخاصيات  (النوع)   
 
!الخاصيات  (النوع)   
سطر 173: سطر 177:
 
|-
 
|-
 
|<code>src</code> (سلسلة نصية)
 
|<code>src</code> (سلسلة نصية)
−
|تحدد هذه الخاصية مرجعًا لملف في مجلد الإضافة نسبةً إلى الملف <code>plugin.xml</code>. إذا لم يكن المسار المُستنتج من  <code>src</code> يشير إلى ملف موجود فعلًا، فستوقف [[Cordova/cli|واجهة سطر الأوامر]] التثبيت وتعكسه، وتطلق تنبيهًا بالمشكلة، ثم تخرج مع إعادة قيمة غير معدومة.
+
|تحدد هذه الخاصية مرجعًا لملف ما في مجلد الإضافة نسبةً إلى الملف <code>plugin.xml</code>. إذا لم يكن المسار المُستنتج من  <code>src</code> يشير إلى ملف موجود فعلًا، فستوقف [[Cordova/cli|واجهة سطر الأوامر]] التثبيت وتعكسه، وتطلق تنبيهًا بالمشكلة، ثم تخرج مع إعادة قيمة غير معدومة.
 
|-
 
|-
 
|<code>name</code> (سلسلة نصية)  
 
|<code>name</code> (سلسلة نصية)  
سطر 195: سطر 199:
 
|-
 
|-
 
|<code>target</code> (سلسلة نصية)
 
|<code>target</code> (سلسلة نصية)
−
|مجال الأسماء حيث يتم إدراج module.exports
+
|مجال الأسماء حيث يتم إدراج <code>module.exports</code>
 
|}مثال: <syntaxhighlight lang="xml"><js-module src="socket.js" name="Socket">
 
|}مثال: <syntaxhighlight lang="xml"><js-module src="socket.js" name="Socket">
 
   <clobbers target="chrome.socket" />
 
   <clobbers target="chrome.socket" />
سطر 203: سطر 207:
 
===<code>merges</code>===  
 
===<code>merges</code>===  
  
−
هذا الوسم مسموح به داخل العنصر <code><js-module></code>. ويُستخدم لتحديد مجال الاسماء المرتبط بالكائن <code>window</code> حيث يُدمج <code>module.exports</code> مع القيمة الموجودة. إذا كان هناك مفتاح (key) موجود سلفًا، فسيتجاوز (overrides) إصدارُ الوحدة الإصدارَ الأصلي. يمكنك إدارج أي عدد تريد من وسوم <code><merges></code>. الكائنات غير المتوفر في الكائن <code>window</code> سيتم إنشاؤها.   
+
هذا الوسم مسموح به داخل العنصر <code><js-module></code>. ويُستخدم لتحديد مجال الاسماء المرتبط بالكائن <code>window</code> حيث يُدمج <code>module.exports</code> مع القيمة الموجودة. إذا كان هناك مفتاح (key) موجود سلفًا، فسيتجاوز (overrides) إصدارُ الوحدة الإصدارَ الأصلي. يمكنك إدارج أي عدد تريد من وسوم <code><merges></code>. سيتم إنشاء الكائنات غير المتوفرة في الكائن <code>window</code>.   
 
{| class="wikitable"
 
{| class="wikitable"
 
!الخاصيات  (النوع)   
 
!الخاصيات  (النوع)   
سطر 219: سطر 223:
 
===<code>runs</code>===  
 
===<code>runs</code>===  
  
−
هذا الوسم مسموح به داخل العنصر <code><js-module></code>. ويستلزم ضرورة تحديد شيفرتك البرمجية عبر <code>cordova.require</code>، لكن دون أن تكون مثبتة في الكائن <code>window</code>. هذا مفيد عند تهيئة الوحدة، أو إرفاق معالجات الأحداث (event handlers) و غير ذلك. يمكن استخدام وسم <code><runs/></code> واحد فقط. لاحظ أن تضمين <code><runs/></code> مع <code><clobbers/></code> أو <code><merges/></code> فيه تكرار، لأنهم يستوردون الوحدة عبر الأمر <code>cordova.require</code>.  
+
هذا الوسم مسموح به داخل العنصر <code><js-module></code>. ويستلزم ضرورة تحديد شيفرتك البرمجية عبر <code>cordova.require</code>، لكن دون أن تكون مثبتة في الكائن <code>window</code>. هذا مفيد عند تهيئة الوحدة، أو عند إرفاق معالجات الأحداث (event handlers) و غير ذلك. يمكن استخدام وسم <code><runs/></code> واحد فقط. لاحظ أن تضمين <code><runs/></code> مع <code><clobbers/></code> أو <code><merges/></code> فيه تكرار، لأنها تستورد الوحدة عبر الأمر <code>cordova.require</code>.  
  
 
مثال:  
 
مثال:  
سطر 246: سطر 250:
 
|تبيّن هذه الخاصية أن ارتباطات الإضافة المستهدفة موجودة كمجلد فرعي في مستودع git. وهذا مفيد لأنه يسمح للمستودع بأن يحتوي على العديد من الإضافات ذات الصلة، بحيث تُحدد كلها  بشكل فردي.  
 
|تبيّن هذه الخاصية أن ارتباطات الإضافة المستهدفة موجودة كمجلد فرعي في مستودع git. وهذا مفيد لأنه يسمح للمستودع بأن يحتوي على العديد من الإضافات ذات الصلة، بحيث تُحدد كلها  بشكل فردي.  
  
−
إذا قمت بتعيين الخاصية <code>url</code> في الوسم <code><dependency></code> وإعطائها القيمة <code>"."،</code> وقمت بتحديد الخاصية <code>subdir</code>، فستُثبّت الإضافة المرتبطة من نفس مستودع git المحلي أو البعيد مثل الإضافة الأم (parent plugin) التي حددت الوسم <code><dependency></code>. لاحظ أن المسار الذي تحدده <code>subdir</code>  منسوب دائمًا  إلى جذر مستودع git، وليس الإضافة الأم.  هذا الأمر لن يتغير حتى لو قمت بتثبيت الإضافة عبر مسار محلي موجه مباشرة إليها. ستجد [[Cordova/cli|واجهة سطر الأوامر]] جذر مستودع git، ثم ستجد الإضافة الأخرى من هناك.
+
إذا قمت بتعيين الخاصية <code>url</code> في الوسم <code><dependency></code> وأعطيتها القيمة <code>"."،</code> وقمت بتحديد الخاصية <code>subdir</code>، فستُثبّت الإضافة المرتبطة من نفس مستودع git المحلي أو البعيد مثل الإضافة الأم (parent plugin) التي حددت الوسم <code><dependency></code>. لاحظ أن المسار الذي تحدده <code>subdir</code>  منسوب دائمًا  إلى جذر مستودع git، وليس الإضافة الأم.  هذا الأمر لن يتغير حتى لو قمت بتثبيت الإضافة عبر مسار محلي موجه مباشرة إليها. ستجد [[Cordova/cli|واجهة سطر الأوامر]] جذر مستودع git، ثم ستجد الإضافة الأخرى من هناك.
 
|-
 
|-
 
|<code>version</code> (سلسلة نصية)  
 
|<code>version</code> (سلسلة نصية)  
 
|إصدار الإضافة المعتمد عليها. الإصدار الرمزي (Semver) مدعوم.
 
|إصدار الإضافة المعتمد عليها. الإصدار الرمزي (Semver) مدعوم.
−
|}أمثلة: <syntaxhighlight lang="xml"><dependency id="cordova-plugin-someplugin" url="https://github.com/myuser/someplugin" commit="428931ada3891801" subdir="some/path/here" />
+
|}مثال على استخدام الوسم <code>dependency</code>: <syntaxhighlight lang="xml"><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">‎</syntaxhighlight>
 
<dependency id="cordova-plugin-someplugin" version="1.0.1">‎</syntaxhighlight>
  
سطر 267: سطر 271:
  
 
تجعل هذه الخاصية المنصة المحددة مدعومة، مع ربط العنصرالفرعي (element's children) بتلك المنصة.
 
تجعل هذه الخاصية المنصة المحددة مدعومة، مع ربط العنصرالفرعي (element's children) بتلك المنصة.
−
|}مثال: <syntaxhighlight lang="xml"><platform name="android">
+
|}مثال على استخدام الوسم <code>platform</code>: <syntaxhighlight lang="xml"><platform name="android">
−
   <!-- android-specific elements -->
+
   <!-- عناصر خاصة بأندرويد -->
 
</platform>‎</syntaxhighlight>
 
</platform>‎</syntaxhighlight>
  
سطر 297: سطر 301:
  
 
(ios)  
 
(ios)  
−
|في حال تعيين هذه الخاصية، فستعيّن رايات المُصرّف (compiler flags) الخاصة بالملف المصدري المحدد.
+
|هذه الخاصية ستعيّن رايات المُصرّف (compiler flags) الخاصة بالملف المصدري المحدد.
−
|}أمثلة: <syntaxhighlight lang="xml"><!-- android -->
+
|}مثال على استخدام الوسم <code>source-file</code>: <syntaxhighlight lang="xml"><!-- android -->
 
<source-file src="src/android/Foo.java" target-dir="src/com/alunny/foo" />
 
<source-file src="src/android/Foo.java" target-dir="src/com/alunny/foo" />
 
<!-- ios -->
 
<!-- ios -->
سطر 389: سطر 393:
 
|-
 
|-
 
|<code>parent</code> (سلسلة نصية)
 
|<code>parent</code> (سلسلة نصية)
−
|محدد XPath ‏(XPath selector‏) يشير إلى أصل (parent) العناصر المراد إضافتها إلى ملف الإعدادات. إن استخدمت محددًا مطلقًا (absolute selectors)، فيمكنك استخدام المحرف العام (<code>*</code>) لتحديد العنصر الجذري، على سبيل المثال، ‎<code>/*/plugins</code>. إن لم يكن يُشير إلى وسم فرعي (child) من المستند المحدد، فستوقف الأداة عملية التثبيت وتعكسها، وتطلق تنبيًها، ثم تخرج وتعيد قيمة غير معدومة.  
+
|محدد XPath ‏(XPath selector‏) يشير إلى أصل (parent) العناصر المراد إضافتها إلى ملف الإعدادات. إن استخدمت محددًا مطلقًا (absolute selectors)، فيمكنك استخدام المحرف العام (<code>*</code>) لتحديد العنصر الجذري، على سبيل المثال، ‎<code>/*/plugins</code>. إن لم يكن المحدد يُشير إلى وسم فرعي (child) من المستند المحدد، فستوقف الأداة عملية التثبيت وتعكسها، وتطلق تنبيًها، ثم تخرج وتعيد قيمة غير معدومة.  
  
 
بالنسبة لملفات <code>plist</code>، تحدد الخاصية <code>parent</code> المفتاح الأصلي (parent key) الذي ينبغي أن يُدرج فيه عنصر XML المحدد.
 
بالنسبة لملفات <code>plist</code>، تحدد الخاصية <code>parent</code> المفتاح الأصلي (parent key) الذي ينبغي أن يُدرج فيه عنصر XML المحدد.
 
|-
 
|-
 
|after (سلسلة نصية)  
 
|after (سلسلة نصية)  
−
|قائمة مرتبة حسب الأولوية للوسوم الإخوة (siblings) المقبولة التي ينبغي إضافة مقتطف XML بعدها. هذه الخاصية مفيدة لتحديد التغييرات في الملفات التي تتطلب ترتيبًا صارمًا لعناصر XML، كما هو الحال في [http://msdn.microsoft.com/en-us/library/windowsphone/develop/ff769509%28v=vs.105%29.aspx#BKMK_EXTENSIONSelement هنا].
+
|قائمة مرتبة حسب الأولوية للوسوم الإخوة (siblings) المقبولة التي ينبغي إضافة بيانات XML بعدها. هذه الخاصية مفيدة لتحديد التغييرات في الملفات التي تتطلب ترتيبًا صارمًا لعناصر XML، كما هو الحال [http://msdn.microsoft.com/en-us/library/windowsphone/develop/ff769509%28v=vs.105%29.aspx#BKMK_EXTENSIONSelement هنا].
 
|-
 
|-
 
|<code>device-target</code> (سلسلة نصية)
 
|<code>device-target</code> (سلسلة نصية)
سطر 401: سطر 405:
 
|القيم المسموح بها: <code>win</code> و <code>phone</code> و <code>all</code>.  
 
|القيم المسموح بها: <code>win</code> و <code>phone</code> و <code>all</code>.  
  
−
هذه الخاصية قابلة للتطبيق عند التأثير على  الاسم الوصفي <code>package.appxmanifest</code>، تشير هذه الخاصية إلى أنه يجب ألا يُعدّل الملف إلا عند القيام بالبناء لأجل نوع الجهاز المستهدف المحدد.  
+
هذه الخاصية قابلة للتطبيق عند التأثير على  الاسم الوصفي <code>package.appxmanifest</code>، تشير هذه الخاصية إلى ضرورة عدم تعديل الملف إلا عند القيام بالبناء لأجل نوع الجهاز المستهدف المحدد.  
 
|-
 
|-
 
|<code>versions</code> (سلسلة نصية)  
 
|<code>versions</code> (سلسلة نصية)  
  
 
(ويندوز)
 
(ويندوز)
−
|تُطبق هذه الخاصية عند التأثير على الاسم الوصفي <code>package.appxmanifest</code>، تشير هذه الخاصية إلى أنه يجب ألا تُعدّل ملفات بيان (manifests) التطبيق الخاصة بإصدارات ويندوز المحددة إلا في الإصدارات التي تطابق السلسلة النصية المُعيّنة في الخاصية <code>versions</code>. يمكن أن تكون القيمة أي سلسلة نصية تحتوي مجالًا صالحًا للإصدارات الدلالية (semantic version).
+
|تُطبق هذه الخاصية عند التأثير على الاسم الوصفي <code>package.appxmanifest</code>، تشير هذه الخاصية إلى ضرورة عدم تعديل ملفات بيان (manifests) التطبيق الخاصة بإصدارات ويندوز المحددة إلا في الإصدارات التي تطابق السلسلة النصية المُعيّنة في الخاصية <code>versions</code>. يمكن أن تكون قيمة هذه الخاصية أي سلسلة نصية تحتوي مجالًا صالحًا للإصدارات الدلالية (semantic version).
 
|}
 
|}
  
سطر 428: سطر 432:
 
</config-file>‎</syntaxhighlight>  
 
</config-file>‎</syntaxhighlight>  
  
−
بالنسبة للخاصيات الموجهة لويندوز:  
+
بالنسبة للخاصيات الخاصة بويندوز:  
 
<syntaxhighlight lang="xml"><config-file target="package.appxmanifest" parent="/Package/Capabilities" versions="&lt;8.1.0">
 
<syntaxhighlight lang="xml"><config-file target="package.appxmanifest" parent="/Package/Capabilities" versions="&lt;8.1.0">
 
     <Capability Name="picturesLibrary" />
 
     <Capability Name="picturesLibrary" />
سطر 437: سطر 441:
 
</config-file>‎</syntaxhighlight>  
 
</config-file>‎</syntaxhighlight>  
  
−
المثال أعلاه سيجعل المنصات السابقة للإصدار 8.1 (ويندوز 8، على وجه التحديد) مُطالبة باستيراد مكتبة <code>webcam</code> والمكتبة العامة <code>picturesLibrary</code>، مع تطبيق مكتبة الجهاز <code>webcam</code> حصريًا على مشاريع ويندوز 8.1 التي تُبنى لأجل Windows Phone. أما منصات Windows 8.1 المكتبية فلا تُعدَّل.  
+
المثال أعلاه سيجعل المنصات السابقة للإصدار 8.1 (ويندوز 8، على وجه التحديد) مُطالبة باستيراد مكتبة <code>webcam</code> والمكتبة العامة <code>picturesLibrary</code>، مع تطبيق مكتبة الجهاز <code>webcam</code> حصريًا على مشاريع ويندوز 8.1 التي تُبنى لأجل Windows Phone. أما منصات Windows 8.1 المكتبية فلن تُعدَّل.  
  
 
== <code>edit-config</code> ==
 
== <code>edit-config</code> ==
سطر 493: سطر 497:
 
=== إدارة تعارضات <code>edit-config</code> ===  
 
=== إدارة تعارضات <code>edit-config</code> ===  
  
−
لا يمكن أن تعدل أكثرُ من إضافة واحدة نفس الخاصيات، لأنها قد تتسبب في مشاكل في التطبيق. وسيُطلق خطأ، ويفشل تثبيت الإضافة. يجب حل الوسوم المتعارضة <code>edit-config</code> قبل إضافة الإضافة.   
+
لا يمكن أن تعدل أكثرُ من إضافة واحدة نفس الخاصيات، لأنها قد تتسبب في مشاكل في التطبيق. وسيُطلق خطأ ويفشل تثبيت الإضافة. لذلك يجب حل التعارض في وسوم <code>edit-config</code> قبل إضافة الإضافة.   
  
 
أدخل تعديلات على الوسوم المتعارضة لأجل حل التعارض، ثم أزل الإضافات المحدّثة وأعد إضافتها.  
 
أدخل تعديلات على الوسوم المتعارضة لأجل حل التعارض، ثم أزل الإضافات المحدّثة وأعد إضافتها.  
  
−
هناك خيار يمكن استخدامه إن أردت تثبيت الإضافة على الرغم من وجود التعارضات. يمكن استخدام الراية ‎<code>--force</code> مع الأمر <code>cordova plugin add</code>. وهذا سيجبر كوردوفا على أن تضيف الإضافة، وسيؤدي إلى عكس التغييرات المتعارضة التي أجرتها الإضافات الأخرى لأجل تجنب المشاكل.   
+
هناك خيار يمكن استخدامه إن أردت تثبيت الإضافة حتى بوجود تعارضات. يمكن استخدام الراية ‎<code>--force</code> مع الأمر <code>cordova plugin add</code>. وهذا سيجبر كوردوفا على أن تضيف الإضافة، وسيؤدي إلى عكس التغييرات المتعارضة التي أجرتها الإضافات الأخرى لأجل تجنب المشاكل.   
  
 
يجب استخدام الراية ‎<code>--force</code> بحذر، لأن عكس التغييرات التي أجرتها الإضافات الأخرى قد يتسبب بمشاكل في عمل التطبيق.  
 
يجب استخدام الراية ‎<code>--force</code> بحذر، لأن عكس التغييرات التي أجرتها الإضافات الأخرى قد يتسبب بمشاكل في عمل التطبيق.  
سطر 512: سطر 516:
 
يمكن إضافة <code>plugin-2</code> بطريقتين:  
 
يمكن إضافة <code>plugin-2</code> بطريقتين:  
  
−
الطريقة الأولى لحل التعارضات هي إزالة الوسم <code>edit-config</code> من الإضافة <code>plugin-2</code> ودمجه في الوسم <code>edit-config</code> الخاص بالإضافة <code>plugin-1</code> (على افتراض أن <code>plugin-1</code> ليس لها أي مشكلة مع هذا التغيير). أزل كلي الإضافتين، ثم أعد إضافتهما مع هذه التغييرات. يُفترض أن تُضاف الإضافة <code>plugin-2</code> بدون مشاكل هذه المرة.  
+
الطريقة الأولى لحل التعارضات هي إزالة الوسم <code>edit-config</code> من الإضافة <code>plugin-2</code> ودمجه في الوسم <code>edit-config</code> الخاص بالإضافة <code>plugin-1</code> (على افتراض أن <code>plugin-1</code> ليس لها أي مشكلة مع هذا التغيير). أزل كلا الإضافتين، ثم أعد إضافتهما مع هذه التغييرات. يُفترض أن تُضاف الإضافة <code>plugin-2</code> بدون مشاكل هذه المرة.  
  
 
إزالة الوسم <code>edit-config</code> من <code>plugin-2</code> ودمجه في <code>plugin-1</code>:  
 
إزالة الوسم <code>edit-config</code> من <code>plugin-2</code> ودمجه في <code>plugin-1</code>:  
سطر 523: سطر 527:
 
</edit-config>‎</syntaxhighlight>  
 
</edit-config>‎</syntaxhighlight>  
  
−
الملف <code>AndroidManifest.xml</code> الناتج بعد إزالة وإعادة إضافة كلي الإضافتين:  
+
الملف <code>AndroidManifest.xml</code> الناتج بعد إزالة وإعادة إضافة كلا الإضافتين:  
 
<syntaxhighlight lang="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">
 
<syntaxhighlight lang="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">
 
     ...
 
     ...
سطر 533: سطر 537:
 
</manifest>‎</syntaxhighlight>  
 
</manifest>‎</syntaxhighlight>  
  
−
الطريقة الثانية لإضافة <code>plugin-2</code> تتطلب أن تُضيف الإضافة مع الراية <code>--force</code>. سيتم التراجع عن التغييرات المتعارضة التي أجرتها الإضافة <code>plugin-1</code> في الوسم <code>edit-config</code> وسيتم تطبيق تغييرات <code>plugin-2</code>. الملف <code>AndroidManifest.xml</code> الناتج سيتضمن التغيير <code>uses-sdk</code> من <code>plugin-2</code> والتغيير <code>activity</code> من <code>plugin-1</code>. لاحظ أنه لم يتم تجاوز إلا التغيير <code>uses-sdk</code> وحده من بين تغييرات <code>plugin-1</code>، لأنه التغيير الوحيد المتعارض.  
+
الطريقة الثانية لإضافة <code>plugin-2</code> تتطلب أن تُضيف الإضافة مع الراية <code>--force</code>. سيتم التراجع عن التغييرات المتعارضة التي أجرتها الإضافة <code>plugin-1</code> في الوسم <code>edit-config</code> وسيتم تطبيق تغييرات <code>plugin-2</code>. الملف <code>AndroidManifest.xml</code> الناتج سيتضمن التغيير <code>uses-sdk</code> من <code>plugin-2</code> والتغيير <code>activity</code> من <code>plugin-1</code>. لاحظ أنه لم يتم تجاوز إلا التغيير <code>uses-sdk</code> وحده من بين التغييرات التي قامت بها الإضافة <code>plugin-1</code>، ذلك أنه التغيير الوحيد المتعارض.  
  
 
الملف <code>AndroidManifest.xml</code> الناتج بعد فرض إضافة <code>plugin-2</code>:  
 
الملف <code>AndroidManifest.xml</code> الناتج بعد فرض إضافة <code>plugin-2</code>:  
سطر 548: سطر 552:
  
 
== <code>plugins-plist</code> ==
 
== <code>plugins-plist</code> ==
−
يحدد هذا الوسم مفتاحًا (key) وقيمة لإلحاقهما بالملف <code>AppInfo.plist</code> الصحيح في مشروع iOS Cordova. هذا الوسم صار مُتجاوزًا، لأنه لا ينطبق إلا على الإصدار cordova-ios 2.2.0 وما قبله. استخدم الوسم <code><config-file></code> في إصدارات كوردوفا الأحدث.  
+
يحدد هذا الوسم مفتاحًا (key) وقيمة لإلحاقهما بالملف <code>AppInfo.plist</code> المناسب في مشروع iOS Cordova. هذا الوسم صار مُتجاوزًا، لأنه لا ينطبق إلا على الإصدار cordova-ios 2.2.0 وما قبله. استخدم الوسم <code><config-file></code> في إصدارات كوردوفا الأحدث.  
  
 
مثال:  
 
مثال:  
سطر 554: سطر 558:
  
 
== <code>lib-file</code> ==
 
== <code>lib-file</code> ==
−
الوسم lib-file يشبه الملفات المصدرية (source)، والموارد (resource)، والملفات الرئيسية (header files)، ولكنه مخصوص بمنصات مثل BlackBerry 10 التي تستخدم المكتبات المُولّدة من قبل المستخدم. بالنسبة لمنصة ويندوز، يسمح الوسم <code><lib-file></code> بتضمين العنصر <code><SDKReference></code> في ملفات مشروع ويندوز المُنشأة.  
+
الوسم <code>lib-file</code> يشبه الملفات المصدرية (sources)، والموارد (resources)، والملفات الرئيسية (header files)، ولكنه مخصوص بمنصات مثل BlackBerry 10 التي تستخدم المكتبات المُولّدة من قبل المستخدمين. بالنسبة لمنصة ويندوز، يسمح الوسم <code><lib-file></code> بتضمين العنصر <code><SDKReference></code> في ملفات مشروع ويندوز المُنشأة.  
 
{| class="wikitable"
 
{| class="wikitable"
 
!الخاصيات  (النوع)   
 
!الخاصيات  (النوع)   
سطر 587: سطر 591:
 
|توضح هذه الخاصية أنه لا يجب تضمين <code><SDKReference></code> إلا عند القيام بالبناء لأجل الإصدارات التي تطابق السلسلة النصية المحددة. قيمة هذه الخاصية قد تكون أي سلسلة نصية تحتوي مجال إصدارات دلالية (semantic version range) صالحة
 
|توضح هذه الخاصية أنه لا يجب تضمين <code><SDKReference></code> إلا عند القيام بالبناء لأجل الإصدارات التي تطابق السلسلة النصية المحددة. قيمة هذه الخاصية قد تكون أي سلسلة نصية تحتوي مجال إصدارات دلالية (semantic version range) صالحة
 
|}
 
|}
−
بالنسبة للأندرويد، يُستخدم العنصر <code><lib-file></code> لتثبيت الملفات ‎'''.jar''' في المجلد '''libs''' الخاص بالمشروع. ولا يدعم إلا الخاصية <code>src</code> التي تحتوي على المسار النسبي لملف‎ <code>.jar</code>.
+
بالنسبة للأندرويد، يُستخدم العنصر <code><lib-file></code> لتثبيت الملفات ‎'''<code>.jar</code>''' في المجلد '''<code>libs</code>''' الخاص بالمشروع. ولا يدعم إلا الخاصية <code>src</code> التي تحتوي على المسار النسبي لملف‎ <code>.jar</code>.
  
 
أمثلة:  
 
أمثلة:  
 
<syntaxhighlight lang="xml"><lib-file src="src/BlackBerry10/native/device/libfoo.so" arch="device" />
 
<syntaxhighlight lang="xml"><lib-file src="src/BlackBerry10/native/device/libfoo.so" arch="device" />
 
<lib-file src="src/BlackBerry10/native/simulator/libfoo.so" arch="simulator" />‎</syntaxhighlight>
 
<lib-file src="src/BlackBerry10/native/simulator/libfoo.so" arch="simulator" />‎</syntaxhighlight>
−
 
  
 
مثال لمنصة لويندوز:  
 
مثال لمنصة لويندوز:  
سطر 634: سطر 637:
 
|القيم المسموح بها: <code>x86</code> أو <code>x64</code> أو <code>ARM</code>.  
 
|القيم المسموح بها: <code>x86</code> أو <code>x64</code> أو <code>ARM</code>.  
  
−
توضح هذه الخاصية أنه لا يجب تضمين الملف إلا عند القيام بالبناء لأجل البنية (architecture) المحدد.
+
توضح هذه الخاصية أنه لا يجب تضمين الملف إلا عند القيام بالبناء لأجل البنية (architecture) المحددة.
 
|-
 
|-
 
|<code>device-target</code> (سلسلة نصية)
 
|<code>device-target</code> (سلسلة نصية)
سطر 656: سطر 659:
  
 
(ويندوز)
 
(ويندوز)
−
|تُعيّن هذه الخاصية المسار النسبي عند الملف <code>.dll</code> الذي يحتوي على تقديم (implementation) المُكوِّن WinMD المكتوب بلغة في C++‎.
+
|تُعيّن هذه الخاصية قيمة المسار النسبي عند الملف <code>.dll</code> الذي يحتوي على تقديم (implementation) المُكوِّن WinMD المكتوب بلغة في C++‎.
 
|-
 
|-
 
|<code>spec</code> (سلسلة نصية)
 
|<code>spec</code> (سلسلة نصية)
سطر 676: سطر 679:
  
 
=== أمثلة ===
 
=== أمثلة ===
−
مثال لمنصة iOS:  
+
مثال خاص بمنصة iOS:  
 
<syntaxhighlight lang="xml"><framework src="libsqlite3.dylib" />
 
<syntaxhighlight lang="xml"><framework src="libsqlite3.dylib" />
 
<framework src="social.framework" weak="true" />
 
<framework src="social.framework" weak="true" />
سطر 726: سطر 729:
 
يمثل هذا الوسمُ برنامجك النصي (script) المخصص، والذي سيٌستدعى من قبل كوردوفا عند وقوع حدثٍ معينٍ (على سبيل المثال، بعد إضافة الإضافة أو عند استدعاء سلسلة تحضير المنصة). هذا مفيد إن كنت تحتاج إلى توسيع وظائف كوردوفا. راجع صفحة [[Cordova/hooks|الخطافات]] لمزيد من المعلومات.  
 
يمثل هذا الوسمُ برنامجك النصي (script) المخصص، والذي سيٌستدعى من قبل كوردوفا عند وقوع حدثٍ معينٍ (على سبيل المثال، بعد إضافة الإضافة أو عند استدعاء سلسلة تحضير المنصة). هذا مفيد إن كنت تحتاج إلى توسيع وظائف كوردوفا. راجع صفحة [[Cordova/hooks|الخطافات]] لمزيد من المعلومات.  
  
−
مثال:  
+
مثال على استخدام الوسم <code>hook</code>:  
 
<syntaxhighlight lang="xml"><hook type="after_plugin_install" src="scripts/afterPluginInstall.js" />‎</syntaxhighlight>
 
<syntaxhighlight lang="xml"><hook type="after_plugin_install" src="scripts/afterPluginInstall.js" />‎</syntaxhighlight>
  
 
== <code>uses-permission</code> ==
 
== <code>uses-permission</code> ==
−
في بعض الحالات، قد تحتاج الإضافة إلى إجراء تغييرات على الإعدادات بحسب التطبيق المستهدف. على سبيل المثال، للتسجيل في خدمة C2DM على أندرويد، يتطلب التطبيق الذي يحمل رقم تعريفه <code>my-app-id</code> إذنًا على النحو التالي:  
+
في بعض الحالات، قد تحتاج الإضافة إلى إجراء تغييرات على الإعدادات بحسب التطبيق المستهدف. على سبيل المثال، للتسجيل في خدمة C2DM على أندرويد، سيتطلب التطبيق الذي يحمل رقم تعريفه <code>my-app-id</code> إذنًا على النحو التالي:  
 
<syntaxhighlight lang="xml"><uses-permission android:name="my-app-id.permission.C2D_MESSAGE"/>‎</syntaxhighlight>  
 
<syntaxhighlight lang="xml"><uses-permission android:name="my-app-id.permission.C2D_MESSAGE"/>‎</syntaxhighlight>  
  
−
في الحالة حيث لا يكون المحتوى المدرج من الملف <code>plugin.xml</code> معروفًا مُقدمًا، يمكن الإشارة إلى المتغيرات بعلامة الدولار ("$") متبوعة بسلسلة من الحروف الكبيرة، أو الأرقام، أو الشرطات السفلية. في المثال أعلاه، سيتضمن الملف <code>plugin.xml</code> هذا الوسم:  
+
في حال لم يكن المحتوى المدرج من الملف <code>plugin.xml</code> معروفًا مُقدمًا، يمكن الإشارة إلى المتغيرات بعلامة الدولار ("$") متبوعة بسلسلة من الحروف الكبيرة، أو الأرقام، أو الشرطات السفلية. في المثال أعلاه، سيتضمن الملف <code>plugin.xml</code> هذا الوسم:  
 
<syntaxhighlight lang="xml"><uses-permission android:name="$PACKAGE_NAME.permission.C2D_MESSAGE"/>‎</syntaxhighlight>  
 
<syntaxhighlight lang="xml"><uses-permission android:name="$PACKAGE_NAME.permission.C2D_MESSAGE"/>‎</syntaxhighlight>  
  
سطر 757: سطر 760:
 
|-
 
|-
 
|<code>default</code> (سلسلة نصية)
 
|<code>default</code> (سلسلة نصية)
−
|القيمة الافتراضية للمتغير. في حال تحديدها، فسيتم استخدامها، ولن يُطلق أي خطأ عندما لا يُدخل المستخدم أي قيمة.
+
|القيمة الافتراضية للمتغير. في حال تحديدها، فسيتم استخدامها، ولن يُطلق أي خطأ إذا لم يُدخل المستخدم أي قيمة.
 
|}
 
|}
  
 
مثال على استخدام الوسم <code>preference</code>: <syntaxhighlight lang="xml"><preference name="MY_CUSTOM_STRING" default="default-value" />
 
مثال على استخدام الوسم <code>preference</code>: <syntaxhighlight lang="xml"><preference name="MY_CUSTOM_STRING" default="default-value" />
 
<!--
 
<!--
−
     The preference may be referenced elsewhere in plugin.xml like so:
+
     plugin.xml التفضيلات يمكن أن توضع في أي مكان في الملف
 
-->
 
-->
 
<config-file target="./res/values/strings.xml" parent="/resources">
 
<config-file target="./res/values/strings.xml" parent="/resources">
سطر 770: سطر 773:
 
== انظر أيضا ==
 
== انظر أيضا ==
 
* صفحة <nowiki/>[[Cordova/hooks|الخطافات]].
 
* صفحة <nowiki/>[[Cordova/hooks|الخطافات]].
−
 
−
 
  
 
* صفحة <nowiki/>[[Cordova/config ref|الملف Config.xml]]
 
* صفحة <nowiki/>[[Cordova/config ref|الملف Config.xml]]
−
 
−
 
  
 
* صفحة <nowiki/>[[Cordova/cli|واجهة سطر الأوامر]].
 
* صفحة <nowiki/>[[Cordova/cli|واجهة سطر الأوامر]].

مراجعة 01:36، 10 ديسمبر 2018

يحدد الملف Plugin.xml بنية وإعدادات الإضافة. ويحتوي على العديد من العناصر التي يمكن استخدامها لتحديد تفاصيل الإضافة.

plugin

العنصر plugin هو العنصر الجذري (top-level) لبيان (manifest) الإضافة.

الخاصيات (النوع)

فقط للمنصة:

الوصف
xmlns (سلسلة نصية) مطلوب

مجال اسماء (namespace) الإضافة، http://apache.org/cordova/ns/plugins/1.0. إن كان المستند يحتوي على وُسوم XML من مجالات أسماء أخرى، مثل الوسوم المراد إضافتها إلى الملف AndroidManifest.xml في حالة استهداف المنصة أندرويد، فيجب أيضًا تضمين مجالات الأسماء تلك في العنصر.

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). فيما يلي المحركات الافتراضية المدعومة:

  • cordova
  • cordova-plugman
  • cordova-android
  • cordova-ios
  • cordova-windows
  • cordova-osx
  • windows-os
  • android-sdk (تعيد أعلى مستوى لواجهة أندرويد البرمجية المثبتة)
  • windows-sdk (تعيد إصدار إطار العمل الأصلي SDK الخاص بويندوز)
  • apple-xcode (تعيد إصدار xcode)
  • apple-ios (تعيد أعلى إصدار مثبت من منصة iOS)
  • apple-osx (تعيد إصدار OSX)

يمكنك أيضًا تحديد إطار عمل مخصص إضافة للبيئات الافتراضية.

version (سلسلة نصية) مطلوب

إصدار إطار العمل اللازم لكي يتم تثبيته. الإصدار الرمزي (Semver) مدعوم.

scriptSrc (سلسلة نصية) لإطارات العمل المُخصصة فقط

مطلوب

ملف البرنامج النصي الذي يُعلِم الأمر plugman بإصدار إطار العمل المخصص. يُفضل أن يكون هذا الملف ضمن المجلد الجذري في مجلد الإضافات.

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: 

<name>Foo</name>‎

description

يُستخدم الوسم description لتحديد وصفٍ للإضافة. هذا العنصر لا يدعم (لحد الساعة) اللغات المحلية.

مثال على استخدام الوسم description: 

<description>Foo plugin description</description>‎

author

يحتوي الوسم author على اسم مؤلف الإضافة.

مثال على استخدام الوسم author: 

<author>Foo plugin author</author>‎

keywords

يحتوي العنصرkeywords على كلمات رئيسية مفصولة بفواصل لوصف الإضافة.

مثال على استخدام الوسم keywords: 

<keywords>foo,bar</keywords>‎

license

يُستخدم هذا العنصر لتحديد ترخيص الإضافة.

مثال على استخدام الوسم license: 

<license>Apache 2.0 License</license>‎

asset

يُستخدم هذا العنصر لسرد الملفات أو المجلدات المراد نسخها في مجلد التطبيق www. عناصر <asset> المتشعبة (nested) داخل العنصر <platform> ستحدد أصول الويب (web assets) الخاصة بالمنصة.

الخاصيات (النوع)

فقط للمنصة:

الوصف
src (سلسلة نصية) مطلوب

تحدد هذه الخاصية المكان الذي يوجد فيه الملف أو المجلد في حزمة الإضافة نسبةً إلى المستند plugin.xml. إن لم يكن الملف موجودًا في الموضع src المحدد، فستتوقف واجهة سطر الأوامر وستعكس عملية التثبيت، وستطلق تنبيهًا حول وجود تعارض، ثم تخرج مع إعادة قيمة غير معدومة.

target (سلسلة نصية) مطلوب

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

أمثلة

<!-- ملف سيُنسخ داخل المجلد الجذري -->
<asset src="www/foo.js" target="foo.js" />
<!-- مجلد سيُنسخ داخل المجلد الجذري -->
<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)، حيث ستكون module و exports وrequire في النطاق، كما هو معتاد في الوحدات غير المتزامنة AMD.

تشعيب (Nesting) عناصر <js-module> ضمن الوسم <platform> سيُصرّح بارتباطات (bindings) وحدة جافاسكريبت الخاصة بالمنصة.

الخاصيات (النوع)

فقط للمنصة:

الوصف
src (سلسلة نصية) تحدد هذه الخاصية مرجعًا لملف ما في مجلد الإضافة نسبةً إلى الملف plugin.xml. إذا لم يكن المسار المُستنتج من src يشير إلى ملف موجود فعلًا، فستوقف واجهة سطر الأوامر التثبيت وتعكسه، وتطلق تنبيهًا بالمشكلة، ثم تخرج مع إعادة قيمة غير معدومة.
name (سلسلة نصية) توفر هذه الخاصية الجزء الأخير من اسم الوحدة. يمكن أن تعطيها أي قيمة تريد، وليس لذلك أهمية إلا إن كنت تريد استخدام cordova.require لاستيراد أجزاء أخرى من الإضافات في شيفرة جافاسكريبت. اسم وحدة <js-module> يساوي مُعرّف (id) الإضافة متبوعًا بقيمة الاسم.

مثال

عند تثبيت الإضافة في المثال أدناه، يُنسخ الملف 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>. ويُستخدم لتحديد مجال الاسماء (namespace) في الكائن 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 مع القيمة الموجودة. إذا كان هناك مفتاح (key) موجود سلفًا، فسيتجاوز (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: 

<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

يعرّف هذا الوسم المنصات التي لها أكواد برمجية أصلية (native code) مرتبطة بها، أو تتطلب تعديلات على ملفات الإعدادات الخاصة بها. يمكن للأدوات التي تستخدم هذه المواصفات التعرف على المنصات المدعومة وتثبيت الشيفرة البرمجية في مشروعات كوردوفا. الإضافات التي لا تستخدم وسوم <platform> يُفترض أن تكون بلغة جافاسكريبت فقط، وبالتالي ستكون قابلة للتثبيت على كل المنصات.

الخاصيات (النوع)

فقط للمنصة:

الوصف
name (سلسلة نصية) مطلوب

القيم المسموح بها هي: ios و android و windows و browser و osx

تجعل هذه الخاصية المنصة المحددة مدعومة، مع ربط العنصرالفرعي (element's children) بتلك المنصة.

مثال على استخدام الوسم platform: 

<platform name="android">
  <!-- عناصر خاصة بأندرويد -->
</platform>‎

source-file

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

الخاصيات (النوع)

فقط للمنصة:

الوصف
src (سلسلة نصية) مطلوب

تحدد هذه الخاصية موقع الملف نسبةً إلى الملف plugin.xml. إذا تعذر العثور على الملف src، فستوقف واجهة سطر الأوامر التثبيت وتعكسه، وتطلق تنبيهًا حول المشكلة، ثم تخرج مع إعادة قيمة غير معدومة.

target-dir (سلسلة نصية) المجلد الذي يجب أن تُنسخ الملفات فيه نسبةً إلى جذر مشروع كوردوفا. من الناحية العملية، يعد هذا أكثر أهمية للمنصات القائمة على جافا، حيث يجب وضع الملفات الموجودة في الحزمة com.alunny.foo داخل المجلد com/alunny/foo. بالنسبة للمنصات التي لا يكون للمجلد المصدري أهمية كبيرة فيها، فيجب حذف هذه الخاصية.
framework (قيمة منطقية)

(ios)

القيمة الافتراضية: false

عند تعيين هذه الخاصية عند القيمة true، فستضيف أيضًا الملف المحدد كإطار عمل للمشروع.

compiler-flags (سلسلة نصية)

(ios)

هذه الخاصية ستعيّن رايات المُصرّف (compiler flags) الخاصة بالملف المصدري المحدد.

مثال على استخدام الوسم source-file: 

<!-- 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) والموارد (resources). هذا الوسم غير مدعوم من قبل ويندوز.

الخاصيات (النوع)

فقط للمنصة:

الوصف
src (سلسلة نصية) مطلوب

موضع الملف نسبةً إلى الملف plugin.xml. إذا تعذر العثور على الملف الذي تحدده src، فستوقف واجهة سطر الأوامر التثبيت وتعكسه، وتطلق تنبيهًا حول المشكلة، ثم تخرج مع إعادة قيمة غير معدومة.

target-dir (سلسلة نصية) المجلد حيث يجب نسخ الملفات، يُحدد نسبةُ إلى جذر مشروع كوردوفا.

مثال خاص بمنصة iOS: 

<header-file src="CDVFoo.h" />‎

resource-file

هذا الوسم يشبه <source-file>، ولكنه مخصوص بمنصات مثل iOS و Android التي تميز بين الملفات المصدرية والملفات الرئيسية والموارد.

الخاصيات (النوع)

فقط للمنصة:

الوصف
src (سلسلة نصية) مطلوب

موضع الملف نسبةً إلى الملف plugin.xml. إذا تعذر العثور على الملف src، فستوقف واجهة سطر الأوامر التثبيت وتعكسه، وتطلق تنبيهًا حول المشكلة، ثم تخرج مع إعادة قيمة غير معدومة.

target-dir (سلسلة نصية) المسار حيث سيُنسخ الملف داخل المجلد خاصتك.
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" />‎

ملاحظة: يجب أن تستخدم الخاصية target الخطوط المائلة العكسية ("\") لتجنب الخطأ DEP2100 deploy في Visual Studio.

config-file

يحدد هذا الوسم ملف الإعداد (XML) المراد تعديله، ويحدد موضع التعديل في ذلك المستند، وما الذي ينبغي تعديله.

هناك نوعان من الملفات تم اختبارها وتعديلها عبر هذا العنصر، وهما الملفان xml و plist. لا يسمح العنصر config-file إلا بإلحاق الوسوم الفرعية الجديدة إلى شجرة المستند XML. الوسوم الفرعية هي عناصر XML حرفية (literals) يتم إدراجها في الوثيقة المستهدفة.

الخاصيات (النوع)

فقط للمنصة:

الوصف
target (سلسلة نصية) تحدد هذه الخاصية الملف المراد تعديله، والمسار نسبةً لجذر مشروع كوردوفا. إن لم يكن الملف المحدد موجودًا، فستتجاهل الأداة التعديلات على الإعدادات وستستمر في التثبيت.

يمكن أن يتضمن الهدف المحرف العام (*). في هذه الحالة، ستبحث واجهة سطر الأوامر عوديًا (recursively) في مجلد المشروع، وستستخدم أول تطابق.

على منصة iOS، موضع ملفات الإعدادات نسبةً إلى جذر مجلد المشروع غير معروف، لذلك فاعتماد القيمة config.xml سيُترجم إلى cordova-ios-project/MyAppName/config.xml.

parent (سلسلة نصية) محدد XPath ‏(XPath selector‏) يشير إلى أصل (parent) العناصر المراد إضافتها إلى ملف الإعدادات. إن استخدمت محددًا مطلقًا (absolute selectors)، فيمكنك استخدام المحرف العام (*) لتحديد العنصر الجذري، على سبيل المثال، ‎/*/plugins. إن لم يكن المحدد يُشير إلى وسم فرعي (child) من المستند المحدد، فستوقف الأداة عملية التثبيت وتعكسها، وتطلق تنبيًها، ثم تخرج وتعيد قيمة غير معدومة.

بالنسبة لملفات plist، تحدد الخاصية parent المفتاح الأصلي (parent key) الذي ينبغي أن يُدرج فيه عنصر XML المحدد.

after (سلسلة نصية) قائمة مرتبة حسب الأولوية للوسوم الإخوة (siblings) المقبولة التي ينبغي إضافة بيانات XML بعدها. هذه الخاصية مفيدة لتحديد التغييرات في الملفات التي تتطلب ترتيبًا صارمًا لعناصر XML، كما هو الحال هنا.
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="&lt;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. سيتم التراجع عن التغييرات المتعارضة التي أجرتها الإضافة plugin-1 في الوسم edit-config وسيتم تطبيق تغييرات 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 يشبه الملفات المصدرية (sources)، والموارد (resources)، والملفات الرئيسية (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 الخاص بالمشروع. ولا يدعم إلا الخاصية 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 (سلسلة نصية)

(ios)

تُقرَن هذه الخاصية بالتعبير type="podspec"‎، وتمثل السلسلة النصية التي تحتوي مواصفات مدير الارتباطات CocoaPod التي تريد تثبيتها (المكتبة الثابتة فقط). CocoaPod ليست مدعومًا إلا في cordova-ios 4.3.0 و cordova-cli 6.4.0. بالنسبة للإضافة الخاصة بك، تأكد من إضافة الوسم <engine> وارتباطات package.json المناسبة لضمان التوافق مع الإصدارات السابقة.
embed (قيمة منطقية)

(ios)

القيمة الافتراضية: 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، أو لتضمين مشروعات المكتبة المجمعة (bundled). 

<!-- play من الخدمة GCM الاعتماد على الإصدار الأحدث من -->
<framework src="com.google.android.gms:play-services-gcm:+" />
<!-- appcompat-v7 من مكتبة الدعمv21 الاعتماد على  -->
<framework src="com.android.support:appcompat-v7:21+" />
<!-- الاعتماد على مكتبة المشروع المُتضمنة في الإضافة -->
<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) متاحة في وقت التشغيل: 

<!-- .winmd يتألف من ملف واحد من النوع C# مكون -->
<framework src="lib\windows\component.winmd" versions="<10.0" />
<!-- مع بيانات وصفية وتقديم منفصل C++ مكون -->
<framework src="lib\windows\x86\cppcomponent.winmd"
           implementation="lib\windows\x86\cppcomponent.dll"
           target-dir="component\x86" arch="x86" versions=">=10.0" />‎

info

يحتوي هذا الوسم على معلومات إضافية لأجل تقديمها للمستخدمين. وهو أمر مفيد عندما تحتاج إلى توضيح خطوات إضافية لا يمكن أتمتتها بسهولة، أو تتجاوز إمكانيات واجهة سطر الأوامر. تُطبع محتويات هذا الوسم عندما تثبّت واجهة سطر الأوامر الإضافة.

مثال على استخدام الوسم info: 

<info>
`Android Extras`  من القسم __Google Play Services__ عليك تثبيت 
(run `android`) SDK باستخدام المُدير 

:local.properties تحتاج إلى إضافة السطر التالي إلى 
android.library.reference.1=PATH_TO_ANDROID_SDK/sdk/extras/google/google_play_services/libproject/google-play-services_lib
</info>‎

hook

يمثل هذا الوسمُ برنامجك النصي (script) المخصص، والذي سيٌستدعى من قبل كوردوفا عند وقوع حدثٍ معينٍ (على سبيل المثال، بعد إضافة الإضافة أو عند استدعاء سلسلة تحضير المنصة). هذا مفيد إن كنت تحتاج إلى توسيع وظائف كوردوفا. راجع صفحة الخطافات لمزيد من المعلومات.

مثال على استخدام الوسم hook: 

<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: 

<preference name="MY_CUSTOM_STRING" default="default-value" />
<!--
    plugin.xml التفضيلات يمكن أن توضع في أي مكان في الملف
-->
<config-file target="./res/values/strings.xml" parent="/resources">
    <string name="custom">$MY_CUSTOM_STRING</string>
</config-file>‎

انظر أيضا

مصادر

مجلوبة من "https://wiki.hsoub.com/index.php?title=Cordova/plugin_ref&oldid=26119"