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

Плагин — это пакет вставленного кода, который позволяет веб-вьюверу 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
• Плагины Windows

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

Вы можете опубликовать свой плагин в любой базе данных, основанной на npmjs, но рекомендуется использовать npm registry. Другие разработчики могут автоматически установить ваш плагин, используя либо 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. Команда 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 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 не поддерживаются.