إضافات iOS في كوردوفا
يقدم هذا القسم تفاصيل عن كيفية تقديم (implement) شيفرات الإضافات الأصلية (native plugin code) على منصة iOS. قبل قراءة هذه الصفحة، راجع صفحة دليل تطوير الإضافات [../../hybrid/plugins/index.html Plugin Development Guide] للحصول على نظرة عامة على بنية الإضافات وواجهة [[JavaScript|جافااسكريبت]] الخاصة بها. يستمر هذا القسم في تطوير مثال الإضافة echo الوارد في دليل تطوير الإضافات، والذي يتواصل بين المعرض webview الخاص بكوردوفا وبين المنصة الأصلية.
يتم تقديم (implement) إضافات iOS على هيئة صنف من لغة Objective-C، والذي يوسع الصنف CDVPlugin. لكي يُربط الوسيط exec المعطى للتابع service في [[JavaScript|جافااسكريبت]] مع صنف في لغة Objective-C، فيجب تسجيل كل كل أصناف الإضافة على هيئة وسم <feature> في الملف config.xml.
إعداد صنف الإضافة
يستخدم جزء [[JavaScript|جافااسكريبت]] من الإضافة التابع cordova.exec على النحو التالي:
exec(<successFunction>, <failFunction>, <service>, <action>, [<args>]);
هذا يرسل طلبية (request) من UIWebView إلى الجانب الأصلي (native side) من منصة iOS، ويستدعي التابع action على الصنف service فعلياً، مع تمرير الوسائط المعطاة في المصفوفة args.
قم بحديد الإضافة على هيئة وسم <feature> في الملف config.xml الخاص بتطبيق Cordova-iOS، مع استخدام الملف plugin.xml لإدراج هذا الوسم تلقائيًا، كما هو موضح في [../../hybrid/plugins/index.html Plugin Development Guide]:
<feature name="LocalStorage">
<param name="ios-package" value="CDVLocalStorage" />
</feature>
يجب أن تتطابق الخاصية name في الوسم feature مع قيمة الوسيط exec الذي مررته سابقا إلى دالة [[JavaScript|جافااسكريبت]] service. كما يجب أن تتطابق الخاصية value مع اسم صنف Objective-C في الإضافة. يجب أن تساوي الخاصية <param> في الوسم name دائمًا القيمة ios-package. إذا لم تتبع هذه الإرشادات، فقد يتم تصريف (compile) الإضافة، ولكن قد لا تتمكن كوردوفا من الوصول إليه.
تهيئة الإضافات ودورة الحياة (Plugin Initialization and Lifetime)
يتم إنشاء نسخة (instance) واحدة من كائن الإضافة خلال دورة حياة المعرض UIWebView. لا يتم إنشاء نسخ للإضافات حتى تتم الإشارة إليها أولاً عبر استدعاء من [[JavaScript|جافااسكريبت]]، إلا في حال إضافة وسم <param> مع خاصية onload مساوية للقيمة name، إلى "true" في config.xml. فمثلا،
<feature name="Echo">
<param name="ios-package" value="Echo" />
<param name="onload" value="true" />
</feature>
يجب أن تستخدم الإضافات التابع pluginInitialize في مرحلة الانطلاق.
لإضافات ذات الطلبيات الطويلة (long-running requests)، أو النشاطات الخلفية (background activity)، مثل قارئات الوسائط، أو المستمعات (listeners)، أو النشاطات ذات الحالة الداخلية (internal state) يجب أن تقدِّم (implement) التابع onReset لإلغاء تلك الطلبيات الطويلة، أو للتنظيفه بعد تلك الأنشطة. يتم تشغيل التابع عند انتقال UIWebView إلى صفحة جديدة/ أو عند تحديث الصفحة، وهو ما يؤدي إلى إعادة تحميل [[JavaScript|جافااسكريبت]].
كتابة إضافات iOS
يرسل استدعاء من [[JavaScript|جافااسكريبت]] طلبية إضافة (plugin request) إلى الجانب الأصلي (native side)، ويُعيّن إضافة Objective-C المقابلة في الملف config.xml. أي شيء يتم إرساله إلى الإضافة عبر دالة [[JavaScript|جافااسكريبت]] exec سيُمرّر إلى التابع action الخاص بصنف بالإضافة. فيما يلي إمضاء (signature) تابع الإضافة:
- (void)myMethod:(CDVInvokedUrlCommand*)command
{
CDVPluginResult* pluginResult = nil;
NSString* myarg = [command.arguments objectAtIndex:0];
if (myarg != nil) {
pluginResult = [CDVPluginResult resultWithStatus:CDVCommandStatus_OK];
} else {
pluginResult = [CDVPluginResult resultWithStatus:CDVCommandStatus_ERROR messageAsString:@"Arg was null"];
}
[self.commandDelegate sendPluginResult:pluginResult callbackId:command.callbackId];
}
لمزيد من التفاصيل، راجع الصفحات CDVInvokedUrlCommand.h و CDVPluginResult.h و CDVCommandDelegate.h.
أنواع الرسائل CDVPluginResult في المنصة iOS
يمكنك استخدام CDVPluginResult لإعادة مجموعة متنوعة من أنواع النتائج إلى استدعاءات [[JavaScript|جافااسكريبت]]، باستخدام توابع الصنف التي تتبع هذا النمط:
+ (CDVPluginResult*)resultWithStatus:(CDVCommandStatus)statusOrdinal messageAs...
يمكنك إنشاء الأنواع String و Int و Double و Bool و Array و Dictionary و ArrayBuffer و Multipart. يمكنك أيضًا استبعاد أي وسيط لإرسال حالة، أو لإعادة خطأ، أو يمكن حتى اختيار عدم إرسال أي نتيجة للإضافة، وفي هذه الحالة لن يُطلق أيٌّ من تلك الاستدعاءات.
تذكر ما يلي للتعامل مع القيم المعادة المعقدة:
messageAsArrayBuffer تتوقع NSData*، وتحول إلى ArrayBuffer في استدعاء [[JavaScript|جافااسكريبت]]. وبالمثل، أي كائن ArrayBuffer ترسله [[JavaScript|جافااسكريبت]] إلى الإضافة سيُحوّل إلى NSData*.
messageAsMultipart تتوقع مصفوفة NSArray* تحتوي على أي من الأنواع المدعومة الأخرى، وترسل المصفوفة بأكملها باعتبارها arguments إلى استدعاء [[JavaScript|جافااسكريبت]] (JavaScript callback). بهذه الطريقة، تُسلسل (serialized) كل الوسائط أو تُفلّ (deserialized) بحسب الضرورة، لذلك من الآمن إعادة NSData* كسلسلة متعددة (multipart)، ولكن ليس على هيئة مصفوة أو قاموس Array / Dictionary.
مثال لإضافة iOS
لمطابقة ميزة [[JavaScript|جافااسكريبت]] echo المقدمة في واجهة [[JavaScript|جافااسكريبت]] في صفحة الإضافات، استخدم الملف plugin.xml لإدراج مواصفات feature في الملف config.xml الخاص بالمنصة المحلية:
<platform name="ios">
<config-file target="config.xml" parent="/*">
<feature name="Echo">
<param name="ios-package" value="Echo" />
</feature>
</config-file>
</platform>
ثم نضيف الملفين Echo.h و Echo.m إلى المجلد Plugins الموجود في مجلد تطبيق Cordova-iOS:
/********* Echo.h Cordova Plugin Header *******/
#import <Cordova/CDVPlugin.h>
@interface Echo : CDVPlugin
- (void)echo:(CDVInvokedUrlCommand*)command;
@end
/********* Echo.m Cordova Plugin Implementation *******/
#import "Echo.h"
#import <Cordova/CDVPlugin.h>
@implementation Echo
- (void)echo:(CDVInvokedUrlCommand*)command
{
CDVPluginResult* pluginResult = nil;
NSString* echo = [command.arguments objectAtIndex:0];
if (echo != nil && [echo length] > 0) {
pluginResult = [CDVPluginResult resultWithStatus:CDVCommandStatus_OK messageAsString:echo];
} else {
pluginResult = [CDVPluginResult resultWithStatus:CDVCommandStatus_ERROR];
}
[self.commandDelegate sendPluginResult:pluginResult callbackId:command.callbackId];
}
@end
تُوسّع عمليات الاستيراد في الجزء العلوي من الملف الصنف من CDVPlugin. في هذه الحالة، لا تدعم الإضافة سوى إجراء (action) واحد echo. تستخلص السلسلة النصية المعروضة echo عن طريق استدعاء التابع objectAtIndex للحصول على الوسيط الأول الموجود في المصفوفة arguments، والذي يتوافق مع الوسائط المُمررة بواسطة دالة [[JavaScript|جافااسكريبت]] exec().
يتحقق من الوسيط للتأكد من أنها لا يساوي القيمة nil أو سلسلة نصية فارغة، ثم يعيد PluginResult مع الحالة ERROR إذا كان الأمر كذلك. إذا اجتاز الوسيط الفحص، فسيُعاد PluginResult مع حالة تساوي OK، وتمرر إلى السلسلة النصية الأصلية echo. وأخيرًا، يرسل النتيجة إلى التابع self.commandDelegate، والذي ينفذ دوال النجاح أو الإخفاق (success or failure callbacks) الخاصة بالتابع exec على جانب [[JavaScript|جافااسكريبت]]. في حال استدعاء دالة النجاح، فسيُمرر إليها الوسيط echo.
التكامل مع منصة iOS
يوفر الصنف CDVPlugin توابع أخرى يمكن أن تعيد الإضافة الخاصة بك تعريفها. على سبيل المثال، يمكنك إمساك الأحداث [../../../cordova/events/events.html#pause pause] و [../../../cordova/events/events.html#resume resume] و إنهاء التطبيق (app terminate) و handleOpenURL. راجع الصنفين CDVPlugin.h و CDVPlugin.m لأجل الإرشادات.
المهام الفرعية (Threading)
تنفّذ توابع الإضافة عادةً في نفس المهمة الفرعية التي تشتغل عليها الواجهة الرئيسية. إن كانت الإضافة تتطلب قدرًا كبيرًا من المعالجة، أو تتطلب القيام باستدعاء مُعطل (blocking call)، فعليك استخدام مهمة فرعية خلفية. مثلا:
- (void)myPluginMethod:(CDVInvokedUrlCommand*)command
{
// Check command.arguments here.
[self.commandDelegate runInBackground:^{
NSString* payload = nil;
// Some blocking logic...
CDVPluginResult* pluginResult = [CDVPluginResult resultWithStatus:CDVCommandStatus_OK messageAsString:payload];
// The sendPluginResult method is thread-safe.
[self.commandDelegate sendPluginResult:pluginResult callbackId:command.callbackId];
}];
}
تصحيح إضافات iOS (Debugging iOS Plugins)
لتصحيح الأخطاء من جانب شيفرة Objective-C، سيكون عليك استخدام المصحح المدمج Xcode. بالنسبة إلى [[JavaScript|جافااسكريبت]]، يمكنك ربط Safari بالتطبيق المُشتغل في جعاز أو محاكي iOS.
أخطاء شائعة
لا تنسَ إضافة خريطة الإضافة (plugin's mapping) إلى config.xml. وإن نسيت، سيُسجّل خطأ في وحدة تحكم Xcode.
لا تنس إضافة كل المضيفات التي تتصل بها في القائمة البيضاء، كما هو موضح في صفحة [../../appdev/whitelist/index.html Whitelist Guide]. وإن نسيت، فسيُسجّل خطأ في وحدة تحكم Xcode.