Плагины

Введение

Плагины 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/android/appAndroidBeforeBuild.bat" />
    <hook type="before_build" src="scripts/android/appAndroidBeforeBuild.js" />
    <hook type="before_plugin_install" src="scripts/android/appAndroidBeforePluginInstall.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

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

JavaScript

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

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

Вот пример, демонстрирующий содержимое объекта context.

{
  // The type of hook being run
  hook: 'before_plugin_install',

  // Absolute path to the hook script that is currently executing
  scriptLocation: '/foo/scripts/appBeforePluginInstall.js',

  // The CLI command that lead to this hook being executed
  cmdLine: 'cordova plugin add plugin-withhooks',

  // The options associated with the current operation.
  // WARNING: The contents of this object vary among the different
  // operations and are currently not documented anywhere.
  opts: {
    projectRoot: '/foo',

    cordova: {
      platforms: ['android'],
      plugins: ['plugin-withhooks'],
      version: '0.21.7-dev'
    },

    // Information about the plugin currently operated on.
    // This object will only be passed to plugin hooks scripts.
    plugin: {
      id: 'plugin-withhooks',
      pluginInfo: { /* ... */ },
      platform: 'android',
      dir: '/foo/plugins/plugin-withhooks'
    }
  },

  // A reference to Cordova's API
  cordova: { /* ... */ }
}

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

const cordovaCommon = context.requireCordovaModule('cordova-common');

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

module.exports = context => {
    return new Promise(resolve => {
        const start = Date.now();
        setTimeout(() => resolve(Date.now() - start), 1000);
    }).then(msWaited => {
        console.log(`${context.scriptLocation} waited ${msWaited} ms`);
    });
};

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

Не-JavaScript

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

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

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

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

Если вы работаете в Windows, а ваши скрипты плагинов не являются файлами *.bat, Cordova CLI ожидает строку shebang в первой строке скрипта. Таким образом, он знает интерпретатор, который нужно использовать для запуска скрипта. Строка shebang для скрипта Python может выглядеть так:

#!/usr/bin/env python

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

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

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

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

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

const fs = require('fs');
const util = require('util');
const stat = util.promisify(fs.stat);

module.exports = function(ctx) {
    // Make sure android platform is part of build
    if (!ctx.opts.platforms.includes('android')) return;

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

    return stat(apkFileLocation).then(stats => {
      console.log(`Size of ${apkFileLocation} is ${stats.size} bytes`);
    });
};

Параметр 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 Phone Gap