Cordova 入门文档

 

关于 Apache Cordova

       Apache Cordova 是一套设备API ，他可以让手机APP 开发者们使用 JavaScript访问到原生设备功能，比如摄像头、加速器。结合一些 UI框架如 Jquery Mobile 、Dojo Mobile 等等。允许智能机的app 使用 HTML、CSS、JS 来开发.(这真的很棒哦)

 

 

       当你使用Cordova API 时，构建一个 app 就可以不需要任何原生代码（java.OC ,等等），替代而为的是 web 中的脚本，这些api 存在于应用程序本身（通常不在远程http服务器上）。

 

      Cordova提供一套统一的 Javascript 库来调用，使用特定设备的本机代码js 库。Cordova可以支持以下平台 iOS, Android, Blackberry, Windows Phone, Palm WebOS, Bada, and Symbian

 

 

 

 

Apache Cordova 文档

 

概述：

       Apache Cordova 是一款开源的手机开发框架，他允许你使用标准的web 技术来做跨平台开发，避免每一种手机平台的原生开发语言。应用程序运行在每个特定的平台的包装器内，依赖标准的 API 来访问每种设备的传感器，数据和网络状态。

 

       Apache Cordova 在2012年推出作为阿帕奇软件基金会顶级（ASF）的项目。通过ASF，未来Cordova 确保作为开源的项目管理。他会保持免费开源在阿帕奇的许可下

 

用Apache Cordova 你可以：

 

• 手机开发者想要扩展他的app至很多的平台而不需要用其他平台的语言来重载；
• a web developer and want to deploy a web app that's packaged for distribution in various app store portals.一个web 开发者想要部署打包 他的webAPP 分发到各种平台的 app 商店
• 手机开发者 感兴趣混合的 原生应用程序组件和 webView(特殊的浏览器窗口) 能访问设备级别的 API，或者你可以开发 一个 原生和 webview 组件之间的插件接口。

 

基础组件：

       Cordova 应用程序依赖一个公共的 config.xml 文件，文件提供一些 app的信息和特殊的参数来决定app 怎么工作，诸如是否响应方向转变。这个文件遵循W3C 的打包Web应用程序,或小部件,规范。

 

       Application 本身作为 web 页面来实现，默认的本地名字是 index.html ,它引用任何 css,js，image, 媒体文件，和其他必要的资源。App 作为一个在原生的应用程序包装器内运行，你可以分发到 app stores.

 

       Cordova 能够是WebView成为应用程序提供整个用户界面。在一些平台上,也可以在一个更大的一个组件,混合应用程序,混合使用WebView本机应用程序组件。

 

       插件接口可以在Cordova和本地组件相互通信。这使您能够从JavaScript调用本地代码。理想情况下,JavaScript api,跨多个设备平台的本机代码是一致的。从版本3.0开始,插件api提供绑定标准装置。第三方插件提供额外的绑定功能不一定在所有的平台上都可用。你可以找到这些第三方插件的插件注册表然后在应用程序中使用它们。你也可以开发自己的插件,如插件开发指南中所述。插件可能是必要的,例如,Cordova 和自定义本地组件之间的通信。

 

 注意： 在 3.0 版本中，你创建的 Cordova 工程是没有任何 插件存在的，即使是 业务插件，你需要手动的 添加；还有Cordova 不提供任何 UI 组件，需要你自己使用第三方库

 

开发路径

      在版本3.0 中，有两种开发流程，使用其中的一种都能实现相同的任务，下面是他们的特点：

•   Cross-platform (CLI) workflow: 使用这个工作流你可以让你的应用程序运行在尽可能多手机操作系统上,不需要对特定于平台的开发。此工作流集中在Cordova工具中,称为Cordova CLI, CLI是一个高级工具,允许您构建项目,抽象了底层shell脚本的功能。CLI复制一套公共的的web资源为每个移动平台的子目录,使任何必要的配置更改为每个运行构建脚本生成应用程序二进制文件。CLI还提供了一个公共接口应用插件在CLI应用程序。更多的细节,看到命令行界面。除非你需要platform-centered工作流,建议跨平台的工作流。.
• Platform-centered workflow: 使用此工作流 你可专注于为一个平台构建一个应用程序,需要能够修改它在一个较低的级别。使用此工作流如果您需要修改的项目在SDK。此工作流依靠一套底层shell脚本,针对每种受支持的平台,和一个单独的Plugman实用程序允许您应用插件。虽然您可以使用此工作流构建跨平台的应用程序,通常更加困难,因为缺乏一个高级工具意味着独立构建周期为每个平台和插件修改。不过,这个工作流允许您访问每个SDK提供的开发选项,和对复杂混合应用至关重要。看到每个平台上的各种平台 Platform Guides 细节的shell工具可用。

