使用Cordova API开发(上)

到目前为止咱们已经了解了如何搭建Cordova开发环境及如何使用Cordova和移动平台开发商提供的工具。之后的部分将讨论更多的关于Cordova编程方面的内容。这里介绍Cordova APIs，及在应用中如何使用。

本文承接上篇《使用PhoneGap Build》。

对API自己不会太深刻，关于这些内容请参考官方API文档，主要演示如何在应用中使用。

Cordova核心API

Hybrid应用比web应用强大之处在于可使运行在容器中的web内容访问native APIs。Cordova提供了用于移动设备上的API的子集，包括：

• 加速度计(Accelerometer)
• 相机(Camera)
• 录制(Capture)
• 指南针(Compass)
• 网络链接(Connection)
• 联系人(Contacts)
• 设备(Device)
• 事件(Events)
• 文件(File)
• 地理定位(Geolocation)
• 全球化(Globalization)
• 内置浏览器(InAppBrowser)
• 多媒体(Media)
• 消息提醒(Notification)
• 闪屏(Splashscreen)
• 存储(Storage)

某些情景中，API模仿已经由现代浏览器提供的能力；大多数状况下，应用使用内嵌在Cordova容器中的native浏览器、webView提供的API。对于没有在浏览器上实现提供API的平台，Cordova开发团队会实现这个API,这样在全部支持的平台上均可以使用了。能够看看Cordova地理定位(Geolocation)、文件(File)或存储(Storage)API。它们在大多数平台上的实现都很标准，实现时不用作太多处理。

而文件和存储的API已经成为移动浏览器的标准，Geolocation也是这种状况，可是以后会谈到的"硬件API"部分涉及到的API和它相似，因此也会谈到些。Contacts API也是基于这种标准的，可是由于比较特殊须要说明一下。

以前提到过全部的核心API在3.0版本以后都从Cordova容器中移除并以插件的形式实现。所以须要在项目中使用以下命令关联插件：

cordova plugin add path_to_plugin

例如要使用Camera API，使用以下命令添加相机功能：

cordova plugin add https://git-wip-us.apache.org/repos/asf/cordova-plugin-camera.git

这样就把相机插件从公共Git资源库下载下来了，若是插件位于本地，好比"d:\cordova\"下，path_to_plugin替换成本地存储路径。

cordova plugin add d:\cordova\cordova-plugin-camera

更多这方面的内容请参考《使用Cordova命令行》。

使用API的Cordova文档

由于有开发团队一直在维护Cordova容器、API和插件，而且有专门的团队在努力维护文档，因此它的的API文档写的很好，在构建Cordova应用时值得花些时间阅读。在线文档地址在www.cordova.io，文档连接在页面的下面，连接指向适当的语言和最近发布的框架版本。文档页面右上方有下拉列表能够选择不一样的版本。

使用API开发时，要注意在文档中说明的每一个API特别之处。虽然Cordova开发团队尽力在跨平台上保存API的一致性，在一些平台上实现的某些功能是不可用的，或者并非要实现的状态。碰到使用Cordova API不尽如人意的地方能够去文档中检查一下API的特别说明。

设置应用许可

大多数Cordova API使用navtive API,许多都有安全限制。出于保护用户和设备考虑，开发者在部署到设备上时要设置应用配置。这些设置配置了native应用容器，由它在安装时通知操做系统使用了有某些限制的API。这样操做系统在安装时会弹出是否容许应用的API。

以下图是在安装HelloCordova应用时出现的提示：

若是某个API或功能在平台上不可用，或者被用户禁用了，使用它的应用在执行这部分时会失败且不会给出提示。设想一下这种状况应用会抛出某种异常，可是由于没有处理的case，所以在执行时会跳过执行这个API。若是在实现某个功能而且只是不工做而不给出任何提示时，检查一下应用权限设置。

要了解应用中使用的API须要什么样的配置设置，要参考具体的API的文档。下图是一个Camera API文档页面，其中包括叫"Accessing the Feature"的部分，描述了怎样向项目中添加API和在应用中使用API时要作怎样的配置设备。

如上图说明了在每一个支持的平台上须要更新的配置文件，以及启用功能时文件中要添加的内容。配置文件一般是config.xml文件，平台不一样位置不一样。

幸亏Cordova CLI能够为咱们管理设置应用权限。若是用CLI添加插件，它会在config.xml中为项目中全部平台做了一些配置改动。以下面的配置文件所示(添加camera再粘一遍)：

