Руководство по разработке плагинов для iOS

Этот раздел содержит подробности о том, как реализовать код нативного плагина на платформе iOS. Перед чтением этого раздела, ознакомьтесь с [Руководством по разработке плагинов][plugin-dev] для обзора структуры плагина и его общего JavaScript интерфейса. Этот раздел продолжает демонстрировать пример плагина echo, который общается от Cordova webview до нативной платформы и обратно.

Плагин iOS реализуется как класс Objective-C, который расширяет класс CDVPlugin. Для параметра метода exec JavaScript, который должен соответствовать классу Objective-C, каждый класс плагина должен быть зарегистрирован как тег <feature> в файле config.xml в каталоге приложения с заданным именем.

Сопоставление классов плагинов

JavaScript часть плагина использует метод cordova.exec следующим образом:

exec(<successFunction>, <failFunction>, <service>, <action>, [<args>]);

Это обеспечивает передачу запроса от UIWebView на сторону нативного iOS, фактически вызывая метод action в классе service, с аргументами, переданными в массиве args.

Укажите плагин как тег <feature> в файле config.xml проекта приложения Cordova-iOS, используя файл plugin.xml для автоматической инъекции этой разметки, как описано в [Руководстве по разработке плагинов][plugin-dev]:

<feature name="LocalStorage">
    <param name="ios-package" value="CDVLocalStorage" />
</feature>

Атрибут name функции должен соответствовать тому, что вы указали как параметр service вызова JavaScript exec. Атрибут value должен соответствовать имени класса Objective-C плагина. Элемент <param> должен всегда содержать ios-package. Если вы не следуете этим рекомендациям, плагин может быть скомпилирован, но Cordova может все еще не иметь к нему доступа.

Инициализация и жизненный цикл плагина

Для каждого UIWebView создаётся один экземпляр объекта плагина. Плагины не создаются до тех пор, пока они не будут впервые упомянуты в вызове с JavaScript, если только <param> с onload атрибутом name не установлен в значение "true" в config.xml. Например,

<feature name="Echo">
    <param name="ios-package" value="Echo" />
    <param name="onload" value="true" />
</feature>

Плагины должны использовать метод pluginInitialize для своей логики запуска.

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

Написание плагина Cordova для iOS

Вызов JavaScript отправляет запрос плагина на сторону нативного кода, а соответствующий плагин iOS Objective-C правильно отображается в файле config.xml, но как выглядит окончательный класс плагина iOS Objective-C? Всё, что передаётся плагину с помощью функции JavaScript exec, передаётся в метод action соответствующего класса плагина. Метод плагина имеет следующую сигнатуру:

- (void)myMethod:(CDVInvokedUrlCommand*)command
{
    CDVPluginResult* pluginResult = nil;
    NSString* myarg = [command.arguments objectAtIndex:0];

    if (myarg != nil) {
        pluginResult = [CDVPluginResult resultWithStatus:CDVCommandStatus_OK];
    } else {
        pluginResult = [CDVPluginResult resultWithStatus:CDVCommandStatus_ERROR messageAsString:@"Arg was null"];
    }
    [self.commandDelegate sendPluginResult:pluginResult callbackId:command.callbackId];
}

Для получения более подробной информации см. CDVInvokedUrlCommand.h, CDVPluginResult.h и CDVCommandDelegate.h.

Типы сообщений iOS CDVPluginResult

Вы можете использовать CDVPluginResult для возврата различных типов результатов в JavaScript обратные вызовы, используя методы класса, которые следуют этой схеме:

+ (CDVPluginResult*)resultWithStatus:(CDVCommandStatus)statusOrdinal messageAs...

Вы можете создать типы String, Int, Double, Bool, Array, Dictionary, ArrayBuffer, и Multipart. Вы также можете опустить любые аргументы для отправки состояния, или вернуть ошибку, или даже не отправлять результат плагина, в этом случае ни один обратный вызов не срабатывает.

Обратите внимание на следующее для сложных значений возврата:

• messageAsArrayBuffer ожидает NSData* и преобразует в ArrayBuffer в обратном вызове JavaScript. Аналогично, любые ArrayBuffer которые JavaScript отправляет плагину, преобразуются в NSData*.

