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

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

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

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

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

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

    $ 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="org.apache.cordova.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 с помощью следующей команды узла :

    $ npm install -g plugman

Вам нужно действительный app исходного каталога, например верхнего уровня www каталог, включенных в проект, созданный CLI по умолчанию, как описано в интерфейс командной строки. Убедитесь, что приложение index.html Главная страница ссылаются на имя плагина интерфейс JavaScript, как будто это в той же директории источника:

    <script src="myplugin.js"></script>

Затем выполните команду следующих для тестирования iOS зависимости нагрузки должным образом:

    $ plugman -platform ios /path/to/my/project/www /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 для вашего плагина, необходимо дополнить его по крайней мере один собственной реализации. Детали для каждой платформы перечислены ниже, и каждый основывается на простой пример эхо плагин выше:

Платформа Tizen не поддерживает плагины.

Публикации плагины

После того как вы развивать ваш плагин, вы можете опубликовать и поделиться им с сообществом. Вы можете опубликовать ваш плагин в реестре Кордова (на основе npmjs ) или в любой другой npmjs -на основе реестра. Другие разработчики могут установить его автоматически с помощью plugman или Кордова CLI. (Подробную информацию о каждом пути развития, см. Использование Plugman для управления плагины и интерфейс командной строки.)

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

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

Вот оно что!

Запуск plugman --help перечислены другие доступные команды на основе реестра.