译：cordova

http://cordova.apache.org/docs/en/3.5.0/guide_cli_index.md.html#The%20Command-Line%20Interface

　　cordova命令界面（CLI）向你展示了怎样创建一个app，并且在各种各种的本地移动平台部署他们。这个工具允许你创建一个新的项目，编译到不同的平台上面，然后在真实的设备上或者模拟器里运行。CLI是在概述里面描述的跨平台工作流的主要工具。然而，你也可以使用CLI来初始化项目代码，然后切换到各种平台的SDK和shell工具来继续开发。

Prerequisites

在运行任何命令行工具之前，你需要安装目标平台的SDK(See the Platform Guidesfor more details.)

为了给任何一个平台添加一个支持或者重建的项目，你需要在支持这个平台的SDK的机器上运行命令行。 命令工具支持下列系统：

• iOS (Mac)
• Amazon Fire OS (Mac, Linux, Windows)
• Android (Mac, Linux, Windows)
• BlackBerry 10 (Mac, Linux, Windows)
• Windows Phone 8 (Windows)
• Windows 8 (Windows)
• Firefox OS (Mac, Linux, Windows)

On the Mac, the command-line is available via the Terminal application. On the PC, it's available as Command Prompt underAccessories.

NOTE: For Windows-only platforms, you can still do your development on Mac hardware by running Windows in a virtual machine environment or in dual-boot mode. For available options, see the Windows Phone Platform Guide or the Windows 8 Platform Guide.

The more likely it is that you run the CLI from different machines, the more it makes sense to maintain a remote source code repository, whose assets you pull down to local working directories.

安装Cordova CLI

The Cordova command-line tool is distributed as an npm package in a ready-to-use format. It is not necessary to compile it from source.

要安装cordova命令行工具，请按照下面步骤操作：

1. 下载并安装 Node.js.。按照步骤安装之后，你可以在你的命令行调用 node 和 npm 。如果安装成功，你可以选择使用像 nvm 或 nave 这样的工具来管理你的 Node.js 安装配置。

2. 下载并安装一个 git 客户端，如果你没有的话。按照步骤安装之后，你可以在你的命令行调用  git 命令。即使你不会手动使用 git 命令，在创建一个新项目的时候CLI会在后台使用它来下载一些资源。

3. 使用 npm 安装 cordova 模块。cordova 模块将会自动被下载.

• 在 OS X 和Linux上:

     $ sudo npm install -g cordova

  On OS X and Linux, prefixing the npm command with sudo may be necessary to install this development utility in otherwise restricted directories such as /usr/local/share. If you are using the optional nvm/nave tool or have write access to the install directory, you may be able to omit the sudo prefix. There are more tips available on using npm without sudo, if you desire to do that.

• 在 Windows系统上:

     C:>npm install -g cordova

　　上面命令中的 -g 标志告诉 npm 全局安装 cordova 。如果没有这个标志， cordova 将会安装在当前工作目录下的 node_modules 子目录。

　　为了全局调用 npm 安装模块，你可能需要把 npm 的目录添加到你的环境变量 PATH 中。在Windows系统中， npm 一般在 C:UsersusernameAppDataRoaming pm。在 OS X 和Linux 系统中，一般在/usr/local/share/npm目录下。

      The installation log may produce errors for any uninstalled platform SDKs.

　　Following installation, you should be able to run cordova on the command line with no arguments and it should print help text.

创建一个App

　　切换到你维护的源码所在目录，运行如下命令：

    $ cordova create hello com.example.hello HelloWorld

It may take some time for the command to complete, so be patient. Running the command with the -d option displays information about its progress.

The first argument hello specifies a directory to be generated for your project. This directory should not already exist, Cordova will create it for you. Its www subdirectory houses your application's home page, along with various resources under css, js, and img, which follow common web development file-naming conventions. The config.xml file contains important metadata needed to generate and distribute the application.

The second argument com.example.hello provides your project with a reverse domain-style identifier. This argument is optional, but only if you also omit the third argument, since the arguments are positional. You can edit this value later in the config.xml file, but do be aware that there may be code generated outside of config.xml using this value, such as Java package names. The default value is io.cordova.hellocordova, but it is recommended that you select an appropriate value.

The third argument HelloWorld provides the application's display title. This argument is optional. You can edit this value later in the config.xml file, but do be aware that there may be code generated outside of config.xml using this value, such as Java class names. The default value is HelloCordova, but it is recommended that you select an appropriate value.

Add Platforms添加平台

　　后面所有的命令需要在项目目录下运行，或者他范围内任意子目录，所以我们切换到项目目录下面：

    $ cd hello

