Хуксы

Введение

Хуксы 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 (что рекомендуется, если вы хотите, чтобы ваши скрипты работали в операционных системах, отличных от 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