<?xml version='1.0' encoding='utf-8'?>
<widget id="io.cordova.hellocordova" version="0.0.1" xmlns="http://www.w3.org/ns/widgets" xmlns:cdv="http://cordova.apache.org/ns/1.0">
    <name>HelloCordova</name>
    <description>
        A sample Apache Cordova application that responds to the deviceready event.
    </description>
    <author email="dev@cordova.apache.org" href="http://cordova.io">
        Apache Cordova Team
    </author>
    <content src="index.html" />
    <plugin name="cordova-plugin-whitelist" version="1" />
    <access origin="*" />
    <allow-intent href="http://*/*" />
    <allow-intent href="https://*/*" />
    <allow-intent href="tel:*" />
    <allow-intent href="sms:*" />
    <allow-intent href="mailto:*" />
    <allow-intent href="geo:*" />
    <platform name="android">
        <allow-intent href="market:*" />
    </platform>
    <platform name="ios">
        <allow-intent href="itms:*" />
        <allow-intent href="itms-apps:*" />
    </platform>
</widget>

到这里讨论了全部背景知识，开始讨论API。

Cordova对象

一些Cordova API并非必要的，然而它们对于Cordova应用也是有用的对象。好比connection和device，下面对它们作下介绍而且在说明如何在应用中使用。

Connection类型

移动应用时常须要知道可用网络链接的类型。由于网络服务商在对超出的数据流量要收取费用，应用在进行数据量大的升级时建议使用收费低的Wifi而不要使用蜂窝移动网络。最佳实践是开发者对应用使用的数据使用类型作出分类，以便在写代码时使用数据流量费用最少。对于这种状况Cordova提供了connection对象用来识别当前可用的网络链接。使用前首先添加插件：

cordova plugin add https://git-wip-us.apache.org/repos/asf/cordova-plugin-network-information.git

在代码适当的位置，经过如下js代码肯定链接类型：

var ct = navigator.connection.type;

接下来能够把ct的值和预约义的链接类型属性的作值对比：

• Connection.CELL
• Connection.CELL_2G
• Connection.CELL_3G
• Connection.CELL_4G
• Connection.ETHERNET
• Connection.NONE
• Connection.UNKOWN
• Connection.WIFI

应用使用网络前要肯定是否有网络链接，能够这么写：

ct = navigator.connection.type;
if (ct != Connection.None) {
    console.log("You have a connection");
    // 使用网络的代码

} else {
    // 警告用户没有网络链接没法进行
}

应用在每次要知道网络的状态是要查询connection对象，前面的ct变量在网络状态变化时不会继续维持一个有效状态值。以后会涉及到相关事件能够看到如何监视网络链接。

或者要检查某个网络类型，能够这么写：

ct = navigator.connection.type;
if (ct == Connection.WIFI) {
    console.log("You have a WIFI Connection");
    // 使用WIFI的的代码功能
} else {
    // 警告用户没有WIFI没法继续
}

应用可使用online和offline事件监视网络的实时状态(稍后介绍)。

Device

device对象能够用来肯定设备的有限数量的信息。可用的设备属性以下：

• device.name
• device.cordova
• device.platform
• device.uuid
• device.verson
• device.model

使用前安装device插件，在《Cordova应用解析中》对它有描述。

警告用户

开发者常常要通知用户一些活动的状况。web应用能够在页面内部或以HTML弹出框显示这些信息。但有时候须要开发者管理这种提示。有两种类型的提示，姑且称之为hardware notifications和visual notifications，下面分别说明。

Hardware Nofifications

大多数智能手机为开发者提供了让设备蜂鸣或振动的API，Cordova也提供了相同的调用接口。使用前要安装，命令以下：

cordova plugin add https://git-wip-us.apache.org/repos/asf/cordova-plugin-vibration.git

Beep

要使用设备的蜂鸣，应用要调用navigator.notification.beep方法，振动要调用navigator.notification.vibrate方法。每一个都带一个参数，用来控制提示要持续多久或发生多少次。beep方法的参数用来控制方法调用时设备蜂鸣多少次：

navigator.notification.beep(quantity);

Vibrate

vibrate方法接受一个持续时间参数，单位是毫秒：

navigator.notification.vibrate(duration);

Visual Notification

web应用能够调用Cordova的一些方法与用户交互，固然可使用js的alert()、confirm()和prompt()方法，可是Cordova的方法是异步的，而且对显示内容有更大的控制权限。

使用前先安装插件，命令以下：