　　在你能编译项目之前，你需要指定一系列的目标平台。你是否能运行这些命令，完全取决于你的机器是否支持这些每一个SDK，或者你是否已经安装这些每一个SKD。在Mac下面运行如下命令：

 　 $ cordova platform add ios
    $ cordova platform add amazon-fireos
    $ cordova platform add android
    $ cordova platform add blackberry10
    $ cordova platform add firefoxos

　　在windows系统下面运行下面命令，wp 指的是Windows Phone 操作系统的不同版本：

    $ cordova platform add wp8
    $ cordova platform add windows8
    $ cordova platform add amazon-fireos
    $ cordova platform add android
    $ cordova platform add blackberry10
    $ cordova platform add firefoxos

Run this to check your current set of platforms:

  $ cordova platforms ls

(Note the platform and platforms commands are synonymous.)

Run either of the following synonymous commands to remove a platform:

    $ cordova platform remove blackberry10
    $ cordova platform rm amazon-fireos
    $ cordova platform rm android

Running commands to add or remove platforms affects the contents of the project's platforms directory, where each specified platform appears as a subdirectory. The www source directory is reproduced within each platform's subdirectory, appearing for example in platforms/ios/www or platforms/android/assets/www. Because the CLI constantly copies over files from the source www folder, you should only edit these files and not the ones located under the platforms subdirectories. If you use version control software, you should add this source www folder, along with the merges folder, to your version control system. (More information about the merges folder can be found in the Customize Each Platform section below.)

WARNING: When using the CLI to build your application, you should not edit any files in the /platforms/ directory unless you know what you are doing, or if documentation specifies otherwise. The files in this directory are routinely overwritten when preparing applications for building, or when plugins are reinstalled.

If you wish at this point, you can use an SDK such as Eclipse or Xcode to open the project you created. You will need to open the derivative set of assets from the /platforms/ directory to develop with an SDK. This is because the SDK specific metadata files are stored within the appropriate /platform/ subdirectory. (See the Platform Guides for information on how to develop applications within each IDE.) Use this approach if you simply want to initialize a project using the CLI and then switch to an SDK for native work.

　　如果你想整个开发周期都使用跨平台工作流方法那就继续读下去。

Build the App（构建App）

　　默认的，cordova create 命令脚本生成一个基于web应用的骨架，这个应用的主页是位于www目录下的index.html( www/index.html )文件。随心所欲的编辑这个应用程序，但是任何初始化都应该被指定为 装置就绪 时间句柄的一部分，被默认的 www/js/index.js引用。

　　运行下面的命令，迭代构建项目：

  $ cordova build

　　上面代码在项目的 platforms 子目录下面生成指定平台的代码。你可以通过下面的命令有选择的限制每次构建的范围来指定平台：

  $ cordova build ios

　　上面 cordova build 命令是下面的速记，在这个例子中也是有目标的构建单个平台：   

 $ cordova prepare ios
 $ cordova compile ios

　　在这个案例中，一旦你运行 prepare 命令，你可以使用苹果的Xcode SDK作为修改和编译指定平台代码的一个选择，Cordova会将它生成在 platforms/ios里。其他平台的SDK也可以使用相同的方法。

在模拟器或真实设备上测试这个APP

   移动平台的SDK和模拟器经常捆绑一个设备图像，用来在主屏启动这个app，还可以看一下他是怎么和许多平台特性交互的。运行下面的命令来重建app，在一个指定的平台模拟器里看它：

 $ cordova emulate android

　　一些移动平台默认模拟一个特殊的设备，例如iOS系统的iPhone。对于其他平台，你可能需要首先和一个模拟器连接一个设备。

　　注意：模拟器支持Amazon当前不可用的Fire系统

　　(查看 平台指南 的细节) 例如，你可能首先运行 android 命令启动Android SDk，然后运行一个特殊的设备图像，根据它的默认行为来启动自己：

　　

　　接着 cordova emulate 命令刷新模拟器图像显示最新的应用程序，现在可以在主屏启动：

　　

　　另外，你还可以把手机连接到你的电脑然后直接测试这个app

    $ cordova run android

　　在运行这个命令之前，你需要建立一个设备来测试，下面的程序在每个平台都变化多端。在Android 和Amazon Fire OS设备上，你不得不提供一个可用的 USB debugging 选项，并且可能提供一个USB驱动在你的开发环境上。在平台指南查看在每个平台所要求的细节 。

Add Plugin Features

　　当你构建并查看一个新项目时，默认的应用程序看上去好像不能做很多事。你可以充分利用标准的web技术许多方式来修改app，但是app想要和不同层次设备的特性紧密交流，你需要添加提供使用核心cordova API权利的插件。