• messageAsMultipart ожидает массив NSArray*, содержащий любые другие поддерживаемые типы, и отправляет весь массив как arguments в ваш обратный вызов JavaScript. Таким образом, все аргументы сериализуются или десериализуются по мере необходимости, поэтому безопасно возвращать NSData* как многокомпонентные, но не как Array/Dictionary.

Пример плагина Echo iOS

Чтобы соответствовать интерфейсу JavaScript функции echo, описанной в плагинах приложения, используйте plugin.xml для инъекции спецификации feature в файл config.xml локальной платформы:

<platform name="ios">
    <config-file target="config.xml" parent="/*">
        <feature name="Echo">
            <param name="ios-package" value="Echo" />
        </feature>
    </config-file>
</platform>

Затем мы добавим следующие файлы Echo.h и Echo.m в папку Plugins в каталоге приложения Cordova-iOS:

/********* Echo.h Cordova Plugin Header *******/

#import <Cordova/CDVPlugin.h>

@interface Echo : CDVPlugin

- (void)echo:(CDVInvokedUrlCommand*)command;

@end

/********* Echo.m Cordova Plugin Implementation *******/

#import "Echo.h"
#import <Cordova/CDVPlugin.h>

@implementation Echo

- (void)echo:(CDVInvokedUrlCommand*)command
{
    CDVPluginResult* pluginResult = nil;
    NSString* echo = [command.arguments objectAtIndex:0];

    if (echo != nil && [echo length] > 0) {
        pluginResult = [CDVPluginResult resultWithStatus:CDVCommandStatus_OK messageAsString:echo];
    } else {
        pluginResult = [CDVPluginResult resultWithStatus:CDVCommandStatus_ERROR];
    }

    [self.commandDelegate sendPluginResult:pluginResult callbackId:command.callbackId];
}

@end

Необходимые импорты в верхней части файла расширяют класс от CDVPlugin. В данном случае плагин поддерживает только одно действие echo. Он получает строку echo, вызывая метод objectAtIndex, чтобы получить первый параметр массива arguments, который соответствует аргументам, переданным функцией JavaScript exec().

Он проверяет параметр, чтобы убедиться, что он не nil или пустая строка, возвращая PluginResult со статусом ERROR, если это так. Если параметр проходит проверку, он возвращает PluginResult со статусом OK, передавая исходную строку echo. Наконец, он отправляет результат в self.commandDelegate, что выполняет обратные вызовы успеха или ошибки метода exec на стороне JavaScript. Если вызывается обратный вызов успеха, он передаёт параметр echo.

Интеграция iOS

Класс CDVPlugin содержит другие методы, которые ваш плагин может переопределить. Например, вы можете обрабатывать события паузы, возобновления, завершения работы приложения и handleOpenURL. Обратитесь к классам CDVPlugin.h и CDVPlugin.m для получения руководства.

Потоки

Методы плагинов обычно выполняются в том же потоке, что и основной интерфейс. Если ваш плагин требует значительной обработки или требует вызова блокировки, вы должны использовать фоновый поток. Например:

- (void)myPluginMethod:(CDVInvokedUrlCommand*)command
{
    // Check command.arguments here.
    [self.commandDelegate runInBackground:^{
        NSString* payload = nil;
        // Some blocking logic...
        CDVPluginResult* pluginResult = [CDVPluginResult resultWithStatus:CDVCommandStatus_OK messageAsString:payload];
        // The sendPluginResult method is thread-safe.
        [self.commandDelegate sendPluginResult:pluginResult callbackId:command.callbackId];
    }];
}

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

Для отладки на стороне Objective-C вам понадобится встроенный отладчик Xcode. Для JavaScript вы можете подключить Safari к приложению, запущенному в симуляторе или устройстве iOS.

Общие ошибки

• Не забудьте добавить сопоставление вашего плагина в config.xml. Если вы это забудете, в консоли Xcode будет выведено сообщение об ошибке.

• Не забудьте добавить все хосты, к которым вы подключаетесь, в список разрешенных, как описано в Руководстве по списку разрешенных доменов. Если вы забудете, в консоли Xcode будет выведено сообщение об ошибке.