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

Плагин — это пакет встраиваемого кода, который позволяет Cordova webview, в котором отображается приложение, взаимодействовать с родной платформой, на которой оно работает. Плагины обеспечивают доступ к функциям устройства и платформы, которые обычно недоступны веб-приложениям. Все основные функции Cordova API реализованы как плагины, и многие другие доступны, например, для сканеров штрих-кодов, коммуникации NFC или настройки интерфейсов календаря. Вы можете найти доступные плагины на странице поиска плагинов Cordova по адресу Cordova Plugin Search page.

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

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

В дополнение к этим инструкциям при подготовке к написанию плагина рекомендуется ознакомиться с существующими плагинами для получения руководства.

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

Разработчики приложений используют команду CLI plugin add для добавления плагина в проект. Аргументом этой команды является URL-адрес репозитория git, содержащего код плагина. В этом примере реализован API устройства Cordova:

cordova plugin add https://git-wip-us.apache.org/repos/asf/cordova-plugin-device.git

Репозиторий плагина должен содержать файл манифеста верхнего уровня plugin.xml. Существует множество способов его настройки, подробности о которых доступны в Спецификации плагина. В этой сокращенной версии плагина Device приводится простой пример для использования в качестве модели:

<?xml version="1.0" encoding="UTF-8"?>
<plugin xmlns="http://apache.org/cordova/ns/plugins/1.0"
        id="cordova-plugin-device" version="0.2.3">
    <name>Device</name>
    <description>Cordova Device Plugin</description>
    <license>Apache 2.0</license>
    <keywords>cordova,device</keywords>
    <js-module src="www/device.js" name="device">
        <clobbers target="device" />
    </js-module>
    <platform name="ios">
        <config-file target="config.xml" parent="/*">
            <feature name="Device">
                <param name="ios-package" value="CDVDevice"/>
            </feature>
        </config-file>
        <header-file src="src/ios/CDVDevice.h" />
        <source-file src="src/ios/CDVDevice.m" />
    </platform>
</plugin>

Атрибут тега верхнего уровня plugin с атрибутом id использует тот же формат обратного доменного имени для идентификации пакета плагина, что и приложения, к которым они добавляются. Тег js-module указывает путь к общему JavaScript-интерфейсу. Тег platform указывает соответствующий набор кода нативной платформы для платформы ios в этом случае. Тег config-file включает тег feature, который встраивается в файл config.xml соответствующей нативной платформы, чтобы сообщить платформе о дополнительной библиотеке кода. Теги header-file и source-file указывают путь к компонентам библиотеки.

Проверка плагина с помощью Plugman

Вы можете использовать утилиту plugman для проверки правильности установки плагина на каждой платформе. Установите plugman с помощью следующей команды node:

npm install -g plugman

Вам нужен действительный каталог исходного приложения, например, каталог верхнего уровня www, включенный в проект, сгенерированный по умолчанию CLI, как описано в руководстве Создание вашего первого приложения.

Затем выполните команду, подобную следующей, чтобы проверить правильность загрузки зависимостей iOS:

plugman install --platform ios --project /path/to/my/project/www --plugin /path/to/my/plugin

Подробные сведения о параметрах plugman см. в разделе Использование Plugman для управления плагинами. Подробные сведения о том, как фактически отлаживать плагины, см. в списке интерфейсов нативных платформ внизу этой страницы.

Интерфейс JavaScript

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

cordova.exec(function(winParam) {},
             function(error) {},
             "service",
             "action",
             ["firstArgument", "secondArgument", 42, false]);

Вот как работает каждый параметр:

• function(winParam) {}: Функция обратного вызова успеха. Если вызов exec завершится успешно, выполняется эта функция вместе с любыми параметрами, которые вы ей передали.

• function(error) {}: Функция обратного вызова ошибки. Если операция не завершится успешно, эта функция выполняется с необязательным параметром ошибки.

