摘要：任何初始化任務(wù)應(yīng)該在文件中的事件的事件處理函數(shù)中。這個(gè)配置文件有幾個(gè)地方很關(guān)鍵，一開始沒有認(rèn)真看，將插件導(dǎo)進(jìn)工程跑的時(shí)候各種問題，十分頭痛，不得不重新認(rèn)真看看文檔。

來新公司的第一個(gè)任務(wù)，研究hybrid App中間層實(shí)現(xiàn)原理，做中間層插件開發(fā)。這個(gè)任務(wù)挺有意思，也很有挑戰(zhàn)性，之前在DCloud雖然做過5+ App開發(fā)，但是中間層的東西確實(shí)涉及不多。本系列文章屬于系列開篇cordova學(xué)習(xí)筆記，本文主要是從零開始搭建一個(gè)cordova工程，并了解cordova開發(fā)的基本內(nèi)容。

Apache Cordova是一個(gè)開源的移動(dòng)開發(fā)框架。允許你用標(biāo)準(zhǔn)的web技術(shù)-HTML5,CSS3和JavaScript做跨平臺(tái)開發(fā)。 應(yīng)用在每個(gè)平臺(tái)的具體執(zhí)行被封裝了起來，并依靠符合標(biāo)準(zhǔn)的API綁定去訪問每個(gè)設(shè)備的功能，比如說：傳感器、數(shù)據(jù)、網(wǎng)絡(luò)狀態(tài)等。

Cordova官網(wǎng)：http://cordova.apache.org/
Cordova中文網(wǎng)：http://cordova.axuer.com/
Cordova中文站：http://www.cordova.org.cn/

npm install -g cordova

安裝完成可以通過cordova -v查看版本號(hào)，本文是在V6.5.0下構(gòu)建。

cordova create  [ID [NAME [CONFIG]]] [options]

Create a Cordova project：

PATH —— 項(xiàng)目路徑

ID —— app 包名 - used in

NAME —— app 名稱

CONFIG —— 配置文件地址 json string whose key/values will be included in [PATH]/.cordova/config.json

Options：

--template= ... use a custom template located locally, in NPM, or GitHub.

--copy-from|src= .................. deprecated, use --template instead.

--link-to= ........................ symlink to custom www assets without creating a copy.

Example：

cordova create hello-cordova io.zhaomenghuan HelloCordova

這將會(huì)為你的cordova應(yīng)用創(chuàng)造必須的目錄。默認(rèn)情況下，cordova create命令生成基于web的應(yīng)用程序的骨骼，項(xiàng)目的主頁是 www/index.html 文件。

所有后續(xù)命令都需要在項(xiàng)目目錄或者項(xiàng)目目錄的任何子目錄運(yùn)行：

cd hello-cordova

給你的App添加目標(biāo)平臺(tái)。我們將會(huì)添加ios和android平臺(tái)，并確保他們保存在了config.xml中：

cordova platform add ios --save
cordova platform add android --save

運(yùn)行add或者remove平臺(tái)的命令將會(huì)影響項(xiàng)目platforms的內(nèi)容，在這個(gè)目錄中每個(gè)指定平臺(tái)都有一個(gè)子目錄。

注意：在你使用CLI創(chuàng)建應(yīng)用的時(shí)候， 不要 修改/platforms/目錄中的任何文件。當(dāng)準(zhǔn)備構(gòu)建應(yīng)用或者重新安裝插件時(shí)這個(gè)目錄通常會(huì)被重寫。

檢查你當(dāng)前平臺(tái)設(shè)置狀況：

cordova platform is

Installed platforms:
  android 6.1.2
Available platforms:
  amazon-fireos ~3.6.3 (deprecated)
  blackberry10 ~3.8.0
  browser ~4.1.0
  firefoxos ~3.6.3
  webos ~3.7.0
  windows ~4.4.0
  wp8 ~3.8.2 (deprecated)

安裝構(gòu)建先決條件：
要構(gòu)建和運(yùn)行App，你需要安裝每個(gè)你需要平臺(tái)的SDK。另外，當(dāng)你使用瀏覽器開發(fā)你可以添加 browser平臺(tái)，它不需要任何平臺(tái)SDK。

檢測你是否滿足構(gòu)建平臺(tái)的要求：

