Плагины

Введение

Плагины Cordova представляют собой специальные скрипты, которые могут быть добавлены разработчиками приложений и плагинов, а также вашей собственной системой сборки для настройки команд cordova.

Плагины Cordova позволяют выполнять специальные действия вокруг команд cordova. Например, у вас может быть инструмент, который проверяет форматирование кода в вашем файле javascript. И вы хотите запустить этот инструмент перед каждой сборкой. В этом случае вы можете использовать плагин «before_build» и указать среде выполнения cordova запустить этот инструмент перед каждой сборкой.

Плагины могут быть связаны с вашими действиями по приложению, такими как before_build, after_build, и т.д. Или же они могут быть связаны с плагинами вашего приложения. Например, такие плагины, как before_plugin_add, after_plugin_add, и т.д., применяются к действиям, связанным с плагинами. Эти плагины могут быть связаны со всеми плагинами в вашем приложении или только с одним плагином.

Cordova поддерживает следующие типы плагинов:

Способы определения плагинов

Config.xml

Плагины могут быть определены в файле проекта config.xml с помощью элементов <hook>, например:

<hook type="before_build" src="scripts/appBeforeBuild.bat" />
<hook type="before_build" src="scripts/appBeforeBuild.js" />
<hook type="before_plugin_install" src="scripts/appBeforePluginInstall.js" />

<platform name="android">
    <hook type="before_build" src="scripts/wp8/appAndroidBeforeBuild.bat" />
    <hook type="before_build" src="scripts/wp8/appAndroidBeforeBuild.js" />
    <hook type="before_plugin_install" src="scripts/wp8/appWP8BeforePluginInstall.js" />
    ...
</platform>

<platform name="windows">
    <hook type="before_build" src="scripts/windows/appWinBeforeBuild.bat" />
    <hook type="before_build" src="scripts/windows/appWinBeforeBuild.js" />
    <hook type="before_plugin_install" src="scripts/windows/appWinBeforePluginInstall.js" />
    ...
</platform>

Плагины (plugin.xml)

Как разработчик плагинов, вы можете определить скрипты плагинов, используя элементы <hook> в файле plugin.xml так:

<hook type="before_plugin_install" src="scripts/beforeInstall.js" />
<hook type="after_build" src="scripts/afterBuild.js" />

<platform name="android">
    <hook type="before_plugin_install" src="scripts/androidBeforeInstall.js" />
    <hook type="before_build" src="scripts/androidBeforeBuild.js" />
    ...
</platform>

before_plugin_install, after_plugin_install, before_plugin_uninstall плагины будут вызываться исключительно для установленного/удаленного плагина.

Папка /hooks (Устарело)

Для выполнения пользовательских действий при срабатывании соответствующего типа плагина используйте тип плагина в качестве имени подкаталога в каталоге 'hooks' и поместите ваш скрипт в него, например:

# script file will be automatically executed after each build
hooks/after_build/after_build_custom_action.js

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

Помните: сделайте ваши скрипты исполняемыми в этом случае.

Примечание: этот метод считается устаревшим в пользу элементов плагина в файлах config.xml и plugin.xml.

Порядок выполнения плагинов

Основанный на определении плагинов

Скрипты плагинов могут быть определены путём добавления их в специальную предопределённую папку (/hooks) или через конфигурационные файлы (config.xml и plugin.xml) и выполняются последовательно в следующем порядке:

• Плагины приложения из /hooks;
• Плагины приложения из config.xml;
• Плагины плагинов из plugins/.../plugin.xml.

Основанный на внутреннем порядке выполнения

Внутренний порядок выполнения плагинов фиксирован.

Пример 1 (cordova platform add)

Если существуют плагины, связанные с before_platform_add, after_platform_add, before_prepare, after_prepare, before_plugin_install и after_plugin_install (и предполагая, что у вас установлен один плагин в вашем проекте), добавление новой платформы выполнит плагины в следующем порядке:

before_platform_add
    before_prepare
    after_prepare
    before_plugin_install
    after_plugin_install
after_platform_add

Пример 2 (cordova build)

Если существуют плагины, связанные с before_prepare, after_prepare, before_compile, after_compile, before_build и after_build - выполнение команды сборки выполнит плагины в следующем порядке:

before_build
    before_prepare
    after_prepare
    before_compile
    after_compile
after_build

Интерфейс скрипта

Особенности Windows

Если вы работаете в Windows, и в случае, если ваши скрипты плагинов (Javascript/Non-Javascript) не являются файлами bat (что рекомендуется, если вы хотите, чтобы ваши скрипты работали в не-Windows операционных системах), Cordova CLI будет ожидать строку shebang в первой строке, чтобы определить интерпретатор, который необходимо использовать для запуска скрипта. Строка shebang должна соответствовать следующему примеру:

