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

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

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

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

Родные интерфейсы

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

• Плагины Android
• Плагины iOS
• Плагины 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. Команда createpackagejson Plugman сделает это за вас, но если вы не использовали её для генерации 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.

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