第一次开始的时候,可能是最容易的使用Cross-platform工作流来创建一个应用程序,在命令行界面。然后您可以选择切换到platform-centered工作流如果你需要SDK提供了更大的控制。底层shell实用程序可在cordova.apache.org上，比CLI在一个单独的分布。项目最初生成通过 CLI,这些shell工具也在项目的各种  platform/ * /cordova目录下。

 

   注意： 一旦你从 基于 CLI开发流 转向围绕 特定平台的 SDK和 shell 工具，你就不能回到重前了. CLI 维护 一套 公共的 跨平台的 源码,在每个构建它使用特定于平台的代码编写。保存您所修改的特定于平台的资源,您需要切换到platform-centeredshell 的工具,忽视了跨平台的源代码,而不是依赖于特定于平台的源代码。

 

安装Cordova

        cordova 的安装有所不同，取决于上面你所选择的workflow;

• Cross-platform workflow: see The Command-Line Interface.
• Platform-centered workflow: see the Platform Guides.

 

 

The Command-Line Interface

        这节讲述如果创建 app 和部署至各种手机平台，使用 Cordova command-line interface(CLI) ，这个工具可以创建 app,编译和运行在不同的平台上，CLI是 Cross-platfrom Workflow 的主要工具，你可以使用CLI 初始化你的项目，然后呢，切换至各种不同平台的 SDK 和shell 工具继续开发。

 

先决条件：

              运行任何命令之前，你需要安装你需要的平台的 SDK（参考Platform Guides）

添加支持任何平台或重建一个项目,你需要从同一台机器上运行命令行界面,支持平台的SDK。CLI支持以下组合

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

 

 

 

安装 Cordova CLI

      安装CLI 安装下面步骤

1. 下载并安装 Node.js。安装后,你应该能够对你的命令行调用node 和npm。如果需要,您可以选择使用一个工具如nvm或nave来管理你的Node.js安装。
2. 下载暗转一个 git client, 安装后, 你使用 git 命令在命令行中.甚至你不需要手动调用 git , 创建一个新项目的时候 CLI在后台 帮你下载了 资源.
3. 安装cordova 模块 使用 npm Node.js 的 npm . cordova 模块自动下载

• 在 OS X 和 Linux:

   $ sudo npm install -g cordova

在OS X 和 Linux,  npm 需要家前缀 sudo 命令下载开发工具 ,否则在一些严格受保护的目录诸如： /usr/local/share.

• 在 Windows:

   C:\>npm install -g cordova

The -g flag above tells npm to install cordova globally.

 -g 选项 告诉 npm把cordova 安装在全局。否则它将被安装在 当前工作目录的node_module的子路径下

安装日志可能会产生错误在一些没有安装平台SDK的 机器上。.

安装成功后 你可以运行 cordova命令了

 

Create APP  创建一个 app

 选择一个维护代码的目录下，使用命令

在MAC上：

    $ cordova create hello com.example.hello HelloWorld

在windows:

 

 

命令 cordova create hello com.wsp.helloworld helloworld

 这个命令需要花些时间，所以耐心等待了程序猿们，（萌萌，不萌）

你可以加个 –d 命令选项来查看详细的过程

 

第一个参数 Hello 是你项目指定的一个目录，注意不要存在这个目录，因为cordova 会为你生成这个目录，www 是应用程序主页的

目录，以及各种资源在css,js和img,遵循通用的web开发文件命名规范。这些资源将被存储在设备上的本地文件系统,而不是远程服务。Config.xml文件包含重要的元数据用来生成和分发应用程序。以下就是 project的目录，

 

 

第二个参数 com.wsp.helloworld ,形如域名的倒叙，这个参数是可选的，但前提是你必须得忽略第三个参数，（因为参数的位置）。你也可以在之后的 config.xml 文件中编辑这个值，但是请注意，使用config.xml 更改这个值会生成外部代码。比如 java的package名字。默认是io.cordova.hellocordova ,建议使用合适的值。

 