• "service": Имя службы для вызова на стороне нативной платформы. Это соответствует нативному классу, более подробную информацию о котором можно найти в нативных руководствах, перечисленных ниже.

• "action": Имя действия для вызова на стороне нативной платформы. Обычно это соответствует методу нативного класса. См. нативные руководства, перечисленные ниже.

• [/* arguments */]: Массив аргументов для передачи в нативную среду.

Пример JavaScript

В этом примере показано один из способов реализации интерфейса JavaScript плагина:

window.echo = function(str, callback) {
    cordova.exec(callback, function(err) {
        callback('Nothing to echo.');
    }, "Echo", "echo", [str]);
};

В этом примере плагин присоединяется к объекту window в качестве функции echo, которую пользователи плагина вызовут следующим образом:

window.echo("echome", function(echoValue) {
    alert(echoValue == "echome"); // should alert true.
});

Обратите внимание на последние три аргумента, переданные функции cordova.exec. Первый вызывает Echo сервис, имя класса. Второй запрашивает echo действие, метод внутри этого класса. Третий — массив аргументов, содержащий строку эха, которая является первым параметром функции window.echo.

Функция обратного вызова успеха, переданная в exec, просто ссылка на функцию обратного вызова window.echo. Если нативная платформа вызывает функцию обратного вызова ошибки, она просто вызывает функцию обратного вызова успеха и передает ей строку по умолчанию.

Нативные интерфейсы

После определения JavaScript для своего плагина необходимо дополнить его по крайней мере одной реализацией нативной платформы. Подробности для каждой платформы указаны ниже, и каждая из них основана на простом примере плагина Echo:

• Плагины Android
• Плагины iOS
• Плагины BlackBerry 10
• Плагины Windows Phone 8
• Плагины Windows

Публикация плагинов

Вы можете опубликовать свой плагин в любом реестре на основе npmjs, но рекомендуемым является реестр npm. Другие разработчики могут автоматически установить ваш плагин, используя либо plugman или Cordova CLI.

Чтобы опубликовать плагин в npm, выполните следующие шаги:

• установите plugman CLI:

  $ npm install -g plugman
  

• создайте файл package.json для вашего плагина:

  $ plugman createpackagejson /path/to/your/plugin
  

• опубликуйте его:

  $ npm adduser # that is if you don't have an account yet
  $ npm publish /path/to/your/plugin
  

Дополнительные сведения об использовании npm см. в разделе Публикация пакетов npm на сайте документации npm.

Интеграция с поиском плагинов

Чтобы отобразить плагин в поиске плагинов Cordova, добавьте ключевое слово ecosystem:cordova в файл package.json вашего плагина перед публикацией.

Чтобы указать поддержку определенной платформы, добавьте ключевое слово в формате **cordova-<platformName>** в список ключевых слов в файле package.json. Команда Plugman's createpackagejson выполняет эту операцию за вас, но если вы не использовали её для генерации вашего package.json, вам следует вручную отредактировать его, как показано ниже.

Например, для плагина, поддерживающего Android, iOS и Windows, ключевые слова в файле package.json должны включать:

"keywords": [
    "ecosystem:cordova",
    "cordova-android",
    "cordova-ios",
    "cordova-windows"
]

Для более подробного примера файла package.json см. файл package.json cordova-plugin-device.

Указание зависимостей Cordova

Cordova 6.1.0 добавила поддержку указания зависимостей Cordova для плагина в файле package.json плагина. Плагины могут перечислить зависимости для нескольких выпусков, чтобы помочь Cordova CLI при выборе версии плагина для извлечения из npm. CLI выберет последнюю версию плагина, совместимую с установленных платформ и плагинов локального проекта, а также с версией локального Cordova CLI. Если ни один выпуск плагина не совместим, CLI предупредит пользователя о невыполненных требованиях и вернется к старому поведению извлечения последнего выпуска.