　　插件 是一点附加代码，向本地组件提供一个接口。你可以设计你自己的插件接口，例如当设计一个混合app的时候，它和本地组件混合了一个cordova web视图。 (看嵌入WebViews 和插件开发指南 的详细说明.) 更常见地，你将添加一个插件来使cordova的基本设备级的特性之一能够使用，在API Reference有更详细的说明 。包括社区提供的其他插件的列表，可以在 plugins.cordova.io找到。你可以使用CLI从注册表取搜索插件。例如，搜索 bar 和 code 生成一个对大小写不敏感匹配这两个子字符串的结果。：

    $ cordova plugin search bar code

    com.phonegap.plugins.barcodescanner - Scans Barcodes

　　只搜索 bar 生成另外的结果:

    org.apache.cordova.statusbar - Cordova StatusBar Plugin

　　这个 cordova plugin add 命令需要你指定插件代码仓库。请注意，当你是Web项目开发流并且使用CLI时，CLI将会很小心的向每个平台合适的地方添加这个插件代码。(如果你是使用本地项目开发刘，你将不得不为每个平台多次使用Plugman添加插件（引导链接）

　　这是一些你可能使用CLI怎样为app添加特性的例子：

• 基本设备信息 (Device API):

    $ cordova plugin add org.apache.cordova.device

• 网络连接(Connection) 和电池事件(Events):

   $ cordova plugin add org.apache.cordova.network-information
   $ cordova plugin add org.apache.cordova.battery-status

• Accelerometer, Compass, and Geolocation:

    $ cordova plugin add org.apache.cordova.device-motion
    $ cordova plugin add org.apache.cordova.device-orientation
    $ cordova plugin add org.apache.cordova.geolocation

• Camera, Media playback and Capture:

    $ cordova plugin add org.apache.cordova.camera
    $ cordova plugin add org.apache.cordova.media-capture
    $ cordova plugin add org.apache.cordova.media

• 设备可访问的文件和网络 (File API):

    $ cordova plugin add org.apache.cordova.file
    $ cordova plugin add org.apache.cordova.file-transfer

• 通知(Notification) 通过对话框或震动:

    $ cordova plugin add org.apache.cordova.dialogs
    $ cordova plugin add org.apache.cordova.vibration

• Contacts:

    $ cordova plugin add org.apache.cordova.contacts

• Globalization:

    $ cordova plugin add org.apache.cordova.globalization

• 闪屏(Splashscreen):

    $ cordova plugin add org.apache.cordova.splashscreen

• 打开新浏览器窗口(InAppBrowser):

    $ cordova plugin add org.apache.cordova.inappbrowser

• 调试控制台:

    $ cordova plugin add org.apache.cordova.console

　　使用 plugin ls (或者 plugin list, 或者 plugin 本身)来查看当前已安装的插件。每个通过自己的标识符显示：

    $ cordova plugin ls    # or 'plugin list'
    [ 'org.apache.cordova.console' ]

　　删除插件指的是出现在列表相同的标识符。例如，这是你将怎样从一个发布版本移除一个调试控制台的支持：

    $ cordova plugin rm org.apache.cordova.console
    $ cordova plugin remove org.apache.cordova.console    # same

　　你可以通过每个命令指定一个以上的参数批删除或添加插件:

    $ cordova plugin add org.apache.cordova.console org.apache.cordova.device

Advanced Plugin Options（高级插件选项）

　　当添加一个插件时，几个选项允许你指定从哪儿获取这个插件。上面的例子使用了一个总所周知的registry.cordova.io 注册表，通过 id指定这个插件:

    $ cordova plugin add org.apache.cordova.console

　　这个 id 可能包含插件的版本号，在 @ 符号之后添加。 The latest version is an alias for the most recent version. For example:

    $ cordova plugin add org.apache.cordova.console@latest
    $ cordova plugin add org.apache.cordova.console@0.2.1

If the plugin is not registered at registry.cordova.io but is located in another git repository, you can specify an alternate URL:

    $ cordova plugin add https://github.com/apache/cordova-plugin-console.git

The git example above fetches the plugin from the end of the master branch, but an alternate git-ref such as a tag or branch can be appended after a # character:

    $ cordova plugin add https://github.com/apache/cordova-plugin-console.git#r0.2.0

If the plugin (and its plugin.xml file) is in a subdirectory within the git repo, you can specify it with a : character. Note that the # character is still needed:

    $ cordova plugin add https://github.com/someone/aplugin.git#:/my/sub/dir

You can also combine both the git-ref and the subdirectory:

    $ cordova plugin add https://github.com/someone/aplugin.git#r0.0.1:/my/sub/dir

Alternately, specify a local path to the plugin directory that contains the plugin.xml file:

    $ cordova plugin add ../my_plugin_dir