cordova 的使用方法

Cordova应用本质上是web应用，每个移动平台使用不同的IDE和项目结构。Cordova以前的版本，开发者创建为每个移动平台创建一个项目，再把web应用内容在项目间来回复制。在3.0以后还把Cordova API都迁移到了插件中。管理Cordova项目、Web内容和安装的插件都很困难。从3.0开始(在2.7发布过预览版)，项目添加了CLI，它提供一套命令给开发者使用：

• 创建跨平台应用项目
• 为每个Cordova移动设备平台添加支持
• 列出支持的移动设备平台
• 删除移动平台支持
• 向项目添加插件：可以是核心Cordova插件、第三方插件或自定义插件
• 列出项目中所有安装的插件
• 从项目中移除插件
• 准备、编译和构建项目
• 通过Web服务器提供项目Web内容
• 在合适的移动设备仿真器中启动应用

恰当使用这些命令，开发者可以管理Cordova应用开发的整个生命周期。

---

检查CLI运行中的故障

Cordova正常情况下执行命令后不会显示任何信息。如果想查看命令在执行过程中哪里出了问题，可以使用-d或--verbose参数开启冗长模式。开启后可以看见命令执行过程的每一步的状态。其中一些信息由CLI本身提供，另外一些由CLI调用的第三方工具产生。

---

CLI命令概要

先大体了解一下CLI命令：

Help：显示可用CLI命令的信息。
Create：创建Cordova项目并关联项目文件夹和文件。
Plateform：管理Cordova项目使用的移动平台。
Plugin：管理Cordova插件的安装和卸载。
Prepare：从Cordova项目的www文件夹复制web应用内容到项目移动平台项目文件夹中。
Compile：把web应用打包成Cordova应用。
Build：先执行Prepare命令然后打包web应用。
Emulate：在一个或多个移动设备平台的设备模拟器中运行Cordova应用。
Run：在一个或多个移动设备中运行Cordova应用。
Serve：启动一个服务器加载web内容以便于用浏览器访问。

---

使用CLI

要详细了解CLI使用的命令，包括命令机制和每个命令的执行过程。要了解CLI可以使用哪些命令，打开Windows命令窗口或类似的程序，输入

<span style="font-size:18px;color:#006600;"><code style="font-family: "Source Code Pro",Consolas,Menlo,Monaco,"Courier New",monospace; font-size: 1em; padding: 0px; white-space: inherit; background: transparent none repeat scroll 0% 0%;">cordova <span class="hljs-operator" style=""><span class="hljs-keyword" style="">help</span></span></code></span>

检查CLI版本：

<span style="font-size:18px;color:#006600;"><code style="font-family: "Source Code Pro",Consolas,Menlo,Monaco,"Courier New",monospace; font-size: 1em; padding: 0px; white-space: inherit; background: transparent none repeat scroll 0% 0%;"><span class="hljs-title" style="">cordova</span> -v</code></span>

或者

<span style="font-size:18px;color:#006600;"><code style="font-family: "Source Code Pro",Consolas,Menlo,Monaco,"Courier New",monospace; font-size: 1em; padding: 0px; white-space: inherit; background: transparent none repeat scroll 0% 0%;"><span class="hljs-title" style="">cordova</span> -version</code></span>

创建Cordova项目

开发前要创建一个项目。create命令用来创建新项目。打开命令行窗口进入要创建项目的文件夹，输入以下命令：

<span style="font-size:18px;color:#006600;"><code style="font-family: "Source Code Pro",Consolas,Menlo,Monaco,"Courier New",monospace; font-size: 1em; padding: 0px; white-space: inherit; background: transparent none repeat scroll 0% 0%;">cordova <span class="hljs-operator" style=""><span class="hljs-keyword" style="">create</span> project_name</span></code></span>

这样就创建了一个简单的Cordova项目结构和一些Web内容文件。也可以用以下命令明确指定应用ID和应用的名字：

<span style="font-size:18px;color:#006600;"><code style="font-family: "Source Code Pro",Consolas,Menlo,Monaco,"Courier New",monospace; font-size: 1em; padding: 0px; white-space: inherit; background: transparent none repeat scroll 0% 0%;">cordova <span class="hljs-operator" style=""><span class="hljs-keyword" style="">create</span> project_name app_id app_name</span></code></span>

