Плагины 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"]);

Значение переданной в метод Echo.echo строки options — это 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(). Это позволит вам повторно использовать больше кода и исключить избыточную функциональность из различных нативных реализаций плагина.