Cordova/plugins windows

 يقدم هذا القسم تفاصيل عن كيفية تنفيذ إضافة لاستخدامها في متجر تطبيقات ويندوز للهواتف وسطح المكتب في ويندوز 8.1 للهاتف (Windows 8.1 phone)، ومنصة ويندوز الكونية (Universal Windows [ويندوز 10+]‎‎). قبل قراءة هذه الصفحة، يرجى قراءة صفحة دليل تطوير الإضافات للحصول على نظرة عامة على بنية الإضافات وواجهة JavaScript الخاصة بها. يستمر هذا القسم في تطوير مثال الإضافة echo الوارد في دليل تطوير الإضافات، والذي يربط الاتصال بين المعرض webview الخاص بكوردوفا وبين المنصة الأصلية.

إنشاء إضافة ويندوز عبر جافاسكريبت

إضافات ويندوز كوردوفا هي بالأساس أغلفة (wrapper) رقيقة حول دوال المكتبة WinJS، ولكن إن كنت تحتاج إلى تعريف واجهة JavaScript مشتركة بين عدة أجهزة، فستحتاج عادةً إلى ملف JavaScript واحد يوفر تلك الواجهة البرمجية (API):

// echoplugin.js داخل الملف
var EchoPlugin = {
    // strInput مع النص المُوفّر في successCallback  تستدعي echo الدالة
    // errorCallback فارغة ستقوم باستدعاء strInput إن كانت
    echo:function(successCallback, errorCallback, strInput) {
        cordova.exec(successCallback,errorCallback,"EchoPlugin","echo",[strInput]);
    }
}‎

يختلف تعريف الدالة cordova.exec من منصة إلى أخرى، وذلك لأن لكل منصة طريقتها الخاصة في التواصل بين شيفرة JavaScript، والشيفرة الأصلية المُغلّفة (native wrapper code). ولكن في حالة ويندوز، لا يوجد غلاف أصلي، لذلك فاستدعاء exec هو مجرد اصطلاح لتوفير واجهة متناسقة. لذلك، على الرغم من أنه يمكنك كتابة الشيفرة البرمجية الخاصة بويندوز كجزء من ملف JavaScript المشترك (الخاص بالإضافة) مباشرةً، إلا أننا لا نوصي بذلك، فيجب على مطوري الإضافات استخدام نفس الواجهة البرمجية exec في ويندوز كما في بقية المنصات الأخرى. وبهذه الطريقة تصبح الواجهة البرمجية للإضافات متسقة، كما يمكنك أيضًا الاستفادة من أي فحص للمعاملات، أو الشيفرات الأخرى الشائعة التي يوفرها المطورون على المنصات الأخرى.

على ويندوز، توفر كوردوفا خادمًا وسيطًا (proxy) يمكن استخدامه لتسجيل كائن معين يتكلّف بالتعامل مع جميع استدعاءات cordova.exec في الواجهة البرمجية (API). لذا، سنفترض في حالتنا أن الشيفرة الموجودة في الملف echoplugin.js ستعالج أكواد JavaScript العابرة للمنصات (cross platform)، وهكذا يمكننا ببساطة كتابة خادمٍ وسيطٍ لنظام ويندوز.

في الملف echoplugin.js:

// echoplugin.js في الملف
window.echo = function(str, callback) {
    cordova.exec(callback, function(err) {
        callback('Nothing to echo.');
    }, "Echo", "echo", [str]);
};‎

وفي الملف echopluginProxy.js:

// echopluginProxy.js في الملف
cordova.commandProxy.add("Echo",{
    echo:function(successCallback,errorCallback,strInput) {
        if(!strInput || !strInput.length) {
            errorCallback("Error, something was wrong with the input string. =>" + strInput);
        }
        else {
            successCallback(strInput + "echo");
        }
    }
});‎

سيعيد الملف echoplugin.js توجيه استدعاء الدالة echo إلى الخادم الوسيط عبر الأمر cordova.exec ثم ينفّذ هذا التقديم (implementation). سيحتوي الملف plugin.xml على الإعدادات المطلوبة في الََإضافة. وفي هذه الحالة، نريد إضافة الملف echoplugin.js إلى المجلد www، وإضافة الملف echopluginProxy.js داخل الشيفرة المصدرية windows الخاصة بتطبيقنا. يمكن العثور على مزيد من التفاصيل حول هذه العناصر في المرجع Plugin xml.

<?xml version="1.0" encoding="UTF-8"?>
<plugin xmlns="http://apache.org/cordova/ns/plugins/1.0"
    id="echoplugin"
    version="0.1.0">
    <js-module src="www/echoplugin.js" name="echoplugin">
        <clobbers target="window.echoplugin" />
    </js-module>
    <!-- windows -->
    <platform name="windows">
        <js-module src="src/windows/echopluginProxy.js" name="EchoProxy">
            <merges target="" />
        </js-module>
    </platform>
    <!-- منصات أخرى -->
</plugin>‎c

سينتج عن هذا إضافة ويندوز-جافاسكريبت جاهزة، والتي تستخدم ملفًا مشتركًا (هو echoplugin.js)، وخادمًا وسيطًا لتوفير الأجزاء المخصوصة بويندوز في الملف (echopluginProxy.js).