这个命令还把应用ID写进应用的配置文件，并且有了一个和项目名字不同的应用名字，如项目文件夹叫myapp而应用名字叫Hello，可以这么写：

<span style="font-size:18px;color:#006600;"><code style="font-family: "Source Code Pro",Consolas,Menlo,Monaco,"Courier New",monospace; font-size: 1em; padding: 0px; white-space: inherit; background: transparent none repeat scroll 0% 0%;">cordova <span class="hljs-operator" style=""><span class="hljs-keyword" style="">create</span> myapp com.cordovaprogamming.hello hello</span></code></span>

注意命令执行完并不显示发生了什么，执行完就返回到命令行。创建项目时，CLI创建了一个默认的HelloWorld页面。

所有的Cordova CLI命令都要在创建好的项目文件夹中执行，即用CLI执行的项目操作都要在create创建的项目文件夹中指行。

创建的项目结构如下图。这种项目结构便于跨平台处理。注意www文件夹单独被拿出来，这样就可以在多个移动平台上共享同一个web应用。

在以前的版本中项目文件夹中有merges文件夹，用来单独存放不同平台上不同的资源文件(如html、css、js、图像和视频文件等)。最近的版本去掉了它，增加了hooks文件夹(可替代merges文件夹的作用)。hooks文件夹用于存放一些脚本代码(如Node.js、shell)，用来自定义CLI命令，从而扩展Cordova CLI框架。关于Cordova hooks的详细使用请参考hooks文件夹中的readme.md。platform文件夹中放置每个移动平台的文件夹。plugins文件夹存放应用使用的插件的源码。

Cordova CLI的不会事先准备好所有要使用的文件，它使用了一种叫延时加载的处理方法，在创建项目和向项目添加平台支持时下载所需要的文件。CLI用一个叫.cordova的文件夹存放延时加载下载的文件，在windows系统中一般位于用户主目录下(c:\users\user_name)。在创建项目时的下载过程中如果出现问题，可以先用-d参数下载了哪些文件，如果CLI报告已下载过并跳过下载，查看.cordova中是否真的有这个文件。如果没有请whack这个空文件夹并重试。

平台管理

新创建的项目文件夹中只有一些空文件夹，还不支持任何移动设备平台。platform命令就是用于管理应用中的项目文件的。

添加平台

打开命令行窗口进入Cordova项目文件夹，输入以下命令添加某个移动设备平台,当然要提前安装好平台开发工具(如Android SDK)：

<span style="font-size:18px;color:#006600;"><code style="font-family: "Source Code Pro",Consolas,Menlo,Monaco,"Courier New",monospace; font-size: 1em; padding: 0px; white-space: inherit; background: transparent none repeat scroll 0% 0%;"><span class="hljs-title" style="">cordova</span> platform add platform_name</code></span>

如果要向应用中添加Android项目，可以这么写：

<span style="font-size:18px;color:#006600;"><code style="font-family: "Source Code Pro",Consolas,Menlo,Monaco,"Courier New",monospace; font-size: 1em; padding: 0px; white-space: inherit; background: transparent none repeat scroll 0% 0%;"><span class="hljs-title" style="">cordova</span> platform add android</code></span>

如果在一行命令中添加多个平台项目，可以这么写：

<span style="font-size:18px;color:#006600;"><code style="font-family: "Source Code Pro",Consolas,Menlo,Monaco,"Courier New",monospace; font-size: 1em; padding: 0px; white-space: inherit; background: transparent none repeat scroll 0% 0%;"><span class="hljs-title" style="">cordova</span> platform add android blackberry ios</code></span>

执行命令后，会在项目根目录的platform文件夹中生成平台项目文件夹，可以用相关IDE导入使用(如Android使用安装ADT的Eclipse)。

列出平台列表

CLI可以查看Cordova项目中已经存在的平台的列表。在平台根目录中输入以下命令之一查看：

<span style="font-size:18px;color:#006600;"><code style="font-family: "Source Code Pro",Consolas,Menlo,Monaco,"Courier New",monospace; font-size: 1em; padding: 0px; white-space: inherit; background: transparent none repeat scroll 0% 0%;"><span class="hljs-title" style="">cordova</span> platformscordova platform lscordova platform list</code></span>

CLI用JSON格式返回每个平台的名字，形如：

