Руководство по хукам

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

Хуки приложения из /hooks;
Хуки приложения из config.xml;
Хуки плагинов из plugins/.../plugin.xml.

Примечание: Каталог /hooks считается устаревшим и заменяется элементами hook в файлах config.xml и plugin.xml.

Типы поддерживаемых хуков

Поддерживаются следующие типы хуков:

after_build
after_compile
after_clean
after_docs
after_emulate
after_platform_add
after_platform_rm
after_platform_ls
after_plugin_add
after_plugin_ls
after_plugin_rm
after_plugin_search
after_plugin_install // Plugin hooks in plugin.xml are executed for a plugin being installed only
after_prepare
after_run
after_serve
before_build
before_clean
before_compile
before_docs
before_emulate
before_platform_add
before_platform_rm/
before_platform_ls
before_plugin_add
before_plugin_ls
before_plugin_rm
before_plugin_search/
before_plugin_install // Plugin hooks in plugin.xml are executed for a plugin being installed only
before_plugin_uninstall // Plugin hooks in plugin.xml are executed for a plugin being uninstalled only
before_prepare
before_run
before_serve
pre_package // Windows and Windows Phone only

Способы определения хуков

Через каталог `/hooks`

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

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

# Файл скрипта будет автоматически выполняться после каждой сборки
hooks/after_build/after_build_custom_action.js

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

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="wp8">
    <hook type="before_build" src="scripts/wp8/appWP8BeforeBuild.bat" />
    <hook type="before_build" src="scripts/wp8/appWP8BeforeBuild.js" />
    <hook type="before_plugin_install" src="scripts/wp8/appWP8BeforePluginInstall.js" />
    ...
</platform>

<platform name="windows8">
    <hook type="before_build" src="scripts/windows8/appWin8BeforeBuild.bat" />
    <hook type="before_build" src="scripts/windows8/appWin8BeforeBuild.js" />
    <hook type="before_plugin_install" src="scripts/windows8/appWin8BeforePluginInstall.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="wp8">
    <hook type="before_plugin_install" src="scripts/wp8BeforeInstall.js" />
    <hook type="before_build" src="scripts/wp8BeforeBuild.js" />
    ...
</platform>

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

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

Javascript

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

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

Вы можете сделать ваши скрипты асинхронными, используя 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;
}

Объект контекста содержит тип хука, полный путь исполняемого скрипта, параметры хука, аргументы командной строки, передаваемые 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": ["wp8"],
      "plugins": ["com.plugin.withhooks"],
      "version": "0.21.7-dev"
    },
    "plugin": {
      "id": "com.plugin.withhooks",
      "pluginInfo": {
        ...
      },
      "platform": "wp8",
      "dir": "C:\\path\\to\\the\\project\\plugins\\com.plugin.withhooks"
    }
  },
  "cordova": {...}
}

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

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

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

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

Не-javascript

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

Не-javascript сценарии запускаются через узел child_process.spawn из корневого каталога проекта и получают корневой каталог в качестве первого аргумента. Все остальные параметры передаются в сценарий с помощью переменных среды:

CORDOVA_VERSION - версия Cordova-CLI.
CORDOVA_PLATFORMS - разделенный запятыми список платформ, к которым команда применяется (например: android, ios).
CORDOVA_PLUGINS - разделенный запятыми список идентификаторов плагинов, к которым команда применяется (например: org.apache.cordova.file, org.apache.cordova.file)
CORDOVA_HOOK - путь к выполняемому хуку.
CORDOVA_CMDLINE - точные аргументы командной строки, передаваемые cordova (например: cordova run ios --emulate)

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

Кроме того обратите внимание, что даже если вы работаете на Windows, и в случае, если ваши скрипты хуков не bat файлы (что рекомендуется, если вы хотите, чтобы ваши скрипты работали не только на Windows) Cordova CLI будет ожидать shabang линию в качестве первой линии для того чтобы знать какой интерпретатор необходимо использовать для запуска сценария. Shebang линия должна соответствовать следующему примеру:

#!/usr/bin/env [name_of_interpreter_executable]

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

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

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

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

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

module.exports = function(ctx) {
    // Убедитесь что платформа android является частью построения 
    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('Операция неуспешна');
        } else {
            console.log('Размер ' + apkFileLocation + ' равен ' + stats.size +' байт');
            deferral.resolve();
        }
    });

    return deferral.promise;
};

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

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

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

Более хорошие примеры использования можно найти здесь:

http://devgirl.org/2013/11/12/three-hooks-your-cordovaphonegap-project-needs/