Эта функция предназначена для того, чтобы в конечном итоге заменить элемент engines в файле plugin.xml. Перечисление зависимостей — хороший способ убедиться, что ваш плагин не будет выглядеть неисправным или вызывать ошибки компиляции при извлечении из npm. Если последняя версия плагина несовместима с проектом, CLI предоставит разработчику приложения список невыполненных требований проекта, чтобы он знал о несовместимостях и мог обновить свой проект для поддержки вашего плагина. Это позволяет вашему плагину реагировать на изменения в поведении без риска сбивать с толку разработчиков, работающих со старыми платформами и плагинами.

Чтобы указать зависимости Cordova для плагина, измените элемент engines в файле package.json так, чтобы он включал объект cordovaDependencies со следующей структурой:

"engines": {
    "cordovaDependencies": {
        PLUGIN_VERSION: {
            DEPENDENCY: SEMVER_RANGE,
            DEPENDENCY: SEMVER_RANGE,
            ...
        },
        ...
    }
}

• PLUGIN_VERSION указывает версию вашего плагина. Она должна соответствовать синтаксису для отдельной версии, определенному в пакете semver npm или верхней границе (см. ниже)
• DEPENDENCY может быть одним из следующих:
  • Cordova CLI: "cordova"
  • Платформа Cordova: "cordova-android", "cordova-ios", "cordova-windows", и т.д.
  • Другой плагин Cordova: "cordova-plugin-camera", и т.д.
• SEMVER_RANGE должен соответствовать синтаксису диапазона, определенному в пакете semver npm

ПРИМЕЧАНИЕ: Платформа Cordova DEPENDENCY относится к платформе Cordova, а не к ОС, т.е. cordova-android , а не к Android OS.

Ваш cordovaDependencies может перечислить любое количество требований PLUGIN_VERSION и любое количество ограничений DEPENDENCY. Версии вашего плагина, в которых не перечислены зависимости, будут предполагать ту же информацию о зависимостях, что и у самой высокой PLUGIN_VERSION версии ниже них. Например, рассмотрите следующую запись:

"engines": {
    "cordovaDependencies": {
        "1.0.0": { "cordova-android": "<3.0.0"},
        "2.1.0": { "cordova-android": ">4.0.0"}
    }
}

Все версии плагина ниже самой низкой записи (1.0.0 в этом примере) предполагаются без зависимостей. Любая версия плагина между 1.0.0 и 2.1.0 предполагается с теми же зависимостями, что и версия 1.0.0 (версия cordova-android меньше 3.0.0). Это позволяет обновлять информацию о ваших cordovaDependencies только при внесении изменений в функционал.

Верхние границы

Помимо отдельной версии, PLUGIN_VERSION в cordovaDependencies также может указывать верхнюю границу, чтобы изменить записи для более старых версий вашего плагина. Это полезно, когда происходит критическая смена в DEPENDENCY и необходимо добавить новое ограничение для всех более старых версий плагина, которые его не поддерживают. Эти границы должны быть записаны как < и за ним должна следовать единственная версия semver (не произвольный диапазон!). Это применит любые DEPENDENCY значения ко всем версиям плагина ниже указанной версии. Например, рассмотрите следующую запись:

"engines": {
    "cordovaDependencies": {
        "0.0.1":  { "cordova-ios": ">1.0.0" },
        "<1.0.0": { "cordova-ios": "<2.0.0" },
        "<2.0.0": { "cordova-ios": "<5.0.0" }
    }
}

Здесь мы указываем одну версию плагина (0.0.1) и две верхние границы (<1.0.0 и <2.0.0), которые ограничивают cordova-ios. Две верхние границы не переопределяют ограничение 0.0.1, они объединяются через И при оценке. Когда CLI проверяет версию cordova-ios проекта, ограничение, которое будет оцениваться для версии плагина 0.0.1, будет комбинацией этих трёх:

cordova-ios >1.0.0 AND cordova-ios <2.0.0 AND cordova-ios <5.0.0

Обратите внимание, что допустимы только значения PLUGIN_VERSION — это одиночные версии или верхние границы; другие диапазоны semver не поддерживаются.