<span style="font-size:18px;color:#006600;"><code style="font-family: "Source Code Pro",Consolas,Menlo,Monaco,"Courier New",monospace; font-size: 1em; padding: 0px; white-space: inherit; background: transparent none repeat scroll 0% 0%;">['android', 'ios', 'blackberry10']                     </code></span>

这个命令的主要用于一些自动化处理中。它返回的JSON结果可用于Node.js应用，解析后确定是否缺少某平台。

删除平台

使用如下命令删除：

<span style="font-size:18px;color:#006600;"><code style="font-family: "Source Code Pro",Consolas,Menlo,Monaco,"Courier New",monospace; font-size: 1em; padding: 0px; white-space: inherit; background: transparent none repeat scroll 0% 0%;"><span class="hljs-title" style="">cordova</span> platform remove platform_name</code></span>

或使用remove的简写rm：

<span style="font-size:18px;color:#006600;"><code style="font-family: "Source Code Pro",Consolas,Menlo,Monaco,"Courier New",monospace; font-size: 1em; padding: 0px; white-space: inherit; background: transparent none repeat scroll 0% 0%;"><span class="hljs-title" style="">cordova</span> platform rm platform</code></span>

插件管理

插件管理是CLI重要功能之一。CLI负责复制plugin文件和修改配置文件，不用手工操作。

添加插件

在命令行窗口中进入项目文件夹，输入以下命令：

<span style="font-size:18px;color:#006600;"><code style="font-family: "Source Code Pro",Consolas,Menlo,Monaco,"Courier New",monospace; font-size: 1em; padding: 0px; white-space: inherit; background: transparent none repeat scroll 0% 0%;"><span class="hljs-title" style="">cordova</span> plugin add path_to_plugin_files</code></span>

例如添加相机插件可以使用如下命令：

<span style="font-size:18px;color:#006600;"><code style="font-family: "Source Code Pro",Consolas,Menlo,Monaco,"Courier New",monospace; font-size: 1em; padding: 0px; white-space: inherit; background: transparent none repeat scroll 0% 0%;"><span class="hljs-title" style="">cordova</span> plugin add <span class="hljs-url" style="">https://git-wip-us.apache.org/repos/asf/cordova-plugin-camera.git</span></code></span>

这样就连接到了Apache Git并下载最新版本的插件。Cordova核心API插件列表位于http://cordova.apache.org/docs/en/3.0.0/guide_cli_index.md.html#The%20...。

Apache在插件位置是如下形式，尖括号中的plugin-name指插件名，一般知道了地址，CLI都可以下载下来：

<span style="font-size:18px;color:#006600;"><code style="font-family: "Source Code Pro",Consolas,Menlo,Monaco,"Courier New",monospace; font-size: 1em; padding: 0px; white-space: inherit; background: transparent none repeat scroll 0% 0%;"><span class="hljs-symbol" style="">https:</span>/<span class="hljs-regexp" style="">/git-wip-us.apache.org/repos</span><span class="hljs-regexp" style="">/asf/cordova</span>-plugin-<plugin-name>.git</code></span>

如果是第三方插件或存在本地的自定义的插件，可以使用如下命令安装，your_location指本地存储路径：

<span style="font-size:18px;color:#006600;"><code style="font-family: "Source Code Pro",Consolas,Menlo,Monaco,"Courier New",monospace; font-size: 1em; padding: 0px; white-space: inherit; background: transparent none repeat scroll 0% 0%;"><span class="hljs-title" style="">cordova</span> plugin add your_location </code></span>

使用CLI是向项目安装插件的唯一方法。之前版本要开发者手工复制并修改配置文件。如果在3.0及以后的版本使用这种方法可能会破坏Cordova项目。

3.1版本以后可以直接用插件名安装，CLI会在插件仓库中检查与名字匹配的插件并下载安装到项目中。例如要添加console插件，在项目文件夹下使用如下命令：

<span style="font-size:18px;color:#006600;"><code style="font-family: "Source Code Pro",Consolas,Menlo,Monaco,"Courier New",monospace; font-size: 1em; padding: 0px; white-space: inherit; background: transparent none repeat scroll 0% 0%;">cordova plugin add org.apache.cordova.<span class="hljs-built_in" style="">console</span></code></span>

添加的插件位于项目根目录的plugins文件夹中，插件名的命名空间使用Reverse-DNS命名惯例再加上插件名，例如Cordova核心插件使用*org.apache.cordova.core加上插件名的命名方式。这种命名方式减少了不同组织间相似插件的命名冲突的可能性。