#!/usr/bin/env [name_of_interpreter_executable]

Javascript

Если вы пишете плагины с использованием Node.js, вы должны использовать следующее определение модуля:

module.exports = function(context) {
    ...
}

Объект context содержит тип плагина, полный путь к исполняемому скрипту, опции плагина, аргументы командной строки, переданные Cordova, и верхнеуровневый объект "cordova" следующего формата:

{
  "hook": "before_plugin_install",
  "scriptLocation": "c:\\script\\full\\path\\appBeforePluginInstall.js",
  "cmdLine": "The\\exact\\command\\cordova\\run\\with arguments",
  "opts": {
    "projectRoot":"C:\\path\\to\\the\\project",
    "cordova": {
      "platforms": ["android"],
      "plugins": ["plugin-withhooks"],
      "version": "0.21.7-dev"
    },
    "plugin": {
      "id": "plugin-withhooks",
      "pluginInfo": {
        ...
      },
      "platform": "android",
      "dir": "C:\\path\\to\\the\\project\\plugins\\plugin-withhooks"
    }
  },
  "cordova": {...}
}

Объект context.opts.plugin будет передан только скриптам плагинов.

Вы также можете загрузить дополнительные модули Cordova в свой скрипт, используя context.requireCordovaModule следующим образом:

var Q = context.requireCordovaModule('q');

Вы можете сделать свои скрипты асинхронными, используя Q:

module.exports = function(context) {
    var Q = context.requireCordovaModule('q');
    var deferral = new Q.defer();

    setTimeout(function(){
      console.log('hook.js>> end');
    deferral.resolve();
    }, 1000);

    return deferral.promise;
}

Примечание: новый интерфейс загрузчика модулей используется для файлов .js , определенных через config.xml или plugin.xml . По соображениям совместимости файлы плагинов, указанные через каталоги /hooks , запускаются через Node child_process spawn, см. раздел «Не-JavaScript» ниже.

Не-JavaScript

Скрипты, не являющиеся JavaScript, выполняются через Node child_process spawn из корневого каталога проекта, и корневой каталог передаётся в качестве первого аргумента. Все остальные параметры передаются в скрипт с помощью переменных среды:

Если скрипт возвращает код выхода, отличный от нуля, то родительская команда Cordova будет прервана.

Примечание: настоятельно рекомендуется писать свои плагины с использованием Node.js, чтобы они были кроссплатформенными, см. раздел Javascript выше.

Пример использования

Этот пример демонстрирует использование плагинов Cordova для вывода в консоль размера сгенерированного файла .apk для платформы Android.

Создайте пустое приложение Cordova и добавьте следующее определение в config.xml , чтобы указать Cordova на выполнение скрипта afterBuild.js после каждой сборки платформы.

<hook type="after_build" src="scripts/afterBuild.js" />

Создайте файл scripts/afterBuild.js и добавьте следующее реализацию. Мы используем асинхронную версию метода fs.stat , чтобы продемонстрировать, как можно реализовать асинхронность через плагины.

module.exports = function(ctx) {
    // make sure android platform is part of build
    if (ctx.opts.platforms.indexOf('android') < 0) {
        return;
    }
    var fs = ctx.requireCordovaModule('fs'),
        path = ctx.requireCordovaModule('path'),
        deferral = ctx.requireCordovaModule('q').defer();

    var platformRoot = path.join(ctx.opts.projectRoot, 'platforms/android');
    var apkFileLocation = path.join(platformRoot, 'build/outputs/apk/android-debug.apk');

    fs.stat(apkFileLocation, function(err,stats) {
        if (err) {
                deferral.reject('Operation failed');
        } else {
            console.log('Size of ' + apkFileLocation + ' is ' + stats.size +' bytes');
            deferral.resolve();
        }
    });

    return deferral.promise;
};

Параметр ctx в примере выше передаётся Cordova и представляет контекст выполнения, такой как полный путь к скрипту, целевая платформа, аргументы командной строки и т.д., а также предоставляет дополнительную вспомогательную функциональность. Подробнее см. раздел Script Interface выше.

Теперь можно добавить платформу Android и выполнить сборку.

cordova platform add android
..
cordova build
..
Size of path\to\app\platforms\android\build\outputs\apk\android-debug.apk is 1821193 bytes

Дополнительные примеры хорошего использования можно найти в Трех плагинах, необходимых для вашего проекта Cordova PhoneGap