Плагины Windows

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

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

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

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

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);
        }
    }
});

И это все, у нас есть плагин, вызываемый из js, с поддержкой 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>

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