第三个参数 helloworld ，会提供给程序一个显示出来的标题，这是可选的参数，在之后的 config.xml 文件可以修改，but   but 但是但是。意识到，config.xml 会根据你修改的这个值，生成外部代码，诸如 java 的  class 名字。默认的是 HelloCordova ，推荐你使用个合适的名字。

 

Add Platforms 增加平台

  所有的后续命令必须在 project 的目录内，或者在这个作用域内的子目录下。

 

 

构建 project时，需要指定一套特定的平台，你可以使用下面命令取决于你电脑是否支持这个平台，是否安装这个平台的sdk ,

运行以下任何一个命令在MAC上

 

运行以下任何一个命令在Windows

 

以下命令是坚持你当前平台

 

(Note: platform 和platforms 是同义，作用是一致的)

 

运行以下任何一条命令都能删除平台

 

运行 add or remove platforms 命令会影响工程下 platform 目录里面的内容，每一个特定的平台为一个子目录：

 

 

 

 

在platforms 目录下可以看到有两个平台的子目录。

www 是源目录，将会被复制到各个平台的子目录中去，

诸如: platforms/ios/www 或者 platforms/android/assets/www ，由于 CLI不断的 从www 文件夹内复制文件到各个platform 的子目录中去, 所以你只需要编辑 www 内的文件便可，而不是那些 platforms 的子目录里的文件。当然如果你使用版本控制工具，你应该添加源文件夹 www ,以及合并文件夹。

 

 

警告：使用CLI构建您的应用程序时,您不应该编辑/platfors/  目录中的任何文件,除非你知道你在做什么,或者文档指定。此目录中的文件通常被重写 在准备申请的时候,或当插件重新安装。

 

 

在这一点上，如果你希望使用 SDK （Eclipse ,或者XCode）打开 你创建的工程，在/platform/ 子目录下 使用 SDK打开这些衍生资源进行开发。 这是因为 SDK特定的元数据文件存储 在 适当的 /platforms/ 子目录中 （如何在 IDE下开发应用程序 请参考Platform Guides ）使用这种方法,如果你只想使用CLI初始化一个项目,然后切换到本机工作的SDK。

 

嘿 哥们，如果你想使用 crosse-platform 工作流方法整个开发周期，那么跟着我读下去

 

 

Build the App 构建APP

 

 

默认，cordova创建脚本 生成一个基于web 程序的骨架（这个web 程序在 www/index.html）

编辑这个应用程序，编辑任何的业务，都应该在  deviceready 这个事件的处理函数内，

默认引用在 www/js/index.js

 

 

运行下面命令来迭代的编译你的工程。

 

 

 

生成的 特定平台的 代码在 project 的 platforms 的子目录下 ，你可以随意的限制每一个的范围构建特定的 平台

 

 

 

在这个例子中，你运行了 prepare命令，你就可以使用 Xcode SDK 来替代 Cordova 编辑编译 特定平台的 代码，在/platforms/ios 内，使用相同的方法 作用于其他平台。

 

 

Test the App on an Emulator or Device 在模拟器上测试

SDK 为 移动平台提供了模拟器，通常绑定程序的图片，你在主屏幕上 直接可以启动应用程序。观察有什么影响和其他平台的特性，运行以下命令, 重建应用程序并查看它在特定平台的模拟器:

 

 

你还可以 把手机插到电脑上 来测试运行 app

 

 

 

Add Plugin Features 添加插件特性

 

       当你构建一个工程时，你会发现这个应用程序好像做不了太多事件。你可以来更新这个app 利用 标准的 web 技术，但是却不能和设备通信，你需要添加 提供访问 核心 Cordova API 的 插件。

 

       插件是一些 提供 本地组件接口的一些代码，你可以设计自己的 插件接口（请参考 Embedding WebViews和 Plugin Development Guide）你要添加一个插件 激活 Cordova 中一个基础的设备级别特性。

 

        在 3.0 版本中，你创建的工程中没有任何一个插件存在，即使是核心的 Cordova 都不存在，你需要 显示的 添加他。

 

       一个插件列表，包括额外的第三方插件来自于社区，可以从 注册表中（http://plugins.cordova.io/）查找他们。 使用CLI 可以重 注册表中搜索他们。例如： 查找bar 和 code 产生单个结果 （匹配条件是不区分大小的 bar 和 code 不区分大小）

 

 

 