插件对每个支持的平台有各自存放的文件夹。另外Cordova应用使用的JavaScript文件放在www文件夹中。关于插件更多的情况我们放在后面更详细的去了解。

列出插件列表

使用如下命令查看在Cordova项目中插件列表，打开命令行窗口进入项目文件夹：

<span style="font-size:18px;color:#006600;"><code style="font-family: "Source Code Pro",Consolas,Menlo,Monaco,"Courier New",monospace; font-size: 1em; padding: 0px; white-space: inherit; background: transparent none repeat scroll 0% 0%;"><span class="hljs-title" style="">cordova</span> plugins</code></span>

CLI将以JSON数据形式返回结果，如：

<span style="font-size:18px;color:#006600;"><code style="font-family: "Source Code Pro",Consolas,Menlo,Monaco,"Courier New",monospace; font-size: 1em; padding: 0px; white-space: inherit; background: transparent none repeat scroll 0% 0%;">['org.apache.cordova.core.camera', 'org.apache.cordova.core.device-motion', 'org.apache.cordova.core.file']</code></span>

删除插件

使用如下命令删除插件，打开命令行窗口进入项目文件夹：

<span style="font-size:18px;color:#006600;"><code style="font-family: "Source Code Pro",Consolas,Menlo,Monaco,"Courier New",monospace; font-size: 1em; padding: 0px; white-space: inherit; background: transparent none repeat scroll 0% 0%;"><span class="hljs-title" style="">cordova</span> plugin remove plugin_name</code></span>

或者使用remove的简写形式rm：

<span style="font-size:18px;color:#006600;"><code style="font-family: "Source Code Pro",Consolas,Menlo,Monaco,"Courier New",monospace; font-size: 1em; padding: 0px; white-space: inherit; background: transparent none repeat scroll 0% 0%;"><span class="hljs-title" style="">cordova</span> plugin rm plugin_name</code></span>

删除过程是安装过程的反向操作，它把配置文件中指向插件的配置文件说明删除并把插件文件夹从项目文件夹中删除。

构建管理

CLI内置整合了移动平台SDK，可以使用CLI管理应用构建过程。

准备

CLI的prepare命令把Cordova项目的web应用内容从www文件夹复制到适当的平台文件夹中。每次改动web内容后都要使用这个命令。prepare命令由接下来要介绍的许多命令自动调用。

打开命令行工具进入项目文件夹输入以下命令：

<span style="font-size:18px;color:#006600;"><code style="font-family: "Source Code Pro",Consolas,Menlo,Monaco,"Courier New",monospace; font-size: 1em; padding: 0px; white-space: inherit; background: transparent none repeat scroll 0% 0%;">cordova <span class="hljs-operator" style=""><span class="hljs-keyword" style="">prepare</span></span></code></span>

可以为指定平台执行准备工作，命令如下：

<span style="font-size:18px;color:#006600;"><code style="font-family: "Source Code Pro",Consolas,Menlo,Monaco,"Courier New",monospace; font-size: 1em; padding: 0px; white-space: inherit; background: transparent none repeat scroll 0% 0%;">cordova <span class="hljs-operator" style=""><span class="hljs-keyword" style="">prepare</span> platform_name</span></code></span>

编译

compile命令通过调用项目平台文件夹中的构建脚本初始化编译过程。

打开终端窗口进入平台文件夹输入以下命令使用compile命令：

<span style="font-size:18px;color:#006600;"><code style="font-family: "Source Code Pro",Consolas,Menlo,Monaco,"Courier New",monospace; font-size: 1em; padding: 0px; white-space: inherit; background: transparent none repeat scroll 0% 0%;"><span class="hljs-title" style="">cordova</span> compile</code></span>

编译某个平台：

<span style="font-size:18px;color:#006600;"><code style="font-family: "Source Code Pro",Consolas,Menlo,Monaco,"Courier New",monospace; font-size: 1em; padding: 0px; white-space: inherit; background: transparent none repeat scroll 0% 0%;"><span class="hljs-title" style="">cordova</span> compile platform_name</code></span>

构建

build命令和compile命令相似，只之在执行编译前先调用prepare命令。

打开终端窗口进入平台文件夹输入以下命令：

