إضافات ويندوز في كوردوفا

يقدم هذا القسم تفاصيل عن كيفية تقديم (implement) إضافة لاستخدامها في متجر تطبيقات ويندوز (ويندوز Store app) للهاتف وسطح المكتب ويندوز 8.1، ومنصة ويندوز الكونية (Universal ويندوز ‎Platform [ويندوز 10+]‎‎). قبل قراءة هذه الصفحة، راجع صفحة دليل تطوير الإضافات [../../hybrid/plugins/index.html Create your first plugin] للحصول على نظرة عامة على بنية الإضافات وواجهة [[JavaScript|جافااسكريبت]] الخاصة بها. يستمر هذا القسم في تطوير مثال الإضافة echo الوارد في دليل تطوير الإضافات، والذي يتواصل بين المعرض webview الخاص بكوردوفا وبين المنصة الأصلية.

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

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

// inside file echoplugin.js
var EchoPlugin = {
    // the echo function calls successCallback with the provided text in strInput
    // if strInput is empty, it will call the errorCallback
    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)، ويمكننا ببساطة كتابة خادم وسيطً لنظام ويندوز.

// in file echoplugin.js
window.echo = function(str, callback) {
    cordova.exec(callback, function(err) {
        callback('Nothing to echo.');
    }, "Echo", "echo", [str]);
};‎

// in file 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_ref/spec.html 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>
    <!-- other platforms -->
</plugin>‎

هذا يعطينا إضافة ويتدوز-[[JavaScript|جافااسكريبت]] تستخدم ملفًا مشتركًا (echoplugin.js) وتستخدم خادمًا وسيطًا لتوفير الأجزاء المخصوصة بويندوز في الملف (echopluginProxy.js). إذن، كيف يمكننا إضافة شيفرة أصلية ومٌدارة (native/managed code) إلى هذا؟ حسنا سنعيد ما فعلناه من قبل، مع فرق وحيد يتمثل في ما سنفعله داخل توابع echopluginProxy.

إنشاء إضافات ويندوز عبر C ++ أو الشيفرة المُدارة (Creating a Windows Plugin in C++ or managed code).

في نظام ويندوز، تستطيع تطبيقات [[JavaScript|جافااسكريبت]] أن تتداخل مع اللغات الأصلية (C++‎) والشيفرات المُدارة (C#، VB) عن طريق إنشاء مُركّبة (component) في ويندوز تعمل وقت تشغيل. يمكنك تعلم الأساسيات والحصول على مزيد من التفاصيل في مراجع MSDN: Creating Windows Runtime Components in C# and Visual Basic Creating Windows Runtime Components in C++

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

// in your header file .h
namespace EchoRuntimeComponent
{
    public ref class EchoPluginRT sealed
    {
        public:
        static Platform::String^ Echo(Platform::String^ input);
    }
}
// in the implementation file .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، سنحصل على:

// in file 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);
        }
    }
});‎

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

اعتبارات

عادة ما يكون الرد (callback ) غير متزامن، لذلك قد لا يتوقع المُستدعي (caller) أن يكون الرد فوريًا. لكن إن لم يكن الاستدعاء غير متزامن، فعليك على الأقل استخدام مهلة [[JavaScript|جافااسكريبت]] (javascript timeout) لضمان أن يكون استدعاء الرد غير متزامن.
يمكن استخدام الأصناف القابلة للتنشيط (Activatable classes) لإرسال الأحداث (event dispatching)، أو الردود المتزامنة، أو تمرير أنواع كائنات خاصة، أو المصفوفات، أو المجموعات، أو التوابع المُتحاملة (overloaded methods)، وغير ذلك. ارجع إلى Creating Windows Runtime Components in 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>
    <!-- windows -->
    <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>
    <!-- other platforms -->
</plugin>‎

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

مصادر

قسم إضافات windows في التوثيق الرسمي لكوردوفا.