Плагины Windows Phone 8

Этот раздел содержит подробную информацию о том, как реализовать нативный код плагина на платформе Windows Phone. Прежде чем приступать к чтению, ознакомьтесь с Руководством по разработке плагинов для общего обзора структуры плагина и его общего интерфейса JavaScript. В этом разделе продолжается демонстрация примера плагина echo, который осуществляет взаимодействие между веб-вью Cordova и нативной платформой.

Для написания плагина для Cordova на Windows Phone необходимо базовое понимание архитектуры Cordova. Cordova-WP8 состоит из WebBrowser , который размещает код JavaScript приложения и управляет вызовами нативных API. Вы можете расширить класс C# BaseCommand (WPCordovaClassLib.Cordova.Commands.BaseCommand), который поставляется с большей частью необходимой функциональности:

1. Выберите свой проект и щелкните правой кнопкой мыши, чтобы выбрать Добавить → Новый элемент... Если хотите, вы можете добавить его в папку Plugins.

2. Выберите Класс и назовите его Echo.cs. Это имя класса должно точно совпадать с тем, что вы указываете в качестве сервиса в вызове cordova.exec() на стороне JavaScript.

3. Включите реализацию базовых классов:

   using WPCordovaClassLib.Cordova;
   using WPCordovaClassLib.Cordova.Commands;
   using WPCordovaClassLib.Cordova.JSON;
   

4. Расширьте свой класс от BaseCommand.

   public class Echo : BaseCommand
   {
       // ...
   }
   

5. Добавьте метод echo, который можно вызывать из JavaScript:

   public class Echo : BaseCommand
   {
       public void echo(string options)
       {
           // all JS callable plugin methods MUST have this signature!
           // public, returning void, 1 argument that is a string
       }
   }
   

Обратитесь к классу BaseCommand.cs для получения методов, которые можно переопределить в плагине. Например, плагин может перехватывать события паузы и возобновления.

Пространства имён

По умолчанию пространство имён для неквалифицированных команд:

namespace Cordova.Extension.Commands
{
    // ...
}

Если вы хотите указать собственное пространство имён, вам необходимо выполнить полностью квалифицированный вызов cordova.exec. Например, если вы хотите определить свой класс C# так:

namespace com.mydomain.cordovaExtensions
{
    public class Echo : BaseCommand
    {
        // ...
    }
}

JavaScript необходимо будет вызвать exec следующим образом:

cordova.exec(win, fail, "com.mydomain.cordovaExtensions.Echo", ...);

Интерпретация аргументов в C#

В примере, обсуждаемом в разделе Плагины приложения, данные, получаемые вашим плагином, — это строка, но что, если вы хотите передать массив строк? Предположим, что вызов JavaScript cordova.exec задан следующим образом:

cordova.exec(win, fail, "Echo", "echo", ["input string"]);

Значение строки options, переданной методу Echo.echo, представляет собой JSON:

"[\"input string\"]"

Все аргументы JavaScript exec кодируются в JSON перед передачей в C#, и поэтому их необходимо декодировать:

string optVal = JsonHelper.Deserialize<string[]>(options)[0];
// optVal now has the value of "input string"

Передача результатов из C# в JavaScript

Класс BaseCommand предоставляет методы для передачи данных обработчикам обратного вызова JavaScript. Если вы просто хотите сообщить об успехе без сопровождающего результата, вы можете просто вызвать:

DispatchCommandResult();
// calls back with an empty plugin result, considered a success callback

Для передачи данных необходимо вызвать DispatchCommandResult по-другому:

DispatchCommandResult(new PluginResult(PluginResult.Status.OK, "Everything went as planned, this is a result that is passed to the success handler."));

Используйте закодированную строку JSON для передачи структурированных данных объекта обратно в JavaScript:

DispatchCommandResult(new PluginResult(PluginResult.Status.OK, "{result:\"super awesome!\"}"));

Для сообщения об ошибке вызовите DispatchCommandResult с объектом PluginResult, статус которого ERROR.

DispatchCommandResult(new PluginResult(PluginResult.Status.ERROR, "Echo signaled an error"));

Обработка ошибок сериализации

При интерпретации аргументов блоки try/catch помогают отфильтровать некорректные входные данные. Этот шаблон встречается в коде Cordova на C#:

string optVal = null;

try
{
    optVal = JsonHelper.Deserialize<string[]>(options)[0];
}
catch(Exception)
{
    // simply catch the exception, we handle null values and exceptions together
}

if (optVal == null)
{
    DispatchCommandResult(new PluginResult(PluginResult.Status.JSON_EXCEPTION));
}
else
{
    // ... continue on to do our work
}

Жизненный цикл плагина

Плагины с долговременными запросами, фоновой деятельностью, такой как воспроизведение медиа, слушателями или сохранением внутреннего состояния, должны реализовать метод onReset для очистки этих действий. Метод выполняется при переходе веб-браузера CordovaView на новую страницу или при обновлении, что перезагружает JavaScript.

// defined in WPCordovaClassLib.Cordova.Commands.BaseCommand
public virtual void OnReset() { }

XML-файл плагина

Ниже показано, как использовать файл plugin.xml для указания исходных файлов плагина на платформе Windows Phone. См. Плагины приложения для обзора и Спецификацию плагина для получения подробной информации о доступных параметрах.

• Элемент <source-file> определяет все ресурсы плагина, такие как файлы .cs, .xaml, .xaml.cs и .dll, а также изображения.

• Элемент <config-file> определяет элементы для вставки в файл конфигурации. В этом примере плагин добавляется в файл config.xml платформы:

  <config-file target="config.xml" parent="/*">
      <feature name="PluginName">
          <param name="wp-package" value="PluginName"/>
      </feature>
  </config-file>
  

Этот пример добавляет возможность контактов в файл WMAppManifest.xml:

<config-file target="Properties/WMAppManifest.xml" parent="/Deployment/App/Capabilities">
    <Capability Name="ID_CAP_CONTACTS" />
</config-file>

Отладка плагинов

Используйте отладчик Visual Studio для отладки компонента C# плагина. Вы можете установить точку останова в любом из методов, предоставляемых вашим классом.

Отладка JavaScript на Windows Phone более сложная. Вам нужно использовать console.log для вывода состояния плагина или получения информации об ошибках.

Общие ошибки

• Будьте внимательны, чтобы не передавать в нативную сторону аргументы из JavaScript, которые сложно десериализовать как JSON. Большинство платформ устройств ожидают, что аргумент, переданный в cordova.exec(), будет массивом, например:

  cordova.exec(win, fail, "ServiceName", "MethodName", ["this is a string", 54, {literal:'trouble'}]);
  

Это может привести к слишком сложной строке значения для декодирования в C#:

"[\"this is a string\", 54, { literal:'trouble' }]"

Вместо этого рассмотрите возможность преобразования всех параметров в строки перед вызовом exec(), и декодирование каждого отдельно:

cordova.exec(win, fail, "ServiceName", "MethodName", ["this is a string", "54", "{literal:'trouble'}"]);
string[] optValues = JsonHelper.Deserialize<string[]>(options);

• Обычно лучше проверять параметры в JavaScript перед вызовом exec(). Это позволяет повторно использовать больше кода и исключить ненужную функциональность из различных нативных реализаций плагина.