cordova requirements

Requirements check results for android:
Java JDK: installed 1.8.0
Android SDK: installed true
Android target: installed android-7,android-8,android-9,android-10,android-11,android-12,android-13,android-14,android-15,android-16,android-17,android-18,android-19,android-20,android-21,android-22,android-23,android-24,android-25
Gradle: installed

初次使用我們可能會(huì)遇到下面的報(bào)錯(cuò)：

Error: Failed to find "ANDROID_HOME" environment variable. Try setting setting it manually.
Failed to find "android" command in your "PATH". Try update your "PATH" to include path to valid SDK directory.

這是因?yàn)槲覀儧]有配置環(huán)境變量：

設(shè)置JAVA_HOME環(huán)境變量，指定為JDK安裝路徑

設(shè)置ANDROID_HOME環(huán)境變量，指定為Android SDK安裝路徑

添加Android SDK的tools和platform-tools目錄到你的PATH

對(duì)于android平臺(tái)下的環(huán)境配置在這里不再贅述，具體可以參考：

Android平臺(tái)的要求

iOS平臺(tái)的要求

Windows平臺(tái)的要求

默認(rèn)情況下,?cordova create生產(chǎn)基于web應(yīng)用程序的骨架，項(xiàng)目開始頁面位于www/index.html
?文件。任何初始化任務(wù)應(yīng)該在www/js/index.js文件中的deviceready事件的事件處理函數(shù)中。

運(yùn)行下面命令為所有添加的平臺(tái)構(gòu)建：

cordova build

你可以在每次構(gòu)建中選擇限制平臺(tái)范圍 - 這個(gè)例子中是android：

cordova build android

注意：首次使用時(shí)，命令行提示 Downloading https://services.gradle.org/distributions/gradle-2.14.1-all.zip，是在下載對(duì)應(yīng)的gradle并自動(dòng)解壓安裝，根據(jù)網(wǎng)絡(luò)狀況，可能耗時(shí)極長，且容易報(bào)錯(cuò)。

使用Cordova編譯Android平臺(tái)程序提示：Could not reserve enough space for 2097152KB object heap。

Error occurred during initialization of VM
Could not reserve enough space for 2097152KB object heap

大體的意思是系統(tǒng)內(nèi)存不夠用，創(chuàng)建VM失敗。試了網(wǎng)上好幾種方法都不行，最后這個(gè)方法可以了：

開始->控制面板->系統(tǒng)->高級(jí)設(shè)置->環(huán)境變量->系統(tǒng)變量
新建變量：
變量名: _JAVA_OPTIONS
變量值: -Xmx512M

我們有多種方式運(yùn)行我們的App，在不同場景下使用不同的方式有助于我們快速開發(fā)和測試我們的應(yīng)用。

在命令行運(yùn)行下面的命令，會(huì)重新構(gòu)建App并可以在特定平臺(tái)的模擬器上查看：

cordova emulate android

你可以將你的手機(jī)插入電腦，在手機(jī)上直接測試App：

cordova run android

在進(jìn)行打包操作前，我們可以通過創(chuàng)建一個(gè)本地服務(wù)預(yù)覽app UI，使用指定的端口或缺省值為8000運(yùn)行本地Web服務(wù)器www/assets。訪問項(xiàng)目：http://HOST_IP:PORT/PLATFORM/www。

cordova serve [port]

參考文檔：

設(shè)置Android模擬器

Cordova run 命令參考文檔

Cordova emulate 命令參考文檔

cordova的強(qiáng)大之處在于我們可以通過安裝插件，拓展我們web工程的能力，比如調(diào)用系統(tǒng)底層API來調(diào)用設(shè)備上的底層功能，如攝像頭、相冊(cè)。通過cordova plugin命令實(shí)現(xiàn)插件管理。

可以在這里搜索需要的插件：Cordova Plugins 。

cordova {plugin | plugins} [
    add  [..] {--searchpath= | --noregistry | --link | --save | --browserify | --force} |
    {remove | rm} { | } --save |
    {list | ls} |
    search [] |
    save |
]

添加插件：

cordova plugin add  [...]

移除插件：

cordova plugin remove [...]