cordova plugin add https://git-wip-us.apache.org/repos/asf/cordova-plugin-dialog.git

Alert()

不一样于js中的alert()方法，Cordova的alert()方法以下：

navigator.notification.alert("This is a Cordova Alert()", myCallback, "Alert Test", "Click Me");

这样能够设置对话框标题和按钮文本。js alert()方法是同步的而Cordova alert()方法是异步的，也就是说js警告会立刻显示，而Cordova警告在Cordova容器准备好后显示，方法以下：

naviator.notification.alert(message, callback, [title], [buttonLabel])

callback参数定义了点击对话框中按钮时调用的函数，应用在用户点击按钮以前是空闲状态，点击执行回调函数。若是把callback参数设为null,则应用在警告弹出以后继续执行而不会等用户点击按钮。

title和buttonLabel参数都是可选的。

Confirm

confirm方法与alert方法类似，但它能够指定多个按钮的标签，而且callback方法传入了几个值用来指明点击了哪一个按钮。方法声明以下：

navigator.notification.confirm(message, callback,[title],[buttonLabels]);

如下代码段说明了怎样使用confirm方法：

navigator.notification.confirm('Do you want to continue?', doContinue, 'Please confirm', 'Yes, No');

function doContinue(buttonNum) {
    navigator.nofication.alert('You chose option #' + 'buttonNum + '?', null, 'Really?', 'Yes');
};

传递给回调函数的参数是数值型，指出点击了哪一个按钮，若是点击第1个按钮回调函数接受1，点击第2个则接受2，依次类推。

Prompt

Prompt收集来自表单外部的用户信息。调用函数声明以下：

navigator.notification.prompt(message, callback, [title], [buutonLabels], [defaultText]);

一样中括号中的参数是可选的。调用prompt方法并定义处理用户输入的回调函数。

navigator.notification.prompt('Please enter your nickname', gotData, 'NickName', ['Cancel', 'OK'], 'Jimmy');

function gotData(res) {
    navigator.notification.alert('You chose option #" + res.buttonIndex + '\nYou entered: ' + res.input1, null, "Results' + 'OK');
};

注意prompt使用了和confirm不一样的按钮标签格式。prompt使用字符串数组，而confirm使用逗号分隔的字符串。

Cordova事件

Cordova框架了一组事件，开发者用来对某些运行Cordova应用的设备上的事件做出反应。事件处理的一种状况是硬件相关活动，如电池状态变化或用户按了某个物理按钮；另外一种状况是应用程序状态的变化，如应用被停止或恢复。这些web应用使用的事件同Native应用使用的是同样的。

完整的支持的事件列表以下：

Cordova 事件	描述
backbutton	用户按设备后退键时触发
batterycritical	电池达到关键状态时触发。关键状态的定义因平台而异
batterylow	电池低电量状态时触发。低电量状态的定义因平台而异
batterystatus	电池状态至少改变1%时时触发(增长或减小)
deviceready	cordova容器完成初始化时触发
endcallbutton	在用户按手机的结束通话键时触发
menubutton	在用户按手机的菜单键时触发
offline	在设备失去网络链接时触发
online	在设备由没有网络链接转换到链接状态时触发
pause	Cordova应用被挂起时触发。通常发生在用户跳转到另外一个应用，系统把当前应用放在后台时
resume	在被挂起的应用转到前台时触发
searchbutton	在用户按查找键时触发
startcallbutton	在用户按通话键时触发
volumedownbutton	用户按音量减小键时触发
volumnupbutton	用户按音量键增长时触发

老式手机使用物理按钮来拨通和结束通话。在较新的设备上，这些按钮被移除并用虚拟按键代替。虚拟按键只在用到(如菜单和查找按键)，或只用于某些应用(像电话按键)。

大多数的列出的事件都在Cordova容器中实现了。只有电池状态以插件形式实现了。要使应用可以监视电池事件必须首先添加电池状态插件：

cordova plugin add https://git-wip-us.apache.org/repos/asf/cordova-plugin=battery-status.git

其中device事件在《cordova应用解析》讨论过。

要监视这些事件能够简单的在应用中为某个事件注册监听器。

document.addEventListener("eventName", eventFunction);

如要监听是否断开网络链接，能够注册offline事件的监听器：

document.addEventListener("offline", isOffline);

function isOffline() {
    // 断开网络链接时的动做
}

事件在不一样的移动平台上并不都准确的定期望的状况触发，须要在不一样设备上测试确保应用定期望的工做。