Плагины для Windows

В этом разделе описано, как реализовать плагин для использования в приложении Windows Store для телефонов и настольных компьютеров Windows 8.1 и универсальной платформы Windows (Windows 10 и выше). Перед чтением ознакомьтесь со статьёй Создание первого плагина для общего обзора структуры плагина и его стандартного интерфейса JavaScript. В этом разделе демонстрируется пример плагина echo, который взаимодействует между веб-вью Cordova и родной платформой.

Создание плагина Windows на JavaScript

Плагины Cordova для Windows в основном представляют собой тонкий оберточный слой над существующими функциями WinJS, но если вы хотите определить общий интерфейс JavaScript для нескольких устройств, обычно используется один файл JS, предоставляющий 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 и кодом родного обертки. Но в случае с Windows родной обертки нет, поэтому вызов exec присутствует для обеспечения согласованности. Хотя вы можете написать код, специфичный для Windows, как часть общего кода JavaScript плагина непосредственно, это не рекомендуется. Разработчики плагинов должны использовать тот же API exec для Windows, что и для других платформ. Таким образом, API плагина становится согласованным, и вы также можете воспользоваться проверкой параметров или другим общим кодом, предоставленным разработчиками, работающими над другими платформами.

В Windows Cordova предоставляет прокси, который вы можете использовать для регистрации объекта, обрабатывающего все вызовы cordova.exec для API. Таким образом, в нашем случае мы будем предполагать, что код в echoplugin.js обрабатывает JavaScript, относящийся к нескольким платформам, и мы можем просто написать прокси для Windows.

// 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 и выполнит эту реализацию.

Файл 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>

    <!-- other platforms -->

</plugin>

Это даёт нам рабочий плагин JavaScript для Windows, который использует общий файл (echoplugin.js) и использует прокси для предоставления части реализации, специфичной для Windows (echopluginProxy.js). Итак, как добавить код родной/управляемой платформы к этому? Мы начнём так же, единственное отличие будет заключаться в том, что мы делаем внутри методов echopluginProxy.

Создание плагина Windows на C++ или управляемом коде

В Windows приложения, написанные на JavaScript, могут взаимодействовать с родным кодом (C++) и управляемым кодом (C#, VB), создавая компонент платформы Windows. Вы можете ознакомиться с основами здесь и получить более подробную информацию в руководствах на MSDN:

• Создание компонентов платформы Windows на C# и Visual Basic
• Создание компонентов платформы Windows на C++

При создании компонента платформы Windows любой класс, определённый как public ref class sealed считается «активируемым классом» и будет вызываемым из 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";
    }
}

Теперь, чтобы вызвать родной код, мы используем имя пространства, имя класса и метод, вызываемый с использованием нижнего регистра camelCase.

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++, для использования в Apache Cordova Windows!

Соображения

• Обратный вызов обычно асинхронный, поэтому вызов обратного вызова сразу, вероятно, не ожидается вызывающим кодом. На практике, если вызов не асинхронный, вы должны по крайней мере использовать таймаут JavaScript, чтобы принудительно вызвать обратный вызов асинхронно.
• Активируемые классы могут использоваться для отправки событий, асинхронных обратных вызовов, передачи собственных типов объектов, массивов, коллекций, перегруженных методов и многого другого. Для получения подробностей обратитесь к Создание компонентов платформы Windows на C++.

Определение плагина в plugin.xml

Теперь, когда у нас есть рабочий плагин, нам нужно пересмотреть определение плагина из предыдущего раздела, чтобы опубликовать его. Теперь мы можем добавить компонент времени выполнения как фреймворк через тег <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>

И всё готово, у вас теперь есть распространяемый плагин, которым вы можете поделиться с миром!