Плагины

Введение

Плагины 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/Не-JavaScript) не являются файлами bat (что рекомендуется, если вы хотите, чтобы ваши скрипты работали в других операционных системах), 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