إذًا، كيف يمكننا إضافة شيفرة أصلية ومٌدارة (native/managed code) إلى هذا؟ حسنًا، سنعيد ما فعلناه من قبل، الفرق الوحيد هو ما سنفعله داخل توابع echopluginProxy.

إنشاء إضافات ويندوز بلغة C++‎ أو الشيفرة المُدارة (managed code).

في نظام ويندوز، يمكن لتطبيقات جافاسكريبت أن تتداخل مع اللغات الأصلية (مثل لغة C++‎) والشيفرات المُدارة (مثل لغة C#، و VB) عن طريق إنشاء مُركّبة في ويندوز تعمل وقت تشغيل. يمكنك تعلم الأساسيات والحصول على مزيد من التفاصيل في مراجع MSDN التالية:

• انشاء مركبات ويندوز تعمل وقت التشغيل بلغة C# و Visual Basic
• انشاء مركبات ويندوز تعمل وقت التشغيل بلغة C++‎

عندما تنشئ مركبة ويندوز تعمل وقت التشغيل (Windows Runtime Component)، فإن كل الأصناف التي عُرِّفت وفق الصيغة public ref class sealed ستُعد "أصنافًا قابلًة للتنشيط" (activatable class)، وستكون قابلة للاستدعاء من جافاسكريبت.

// .h في الملف الرئيسي
namespace EchoRuntimeComponent
{
    public ref class EchoPluginRT sealed
    {
        public:
        static Platform::String^ Echo(Platform::String^ input);
    }
}
//  .cpp في ملف التقديم
using namespace EchoRuntimeComponent;
using namespace Platform;
Platform::String^ EchoPluginRT::Echo(Platform::String^ input)
{
    if(input->IsEmpty())
    {
        return "Error: input string is empty.";
    }
    else
    {
        return input->ToString() + "echo";
    }
}‎

ليتسنى لنا استدعاء الشيفرة الأصلية، سنستخدم اسم المجال (namespace)، واسم الصنف، والاسم بنمط سنام الجمل (lowerCamelCase) للتابع الذي نود استدعاءه، كما هو موضح أدناه:

var res = EchoRuntimeComponent.EchoPluginRT.echo("boom");‎

بنقل هذا إلى الملف echopluginProxy.js، سنحصل على ما يلي:

//  echopluginProxy.js في الملف
cordova.commandProxy.add("EchoPlugin",{
    echo:function(successCallback, errorCallback, strInput) {
        var res = EchoRuntimeComponent.EchoPluginRT.echo(strInput);
        if(res.indexOf("Error") == 0) {
            errorCallback(res);
        }
        else {
            successCallback(res);
        }
    }
});‎

وهذا كل شيء، صارت لدينا إضافة ويندوز كوردوفا مع ملف جافاسكريبت قابل للاستدعاء ومربوط ومدعوم بلغة C++‎.

أشياء يجب أخذها بالحسبان

• عادةً ما يكون رد النداء (callback) غير متزامن، لذلك فقد لا يتوقع المُستدعي (caller) أن يكون الرد فوريًا. لكن إن لم يكن الاستدعاء غير متزامن، فعليك على الأقل استخدام مُهلة في جافاسكريبت (javascript timeout) لضمان أن يكون استدعاء رد النداء غير متزامن.
• يمكن استخدام الأصناف القابلة للتنشيط (Activatable classes) لإرسال الأحداث (event dispatching)، أو الردود المتزامنة، أو تمرير أنواع كائنات خاصة، أو المصفوفات، أو المجموعات، أو التوابع المُحمّلة (overloaded methods) وغير ذلك. ارجع إلى صفحة انشاء مركبات ويندوز تعمل وقت التشغيل بلغة C++ ‎ لمزيد من التفاصيل.

تعريف الإضافة في الملف plugin.xml

والآن بعد أن أصبحت إضافتنا جاهزة للعمل، سيكون علينا إعادة النظر في تعريف الإضافة السابق لأجل نشرها. يمكننا الآن إضافة مركبة تعمل وقت التشغيل (runtime component) كإطار عمل، من خلال الوسم <framework> داخل إعدادات منصتنا. لاحظ أنّ امتداد المخرجات WindowsRuntimeComponent قد يكون إما ‎.winmd أو ‎.‎dll:

<?xml version="1.0" encoding="UTF-8"?>
<plugin xmlns="http://apache.org/cordova/ns/plugins/1.0"
    id="echoplugin"
    version="0.2.0">
    <js-module src="www/echoplugin.js" name="echoplugin">
        <clobbers target="window.echoplugin" />
    </js-module>
    <!-- ويندوز-->
    <platform name="windows">
        <js-module src="src/windows/echopluginProxy.js" name="EchoProxy">
            <merges target="" />
        </js-module>
        <framework src="src/windows/EchoRuntimeComponent.winmd" custom="true"/>
    </platform>
    <!-- منصات أخرى -->
</plugin>‎

هذا كل شيء، إضافتك الآن صارت جاهزة لتشاركها مع العالم.

انظر أيضا

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

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

مصادر

• صفحة Windows Plugins في توثيق كوردوفا الرسمي.