13、Hooks（基础知识）

翻译自cordova官方文档（如果需要链接，请自行对照原文链接进行查看）：
https://cordova.apache.org/docs/en/latest/cordova/storage/storage.html

Hooks

介绍

Cordova Hooks提供使用应用程序添加特定脚本或者插件甚至你自己编译系统的自定义命令。
Cordova hooks允许你根据Cordova命令执行特定的行为，比如当你检查代码格式的时候，在build命令执行结束后做点什么，比如你可以通过’before_build’hook’来通知cordova在执行build指令之前干点什么。
Hooks会自动关联到指定的命令上比如before_build,after_build等等。 或者关联到plugin的一些命令比如before_plugin_add, after_plugin_add等等。这个Hooks会关联到所有plugin命令，或者是指定的某一个plugin。
Cordova支持如下的hook类型：

如何定义一个hook

Config.xml

Hooks在config.xml文件内用声明，比如:

<hooktype="before_build"src="scripts/appBeforeBuild.bat" /><hooktype="before_build"src="scripts/appBeforeBuild.js" /><hooktype="before_plugin_install"src="scripts/appBeforePluginInstall.js" /><platformname="android"><hooktype="before_build"src="scripts/wp8/appAndroidBeforeBuild.bat" /><hooktype="before_build"src="scripts/wp8/appAndroidBeforeBuild.js" /><hooktype="before_plugin_install"src="scripts/wp8/appWP8BeforePluginInstall.js" />
        ...
    </platform><platformname="windows"><hooktype="before_build"src="scripts/windows/appWinBeforeBuild.bat" /><hooktype="before_build"src="scripts/windows/appWinBeforeBuild.js" /><hooktype="before_plugin_install"src="scripts/windows/appWinBeforePluginInstall.js" />
        ...
    </platform>```
###Plugin hooks (plugin.xml)
 如果是为plugin设置hook，可以通过plugin.xml文件的<hook>标签来设置:

before_plugin_install, after_plugin_install, before_plugin_uninstall会在plugin安装和卸载的时候触发。
###通过/hooks目录 (不赞成使用)
在指定hook类型被触发的时候执行自定义脚本，通过hooks文件夹下的指定hook类型的名字的脚本文件来识别应该执行哪一个脚本:

script file will be automatically executed after each build

hooks/after_build/after_build_custom_action.js

当使用hooks的时候，文件需要当做可执行文件来使用，而不是一个可被加载的JavaScript模块。
##Hooks的指令
###Hooks的基本定义
Hook脚本可以通过添加到指定目录(/hooks)或者配置文件(config.xml andplugin.xml)来运行。

 - Application hooks from /hooks;
 - Application hooks from config.xml;
 - Plugin hooks from plugins/.../plugin.xml.
###内部指令
内部指令的执行顺序是固定的。
**Example 1 (cordova platform add)**
下面是设置的需要执行的hookbefore_platform_add, after_platform_add,before_prepare, after_prepare, 
before_plugin_install, after_plugin_install，当使用platform add指令的时候他们的执行顺序是这样的:

before_platform_add
before_prepare
after_prepare
before_plugin_install
after_plugin_install
after_platform_add

**Example 2 (cordova build)**
下面是设置的需要执行的hookbefore_prepare, after_prepare, before_compile,after_compile, before_build 
, after_build当执行build指令的时候他们的顺序是这样的:

before_build
before_prepare
after_prepare
before_compile
after_compile
after_build

##脚本接口
###Javascript
如果你使用nodejs来写hook，那么你需要像下面这样定义模块。

module.exports = function(context) {
…
}

context包含hook的类别，执行脚本的路径，hook的选项和command-line的参数等信息:

{
“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对象会被传递到执行脚本内部。
当然，你也可以通过context.requireCordovaModule引入Cordova模块:

var Q = context.requireCordovaModule(‘q’);

可以通过Q来是你的脚本异步执行(promise):

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;
}

###Non-javascript
Non-javascript脚本是通过node child_process加载root根目录的hook目录下的脚本。根目录会被作为第一个参数传入。其他可选参数是通过环境变量传入的。如下:
|环境变量|说明|
|:------|:-------|
|CORDOVA_VERSION|Cordova-CLI版本。|
|CORDOVA_PLATFORMS|逗号分割的平台列表。|
|CORDOVA_PLUGINS|都好分割的插件id列表。|
|CORDOVA_HOOK|执行路径。|
|CORDOVA_CMDLINE|扩展参数。|
如果hook脚本返回非0值，那么cordova的命令就会执行失败。
**Note: 我们强烈建议你使用nodejs来写hook，这样hook将是跨平台的。**
##实例
这个例子是演示cordova的hook如何通过控制台输出apk文件大小。
创建一个空的cordova项目，修改config.xml告诉他在cordova build指令以后需要执行afterBuild.js。

创建scripts/afterBuild.js文件，并且像下面那样编写代码，我们可以通过使用异步版本的fs.stat函数来演示如何使用异步函数。

module.exports = function(ctx) {
// make sure android platform is part of buildif (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参数提供了脚本的路径，目标平台，命令行参数等信息。参考Script Interface可以获取更多信息。
你可以通过下面命令来触发hook:

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