上面我們是在跨平臺(tái)(CLI)的工作流進(jìn)行，原則上如果我們不需要自己寫原生層自定義組件，我們完全可以只在CLI上完成我們的工作，當(dāng)然如果需要進(jìn)一步深入了解cordova native與js的通信聯(lián)系，我們需要切換到平臺(tái)為中心的工作流，即將我們的cordova工程導(dǎo)入到原生工程。例如：我們可以使用android studio導(dǎo)入我們新建的cordova工程。

官方推薦的插件遵循相同的目錄結(jié)構(gòu)，根目錄下是plugin.xml配置文件，src目錄下放平臺(tái)原生代碼，www下放js接口代碼，基本配置方法和代碼結(jié)構(gòu)由一定規(guī)律，我們使用plugman可以生成一個(gè)插件模板，改改就可以寫一個(gè)自定義插件。

npm install -g plugman

比如這里我們創(chuàng)建一個(gè)nativeUI的插件：

plugman create --name NativeUI --plugin_id cordova-plugin-nativeui --plugin_version 0.0.1

參數(shù)介紹：
pluginName: 插件名字：NativeUI
pluginID: 插件id : cordova-plugin-nativeui
oversion: 版本 : 0.0.1
directory:一個(gè)絕對(duì)或相對(duì)路徑的目錄，該目錄將創(chuàng)建插件項(xiàng)目
variable NAME=VALUE: 額外的描述，如作者信息和相關(guān)描述

進(jìn)入插件目錄

cd NativeUI

給 plugin.xml 增加Android平臺(tái)

plugman platform add --platform_name android

生成的插件文件結(jié)構(gòu)為：

NativeUI：

├── src
    └── android
        └── NativeUI.java
├── www
    └── NativeUI.js
└── plugin.xml

plugin.xml文件字段含義：

    NativeUI
    
        
    
    
        
            
                
            
        
        
        
    

這個(gè)配置文件有幾個(gè)地方很關(guān)鍵，一開始沒有認(rèn)真看，將插件導(dǎo)進(jìn)工程跑的時(shí)候各種問題，十分頭痛，不得不重新認(rèn)真看看plugin.xml文檔。

id：原則上沒有嚴(yán)格規(guī)定，參考官方插件寫法，這里我也寫的是cordova-plugin-nativeui，通過plugman創(chuàng)建插件模板的時(shí)候需要指定。

name：插件名稱。

