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

Плагин — это пакет встраиваемого кода, который позволяет веб-вьюверу Cordova, в котором отображается приложение, взаимодействовать с родной платформой, на которой оно работает. Плагины предоставляют доступ к функциям устройства и платформы, которые обычно недоступны веб-приложениям. Все основные функции API Cordova реализованы как плагины, а также доступно множество других, обеспечивающих функции, такие как сканеры штрих-кодов, 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 использует тот же обратный доменный формат для идентификации пакета плагина, что и приложения, к которым они добавляются. Тег 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 действие, метод внутри этого класса. Третий — массив аргументов, содержащий строку echo, которая является первым параметром функции window.echo.

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

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

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

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

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

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

Для публикации плагина в npm необходимо выполнить следующие шаги:

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

  $ 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 не поддерживаются.