cordova plugin add 这个命令 需要指定一个仓储为插件代码。这里是一些怎么使用CLI 去添加特性到 app的 例子

• 基础设备信息 (Device API):
• 网络连接和设备事件
• 加速度计, 罗盘,地理位置:
• 相机,媒体,捕获:
• Access files on device or network (File API):
• Notification via dialog box or vibration:
• Contacts:
• Globalization:
• Splashscreen:
• Open new browser windows (InAppBrowser):
• Debug console:

  $ cordova plugin add cordova-plugin-device

  $ cordova plugin add cordova-plugin-network-information

  $ cordova plugin add cordova-plugin-battery-status

  $ cordova plugin add cordova-plugin-device-motion

  $ cordova plugin add cordova-plugin-device-orientation

  $ cordova plugin add cordova-plugin-geolocation

  $ cordova plugin add cordova-plugin-camera

  $ cordova plugin add cordova-plugin-media-capture

  $ cordova plugin add cordova-plugin-media

  $ cordova plugin add cordova-plugin-file

  $ cordova plugin add cordova-plugin-file-transfer

  $ cordova plugin add cordova-plugin-dialogs

  $ cordova plugin add cordova-plugin-vibration

  $ cordova plugin add cordova-plugin-contacts

  $ cordova plugin add cordova-plugin-globalization

  $ cordova plugin add cordova-plugin-splashscreen

  $ cordova plugin add cordova-plugin-inappbrowser

  $ cordova plugin add cordova-plugin-console

 

Note ：CLI添加插件代码适合每个平台。如果你想开发与底层shell工具或平台sdk您需要运行Plugman工具 为每个平台分别添加插件。(请参考 Using Plugman to Manage Plugins).

 

 

 

使用 cordova plugin ls 命令可以查看当前安装了多少插件；

 

 

Cordova plugin rm 删除一个插件

 

 

 

你可以批处理 添加、删除 多个插件  cordova pluging add pluging-name1 plugin-name2 …

 

 

 

 

Advanced Plugin Options 高级插件选项

 

       当你添加插件时， 你可以指定是从那获取的插件，上面的例子是 从 知名的registry.cordova.io   指定插件的 id ;

 

 

 

 

      你还可以在ID 后面加上 版本号，插件ID 追究 @符号 ， ‘latest’是 最新版本的 别名 例如：

 

 

       如果 插件不在  registry.cordova.io中，位于 另外一个 git 仓储中，你可以用 URL开替换

 

上面例子git 获取插件从主分支,但另一种git-ref 如一个标签或分支之后 可以追加一个#字符:

 

如果插件(和它的plugin . xml文件)是在子目录内的git存储库时,您可以指定它追加一个‘ : ’ 仍然需要注意: ‘#’ 字符

 

       你也 可以合并 git-ref 和 子目录

 

 

       此外,指定一个本地路径插件目录,其中包含plugin . xml文件

 

 

 

Using merges to Customize Each Platform

 

Cordova,允许您轻松地部署应用程序对于许多不同平台,有时你需要添加自定义。在这种情况下,你不想修改各种www目录中的源文件中的 顶层平台目录,因为他们经常替换为顶级www目录的跨平台的来源。

相反,顶级mergers 目录指资源提供了一个部署在特定平台上。每个特定平台的子目录merges反映了www源代码树的目录结构,允许您根据需要来覆盖或添加文件。例如,下面是如何使用Android合并 增加的默认字体大小和Amazon Fire OS 设备; 

1. 在 www/index.html 文件中 添加 一条 css 引用;

 

 

2  创建一个 空的 css 文件  www/css/overrides.css, 这个文件用来给 非android平台的调用以防止出现丢失文件错误；

 

 

 

3 创建一个css在 merges/ android子目录内 ,然后添加一个对应的overrides.css

文件。指定CSS,覆盖了默认字体大小12号 内指定www /css /index.css,例如:

 

 

你重建项目是，Android版本是自定义的 字体，其他的保持不变。

 

        

       你也可以在 merges 中添加 源www 目录不存在的文件。 例如： 一个app 包含 一个 后退按钮的 图片 在 IOS 接口，存储在 mergers/ios/img/back_button.png , 而Android版本可以捕获backbutton事件从相应的硬件按钮