clobbers->target：用于指定插入module.exports的窗口對(duì)象下的命名空間，也就是用戶調(diào)用該插件時(shí)的js層暴露的頂層對(duì)象。這個(gè)很關(guān)鍵，雖然可以任意指定，但是涉及到我們調(diào)用插件的屬性或者方法，所以需要特別關(guān)注。plugman默認(rèn)生成的是將id中的-轉(zhuǎn)換成`."的對(duì)象。這里需要說明的是我們可以寫多個(gè)js-module，每個(gè)js-module下可以指定不同的clobbers。

feature -> param - > value 標(biāo)識(shí)了實(shí)際提供服務(wù)的Native類別名稱，這里直接定位至具體類，然而上述通過plugman生成模板的時(shí)候中沒有指定NativeUI的包名，會(huì)自定生成cordova-plugin-nativeui.NativeUI，這里我們需要改成符合自己要求的類名，如我這里使用公司的域名：cn.com.agree.nativeui.NativeUI。需要說明的是這里的類名可以與插件名稱不同。

source-file -> target-dir 同理target-dir需要修改為： src/cn/com/agree/nativeui，同時(shí)需要修改平臺(tái)下的native部分的代碼：如：package cn.com.agree.nativeui;

platform -> config-file下可以指定程序所需的權(quán)限uses-permission，如：

這里我們以android平臺(tái)為例：

cordova.js在創(chuàng)建Android工程的時(shí)候，是從cordova的lib目錄下Copy到platformsandroidassetswwwcordova.js的。同時(shí)備份到platformsandroidplatform_wwwcordova.js。下一篇文章我會(huì)試著讀一下cordova.js的源碼，這里對(duì)cordova.js暫不做深入探究。

這里我們主要關(guān)心幾個(gè)地方，我們的原生代碼在src目錄下，assets/www目錄下是我們的web 程序。www目錄下的plugins文件夾就是我們的插件js部分，cordova_plugins.js是根據(jù)plugins文件夾的內(nèi)容生成的。

cordova_plugins.js的整體結(jié)構(gòu)：

cordova.define("cordova/plugin_list", function(require, exports, module) {
module.exports = [
    {
        "id": "cordova-plugin-nativeui.NativeUI",
        "file": "plugins/cordova-plugin-nativeui/www/NativeUI.js",
        "pluginId": "cordova-plugin-nativeui",
        "clobbers": [
            "agree.nativeUI"
        ]
    },
    ...
];
module.exports.metadata = 
// TOP OF METADATA
{
    "cordova-plugin-nativeui": "0.0.1",
    ...
};
// BOTTOM OF METADATA
});

Android插件基于Cordova-Android，它是基于具有Javscript-to-native橋接的Android WebView構(gòu)建的。 Android插件的本機(jī)部分至少包含一個(gè)擴(kuò)展CordovaPlugin類的Java類，并重寫其一個(gè)執(zhí)行方法。

插件的JavaScript接口使用cordova.exec方法，如下所示：

cordova.exec(, , , , []);

function(winParam) {}: 成功回調(diào)

function(error) {}: 錯(cuò)誤回調(diào)

service: 原生層服務(wù)名稱

action: js層調(diào)用方法名

[args]: js層傳遞到原生層的數(shù)據(jù)

這將WebView的請(qǐng)求傳遞給Android本機(jī)端，有效地在服務(wù)類上調(diào)用action方法，并在args數(shù)組中傳遞其他參數(shù)。無論您將插件分發(fā)為Java文件還是作為自己的jar文件，必須在Cordova-Android應(yīng)用程序的res / xml / config.xml文件中指定該插件。 有關(guān)如何使用plugin.xml文件注入此要素的詳細(xì)信息，請(qǐng)參閱應(yīng)用程序插件：

一個(gè)插件對(duì)象的一個(gè)實(shí)例是為每個(gè)WebView的生命創(chuàng)建的。 插件不會(huì)被實(shí)例化，直到它們被JavaScript的調(diào)用首次引用為止，除非在config.xml中將具有onload name屬性的設(shè)置為“true”。

插件使用 initialize 初始化啟動(dòng)：

@Override
public void initialize(CordovaInterface cordova, CordovaWebView webView) {
    super.initialize(cordova, webView);
    // your init code here
}

插件還可以訪問Android生命周期事件，并可以通過擴(kuò)展所提供的方法（onResume，onDestroy等）來處理它們。 具有長時(shí)間運(yùn)行請(qǐng)求的插件，媒體播放，偵聽器或內(nèi)部狀態(tài)等背景活動(dòng)應(yīng)實(shí)現(xiàn)onReset（）方法。 當(dāng)WebView導(dǎo)航到新頁面或刷新時(shí)，它會(huì)執(zhí)行，這會(huì)重新加載JavaScript。

一個(gè)JavaScript調(diào)用觸發(fā)對(duì)本機(jī)端的插件請(qǐng)求，并且相應(yīng)的Java插件在config.xml文件中正確映射，但最終的Android Java Plugin類是什么樣的？ 使用JavaScript的exec函數(shù)發(fā)送到插件的任何東西都被傳遞到插件類的execute方法中。

插件的JavaScript不會(huì)在WebView界面的主線程中運(yùn)行; 而是在WebCore線程上運(yùn)行，執(zhí)行方法也是如此。 如果需要與用戶界面進(jìn)行交互，應(yīng)該使用Activity的runOnUiThread方法。

如果不需要在UI線程上運(yùn)行，但不希望阻止WebCore線程，則應(yīng)使用cordova.getThreadPool()獲得的Cordova ExecutorService執(zhí)行代碼。

...
@Override
public boolean execute(String action, JSONArray args, CallbackContext callbackContext) throws JSONException {
    if (action.equals("toast")) {
        this.toast(args.getString(0));
        return true;
    }
    return false;
}

/**
 * Builds and shows a native Android toast with given Strings
 *
 * @param message The message the toast should display
 */
private void toast(final String message) {
    final CordovaInterface cordova = this.cordova;
    if (message != null && message.length() > 0) {
        final int duration = Toast.LENGTH_SHORT;
        Runnable runnable = new Runnable() {
            public void run() {
                Toast toast = Toast.makeText(cordova.getActivity().getApplicationContext(), message, duration);
                toast.show();
            }
        };
        cordova.getActivity().runOnUiThread(runnable);
    }
}
...

js部分的代碼：

var exec = require("cordova/exec");

module.exports = {
    toast: function(message) {
        exec(null, null, "NativeUI", "toast", [message]);
    }
}

callbackContext.success可以將原生層字符串作為參數(shù)傳遞給JavaScript層的成功回調(diào)，callbackContext.error可以將給JavaScript層的錯(cuò)誤回調(diào)函數(shù)傳遞參數(shù)。

如果你的Android插件有額外的依賴關(guān)系，那么它們必須以兩種方式之一列在plugin.xml中：

首選的方法是使用標(biāo)簽（有關(guān)詳細(xì)信息，請(qǐng)參閱插件規(guī)范）。以這種方式指定庫可以通過Gradle的依賴管理邏輯來解決。這允許諸如gson，android-support-v4和google-play-services之類的常用庫被多個(gè)插件使用而沒有沖突。

第二個(gè)選項(xiàng)是使用標(biāo)簽來指定jar文件的位置（有關(guān)更多詳細(xì)信息，請(qǐng)參閱插件規(guī)范）。 只有當(dāng)您確定沒有其他插件將依賴于您所引用的庫（例如，該庫特定于您的插件）時(shí)，才應(yīng)使用此方法。 否則，如果另一個(gè)插件添加了相同的庫，則可能導(dǎo)致插件用戶造成構(gòu)建錯(cuò)誤。 值得注意的是，Cordova應(yīng)用程序開發(fā)人員不一定是本地開發(fā)人員，因此本地平臺(tái)構(gòu)建錯(cuò)誤可能特別令人沮喪。

Android具有Intent系統(tǒng)，允許進(jìn)程相互通信。插件可以訪問CordovaInterface對(duì)象，可以訪問運(yùn)行應(yīng)用程序的Android Activity。 這是啟動(dòng)新的Android Intent所需的上下文。 CordovaInterface允許插件為結(jié)果啟動(dòng)Activity，并為Intent返回應(yīng)用程序時(shí)設(shè)置回調(diào)插件。

從Cordova 2.0開始，插件無法再直接訪問上下文，并且舊的ctx成員已被棄用。 所有的ctx方法都存在于Context中，所以getContext()和getActivity()都可以返回所需的對(duì)象。

運(yùn)行權(quán)限（Cordova-Android 5.0.0+）

Android 6.0 "Marshmallow" 引入了新的權(quán)限模型，用戶可以根據(jù)需要啟用和禁用權(quán)限。這意味著應(yīng)用程序必須將這些權(quán)限更改處理為將來，這是Cordova-Android 5.0.0發(fā)行版的重點(diǎn)。

就插件而言，可以通過調(diào)用權(quán)限方法來請(qǐng)求權(quán)限，該簽名如下：

cordova.requestPermission(CordovaPlugin plugin, int requestCode, String permission);

為了減少冗長度，將此值分配給本地靜態(tài)變量是標(biāo)準(zhǔn)做法：

public static final String READ = Manifest.permission.READ_CONTACTS;

定義requestCode的標(biāo)準(zhǔn)做法如下：

public static final int SEARCH_REQ_CODE = 0;

然后，在exec方法中，應(yīng)該檢查權(quán)限：

if(cordova.hasPermission(READ)) {
    search(executeArgs);
} else {
    getReadPermission(SEARCH_REQ_CODE);
}

在這種情況下，我們只需調(diào)用requestPermission：

protected void getReadPermission(int requestCode) {
    cordova.requestPermission(this, requestCode, READ);
}

這將調(diào)用該活動(dòng)并引起提示出現(xiàn)要求該權(quán)限。 一旦用戶擁有權(quán)限，結(jié)果必須使用onRequestPermissionResult方法處理，每個(gè)插件應(yīng)該覆蓋該方法。 一個(gè)例子可以在下面找到：

public void onRequestPermissionResult(int requestCode, String[] permissions, int[] grantResults) throws JSONException {
    for(int r:grantResults) {
        if(r == PackageManager.PERMISSION_DENIED) {
            this.callbackContext.sendPluginResult(new PluginResult(PluginResult.Status.ERROR, PERMISSION_DENIED_ERROR));
            return;
        }
    }
    switch(requestCode) {
        case SEARCH_REQ_CODE:
            search(executeArgs);
            break;
        case SAVE_REQ_CODE:
            save(executeArgs);
            break;
        case REMOVE_REQ_CODE:
            remove(executeArgs);
            break;
    }
}

上面的switch語句將從提示符返回，并且根據(jù)傳入的requestCode，它將調(diào)用該方法。 應(yīng)該注意的是，如果執(zhí)行不正確地處理權(quán)限提示可能會(huì)堆疊，并且應(yīng)該避免這種情況。

除了要求獲得單一權(quán)限的權(quán)限之外，還可以通過定義權(quán)限數(shù)組來請(qǐng)求整個(gè)組的權(quán)限，如同Geolocation插件所做的那樣：

String [] permissions = { 
  Manifest.permission.ACCESS_COARSE_LOCATION,
  Manifest.permission.ACCESS_FINE_LOCATION 
};

然后當(dāng)請(qǐng)求權(quán)限時(shí)，需要完成的所有操作如下：

cordova.requestPermissions(this, 0, permissions);

這將請(qǐng)求數(shù)組中指定的權(quán)限。 提供公開訪問的權(quán)限陣列是一個(gè)好主意，因?yàn)榭梢允褂貌寮鳛橐蕾囮P(guān)系使用，盡管這不是必需的。

如果你的插件啟動(dòng)將Cordova活動(dòng)推送到后臺(tái)的活動(dòng)，則需要特別考慮。 如果設(shè)備運(yùn)行內(nèi)存不足，Android操作系統(tǒng)將在后臺(tái)銷毀活動(dòng)。在這種情況下，CordovaPlugin實(shí)例也將被銷毀。 如果您的插件正在等待其啟動(dòng)的活動(dòng)的結(jié)果，則當(dāng)Cordova活動(dòng)返回到前臺(tái)并獲得結(jié)果時(shí)，將創(chuàng)建一個(gè)新的插件實(shí)例。 但是，插件的狀態(tài)不會(huì)自動(dòng)保存或恢復(fù)，插件的CallbackContext將丟失。 CordovaPlugin可以實(shí)現(xiàn)兩種方法來處理這種情況：

/**
 * Called when the Activity is being destroyed (e.g. if a plugin calls out to an
 * external Activity and the OS kills the CordovaActivity in the background).
 * The plugin should save its state in this method only if it is awaiting the
 * result of an external Activity and needs to preserve some information so as
 * to handle that result; onRestoreStateForActivityResult() will only be called
 * if the plugin is the recipient of an Activity result
 *
 * @return  Bundle containing the state of the plugin or null if state does not
 *          need to be saved
 */
public Bundle onSaveInstanceState() {}

/**
 * Called when a plugin is the recipient of an Activity result after the
 * CordovaActivity has been destroyed. The Bundle will be the same as the one
 * the plugin returned in onSaveInstanceState()
 *
 * @param state             Bundle containing the state of the plugin
 * @param callbackContext   Replacement Context to return the plugin result to
 */
public void onRestoreStateForActivityResult(Bundle state, CallbackContext callbackContext) {}

cordova 是否能夠發(fā)揮出它出彩的一面還是源于我們對(duì)原生的熟練程度，只有對(duì)原生足夠熟練，對(duì)cordova的運(yùn)行機(jī)制足夠熟悉才能做出一個(gè)相對(duì)比較令人滿意的App，后面的文章我會(huì)嘗試閱讀cordova的源碼，深入解析cordova的實(shí)現(xiàn)原理和插件機(jī)制，也會(huì)教大家封裝一些常用的自定義組件。本文內(nèi)容基本取材于官方文檔，只是借助谷歌翻譯以及自己在探索過程中的一些問題，做了一些增刪，如果有任何問題，希望各位不吝指教。

寫文章不容易，也許寫這些代碼就幾分鐘的事，寫一篇大家好接受的文章或許需要幾天的醞釀，然后加上幾天的碼字，累并快樂著。如果文章對(duì)您有幫助請(qǐng)我喝杯咖啡吧！

轉(zhuǎn)載需標(biāo)注本文原始地址：https://zhaomenghuan.github.io/