<span style="font-size:18px;color:#006600;"><code style="font-family: "Source Code Pro",Consolas,Menlo,Monaco,"Courier New",monospace; font-size: 1em; padding: 0px; white-space: inherit; background: transparent none repeat scroll 0% 0%;"><span class="hljs-title" style="">cordova</span> build</code></span>

编译某平台：

<span style="font-size:18px;color:#006600;"><code style="font-family: "Source Code Pro",Consolas,Menlo,Monaco,"Courier New",monospace; font-size: 1em; padding: 0px; white-space: inherit; background: transparent none repeat scroll 0% 0%;"><span class="hljs-title" style="">cordova</span> build platform_name</code></span>

运行Cordova应用

CLI内在关联了移动平台模拟器，可以在模拟器或物理设备上直接运行Cordova应用。之后会详细介绍模拟器的配置和加载，从CLI使用物理设备都需要什么。先对相关命令大概看一下：

仿真

emulate命令自动执行了构建处理过程并把应用部署到设备模拟器上。它首先要准备应用，执行构建处理过程，把生成的应用程序包部署到模拟器。

在项目中配置的每个平台的默认模拟器上运行Cordova应用，使用如下命令：

<span style="font-size:18px;color:#006600;"><code style="font-family: "Source Code Pro",Consolas,Menlo,Monaco,"Courier New",monospace; font-size: 1em; padding: 0px; white-space: inherit; background: transparent none repeat scroll 0% 0%;"><span class="hljs-title" style="">cordova</span> emulate</code></span>

在单独的设备模拟器上模拟运行，如android，使用如下命令：

<span style="font-size:18px;color:#006600;"><code style="font-family: "Source Code Pro",Consolas,Menlo,Monaco,"Courier New",monospace; font-size: 1em; padding: 0px; white-space: inherit; background: transparent none repeat scroll 0% 0%;"><span class="hljs-title" style="">cordova</span> emulate android</code></span>

运行

run命令自动执行应用的构建过程并部署到物理设备。命令首先做准备工作，执行构建处理过程然后把应用包部署到连接的设备。

要在项目中配置的每个平台上运行Cordova应用，使用如下命令：

<span style="font-size:18px;color:#006600;"><code style="font-family: "Source Code Pro",Consolas,Menlo,Monaco,"Courier New",monospace; font-size: 1em; padding: 0px; white-space: inherit; background: transparent none repeat scroll 0% 0%;"><span class="hljs-title" style="">cordova</span> run</code></span>

在某个设备上，如android设备，使用如下命令：

<span style="font-size:18px;color:#006600;"><code style="font-family: "Source Code Pro",Consolas,Menlo,Monaco,"Courier New",monospace; font-size: 1em; padding: 0px; white-space: inherit; background: transparent none repeat scroll 0% 0%;"><span class="hljs-title" style="">cordova</span> run android</code></span>

使用服务器

web应用在移动设备上使用前，先在桌面浏览器测试。这一点对Cordova应用尤其重要，因为在移动设备上使用前还有一个打包过程。

使用server命令可以加载一个本地服务器，寄宿了某个平台的web内容。它不向浏览器开放Cordova API，所有的测试都针对Web UI进行。在测试前使用prepare命令确保web内容保持最新状态。

在命令行窗口进入项目文件夹输入以下命令：

<span style="font-size:18px;color:#006600;"><code style="font-family: "Source Code Pro",Consolas,Menlo,Monaco,"Courier New",monospace; font-size: 1em; padding: 0px; white-space: inherit; background: transparent none repeat scroll 0% 0%;"><span class="hljs-title" style="">cordova</span> serve plat_form</code></span>

如在服务器中运行Cordova项目的Android平台web应用内容：

<span style="font-size:18px;color:#006600;"><code style="font-family: "Source Code Pro",Consolas,Menlo,Monaco,"Courier New",monospace; font-size: 1em; padding: 0px; white-space: inherit; background: transparent none repeat scroll 0% 0%;"><span class="hljs-title" style="">cordova</span> serve android</code></span>

命令加载后，会显示一个URL用于在浏览器上访问。端口默认使用8000，要使用不同的端口使用如下命令：

<span style="font-size:18px;color:#006600;"><code style="font-family: "Source Code Pro",Consolas,Menlo,Monaco,"Courier New",monospace; font-size: 1em; padding: 0px; white-space: inherit; background: transparent none repeat scroll 0% 0%;"><span class="hljs-title" style="">cordova</span> server android <span class="hljs-number" style="">8080</span></code></span>