使用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="[e-mail]" 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() {
    // 断开网络连接时的动作
}        

事件在不同的移动平台上并不都准确的按期望的情况触发，需要在不同设备上测试确保应用按期望的工作。