使用Cordova API开发(下)

本文承接上篇《使用Cordova API开发（上）》。文中示例代码见篇尾链接。

---

硬件API

Cordova提供了一些与常见的智能手机硬件交互的API，这让Cordova应用可以以某种方式与外部世界交互。

对这些API Cordova文档没有专门分组显示，我们把它们放在一起了解，包括：

• Accelerometer(加速度计)
• Camera(相机)
• Capture(采集)
• Compass(指南针)
• Geolocation(地理定位)

Acclerometer, Compass，Geolocation API以相同的方式工作。应用可以测量某段距离的当前值，或者设置监视器，这样可以测量一段时间内的位移。Camera和Capture API使用设备相机抓取图像，但它们操作不一样，Capture API还可以录制视频和和音频。

World Wide Web组织对这些功能做了规范定义。Compass API规范定义在http://dev.w3.org/2009/dap/system-info/compass.html，Geolocation API规范在http://dev.w3.org/geo/api/spec-source.html，Device Orientation规范定义在http://www.w3.org/geo/api/spec-source-orientation。

会发现一些Cordova API和W3C规范的很接近，另外一些则不然。例如，Cordova Compass API有一个getCurrentHead方法，而W3C规范使用getCurrentOrientation,可以预见未来Cordova API会逐渐采用标准定义，应该时刻关注这种改进。下面简单说一点使用方法，其中一些API支持许多选项，要深入全面了解这部分内容可参考相关书籍。

Accelerometer(加速计)

Cordova Accelerometer API让应用在三维空间(使用笛卡尔三维坐标系统)中决定设备方向。使用这个API前要安装插件，使用以下命令：

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

API公开了三个方法：

• accelerometer.getCurrentAcceleration
• accelerometer.watchAcceleration
• accelerometer.clearWidth

getCurrentAcceleration方法让应用查询设备当前方向。watchAcceleration和clearWatch方法用于捕获一段时间内在某个设备方向的位移，重复地在某个时间间隔上用加加速计测量。

在应用中这么写测量设备当前方向：

navigator.accelerometer.getCurrentAcceleration(onSuccess, onFailure)

参数是两个函数名，onSuccess在测量成功时执行而onFailure在出错时执行，如下例定义两个函数：

function onSuccess(res) {
    x = res.x;
    y = res.y;
    z = res.z;
    var d = new Date(res.timestamp);
    timestamp = d.toLocaleString();
}                

function onFailure() {
    alert('I have no idea why this failed, but it did.');
}

onSuccess函数传递了一个表示加速计测量值各个不同部分，X、Y和Z表示设备在三维坐标系统中的方向，timestamp值表示日期/时间，它由测量值生成。显示在桌面上，生成图像如下图。

一些Android设备如果平放在桌面上，加速计大致返回这样的值：X:0, Y:0, Z:10，翻转后它就位于现在位置的左边，值就调整为X:10,Y:0,Z:0，把设备从底边立起来，置变为X:0, Y:10, Z:0，从顶边立起来，置变为X:0, Y:-10, Z:0。应用就使用这样的值判断用户怎么拿设备，多用在游戏和交互性的应用上。

但是Cordova不会在错误发生并调用onFailure函数时提供信息，像可以识别错误来源的错误代码或错误信息。但在调用加速计接口时如果失败，很有可能是设备就没有加速计。

getCurrentAcceleration用来在快速检查设备方向，比如在游戏中想在一段时间监视方向，getCurrentAcceleration就不好用了，而应该写代码定期检查，为了方便开发者解决这种问题，Cordova API允许开发者通过监视加速计定期的读取，使用accelerometer.watchAcceleration方法。应用使用如下代码设置监听：

var options = {frequency:1000};
watchID = navigator.accelerometer.watchAcceleration(onSuccess, onFailure, options);

onSuccess和onFailure用法和上例相同，options对象以毫秒级定义了加速计测量的频率。如果每半秒测量一次，frenquency设置成500。

示例中把watchAcceleration函数的调用结果赋给了watchID变量，用来在后边取消监视：

navigator.accelerometer.clearWatch(watchID);

这样应用会每秒读一次加速计，并把值传给onSuccess函数来处理结果。

Compass(指南针)

Compass API可以让开发者读取移动设备的朝向。这个API的使用和Accelerometer API基本一样，既可以一次查找朝向值也可以定义个监视器定期测量朝向值。两者主要不同在于上例中的results和options。

要使应用能够读朝向值首先要安装orientation插件：

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

和Compass API提供了也三个方法：

• compass.getCurrentHeading
• compass.watchHeading
• compass.clearWatch

getCurrentHeading方法允许应用查询compass的当前方向。watchHeading和clearWatch方法用来在一段时间内获得compass朝向，即每隔一段时间从compass获得测量结果。

这样获得compass测量结果：

navigator.compass.getCurrentHeading(onSuccess, onFailure);

参数是两个函数名：onSuccess在成功测量朝向值时执行，发生错误时执行onFailure。可以像下面这样使用：

function onSuccess(res) {
    magneticHeading = res.magneticHeading;
    trueHeading = res.trueHeading;
    headingAccuracy = res.headingAccuracy;
    var d = new Date(res.timestamp);
    timestamp = d.toLocaleString();
}                

function onFailure(err) {
    alert("Error: " + err.code);
}

heading对象(即例子中的res)返回给onSuccess函数，它的属性值如下表：

属性	描述
magneticHeading	以从0到359的度数表示compass的朝向值
trueHeading	compass相对于北极的朝向值，范围从0到259度。负值表示真实的朝向值不能确定
headingAccuracy	用度数表示磁极朝向和真实朝向值的不同
timestamp	朝向值测量的日期和时间(从1970年1月1日午夜开始的毫秒数)

错误发生时，onFailure函数传入错误代码可以判断错误的原因。可能的值有CompassError.COMPASS_INTERNAL_ERR和CompassError.COMPASS_NOT_SUPPORTED。

使用compass.watchHeading，使用如下代码设置监听：

var options = {frequency:1000};
watchID = navigator.compass.watchHeading(onSuccess, onFailure, options);

各参数的说明和accelerator一样，还可以指定filter值，用来定义最小度数值变化，它一定在监听触发前调用。因为compass值变化频繁，可能需要设置filter减少朝向值测量的次数，这样可以让应用只回应变化大的朝向。

代码中，调用watchHeading的结果赋给了变量watchID，用来取消监听，用法如下：

navigator.compass.clearWatch(watchID);

上面的代码应用会每隔1秒读compass并把值传给onSuccess函数。

Geolocation(地理定位)

Cordova Geolocation API让应用判断设备的物理位置。它基于W3C的Geolocation API，工作方式和Accelerometer及Compass一样。既可以查找一次位置也可以设置监听定期计算位置，唯一不同的是传递给onSuccess函数的results对象，以及创建watch时用到的option。

使用前安装Geolocation插件：

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

Geoloaction API提供3个方法：

• compass.getCurrentPosition
• compass.watchPosition
• compass.clearWatch

getCurrentPosition方法让应用判断设备当前位置，watchPosition和clearWatch方法允许应用定期计算设备位置。API返回了一个位置对象，包括coordinates和timestamp属性。timestamp见上面相关说明。coordinates属性包括下表属性：

属性	描述
accuracy	用米做单位的经度和纬度坐标的精确度
altitude	用米做单位的设备的海拔高度
altitudeAccuracy	用米做单位的海拔高度坐标的精度
heading	设备上用度数为单位的朝向(移动的方向)
latitude	用小数度数表示的位置的纬度部分
longtitude	用小数度数表示的位置的经度部分
speed	设备以米为单位的每秒的速度

Camera(相机)

Cordova框架提供了两个用于访问设备相机的API，一个是Camera API，它使用开发者能直接访问本地相机的API，另一个是Media Capture API。两者的不同是Camera API只用相机获取图像，而Media Capture API不仅能获取图像，还可以录视频或者录音。Capture API将在接下来介绍。

首先是安装Camera插件：

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

获得相机图像很简单，只需要这样调用：

navigator.camera.getPicture(onCameraSuccess, onCameraError);

下面用一个简单的相机应用(源码见附件)说明展示API如何工作,应用首先调用getPicture，然后把相机返回的数据显示出来，应用界面如下图：

点"Take Photo"按钮，打开设备本地相机应用，操作并照像。可以看到没有取消照像的方法，即使不照也要点一下拍照，然后在下一步取消。

选择保存图像并关闭设备的相机应用后，会把像片的信息返回给Cordova应用，如下图所示。例子中没有告诉getPicture任何关于怎样拍照或者处理的信息，API将使用默认设置并简单的返回一个图像文件的URI。这样Cordova应用可以使用URI访问文件，并把它显示在屏幕上、上传到服务器或其他你想做的任何事。如果上一步选择取消，API会向应用返回取消的错误信息。

以上只是camera API的默认操作，也可以调用getPicture方法并传入一个选项对象，它告诉API拍什么样的照片及怎样去拍。下面是调用getPicture方法的另一种调用方式：

navigator.camera.getPicture(onCameraSuccess, onCameraError, cameraOptions);

cameraOptions是一个js对象，cordova文档中写些起是这样的：

var options = {
    quality : 75,
    destinationType : Camera.DestinationType.DATA_URL,
    sourceType : Camera.PictureSourceType.CAMERA,
    allowEdit : true,
    encodingType : Camera.EncodingType.JPEG,
    targetWdith : 100,
    targetHeight : 100,
    popoverOptions : CameraPopoverOptions,
    saveToPhotoAlbum : false
};                    

有些平台可能会忽略其中一些属性，用之前要检查Cordova文档的quirks部分。

开发者可能会用一些或全部属性控制拍照过程。每个选项描述如下：

属性	描述
allowEdit	布尔值，照片在返回Cordova应用之前用户是否可以编辑，但并不是所有移动平台都支持。
cameraDirection	数值型，规定使用前面或后面的相机。*navigator.camera.Direction.FRONT*和*navigator.camera.Direction.BACK*分别指前面和后面。
correctOrientation	布尔值，告诉API在拍照时旋转图像来调整设备方向。
destinationType	数值型，规定API怎样返回照片。*Camera.DestinationType.FILE_URI*是默认选项前边提到过，*Camera.DestinationType.DATA_URL*，返回用base-64编码的图像，*Camera.DestinationType.NATIVE_URI*, 返回图像的本地的URI。注意使用*DATA_URL*，因为js不处理用字符编码的图像，可能会使用js应用崩溃。
encodingType	数值型，指明图像输出格式。*Camera.EncodingType.JPEG*让API返回JPEG图像。
mediaType	数值型，当*SoruceType*设置为*PHOTOLIBRARY*或*SAVEDPHOTOALBUM*，规定了用户可选择什么类型的文件。使用*Camera.MediaType.PICTURE*时只允许选择图像，*Camera.MediaType.VIDEO*允许选择视频文件，*Camera.MediaType.ALLMEDIA*允许选择任何支持的媒体文件。选择*VIDEO*时，API只返回文件的URI；如果是图像会返回信息，它的格式请参考*destinationType*。
quality	数值型，用从0到100%的百分比来控制图像的质量，100表示不经过压缩。
saveToPhotoAlbum	布尔值，指示API在拍照后把图像保存到设备照片相册中。
sourceType	数值型，指明图像来源。可能值有*Camera.PictureSourceType.CAMERA*(默认值)，或者*Camera.PictureSourceType.PHOTOLIBRARY*、*Camera.PictureSourceType.SAVEDPHOTOALBUM*。选项的行为会根据应用运行的平台不同而不同，像有些平台没有*photo libraries*或*photo albums*。
targetHeight	数值型，用来设定获得的图像的高度。
targetWidth	数值型，用来设定获得的图像的宽。

用户在返回给Cordova应用的是一张图像，但可能拍了不止一张。Cordova有一个cleanup方法用来清理这种图像。调用这个方法并且传入成功和失败的回调函数名作为参数，如下：

navigator.camera.cleanup(onCameraCleanupSuccess, onCameraCleanupError);

录制多媒体文件

Capture API和Camera API类似，可以用来拍照也可以录相或录音。它原来基于W3C Media Capture API，但开发团队没有实现API的一些功能。并且W3C也停止这个标准的工作转而关注于完全不一样的Media Capture and Streams API。首先安装Capture API：

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

API提供如下方法：

* capture.captureAudio
* capture.captureImage
* capture.captureVideo
* MediaFile.getFormData

前三个方法用法完全一样。getFormData获得关于媒体文件的信息，但由于移动设备的限制，通过这种方法获得的信息非常有限。

以三个方法之一为例，使用如下方法声明使用API：

navigator.device.capture.captureAudio(onSuccess, onFailure, options);

onSucess和onFailure方法在录制成功或失败后调用。onSuccess函数传入了一个fileList对象，可以迭代访问指向每个录制的文件的路径，如下面代码所示：

function onSuccess(fileList) {
    var len, I, path;
    len = fileList.length;
    if (len > 0) {
        for (i = 0, len; i < len; i+=1) {
            path = fileList[i].fullPath;

            // Do something with the file here
        }
    } else {
        alert("Error:No files returned.");
    }
}

有了媒体文件的路径，就可以向服务器上传文件，在应用中播放或显示，等等。

调用onFailure函数时会传入error对象，用来查找错误代码，如下面代码所示:

var onError = function(error) {
    alert('Capture error: ' + error.code);
}    

可能的错误代码有：

• CaptureError.CAPTURE_INTERNAL_ERR
• CaptureError.CAPTURE_APPLICATION_BUSY
• CaptureError.CAPTURE_INVALID_ARGUMENT
• CaptureError.CAPTURE_NO_MEDIA_FILES
• CaptureError.CAPTURE_NOT_SUPPORTED

可选的options参数控制要录制多少媒体文件，对音频文件有一个duration属性控制音频录制长度。

var options = { limit: 3, duration: 10};

有的平台上的一些options属性不可用，用之前要检查Cordova Capture API文档的quirks部分。

---

Globalization(全球化)

许多应用的用户是使用不同语言的人，如果应用受欢迎，不久就需要在多语言环境下使用。Globalization API使全球化更方便，它允许应用查询操作系统的当前设置。开发者通过这个API判断用户使用的语言，然后使用适当的语言加载内容，还使用API中的方法更好的显示日期、时间、数字和货币单位。首先安装：

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

globalization对象的方法的用法都类似，也是异步的，调用方法并传入成功和失败函数，像下面这样调用：

navigator.globalization.getPreferredLanguage(onGPLSuccess, onGPLFailure);

调用成功函数传了一个对象，应用用它查询一个或一些由方法返回的值。大多数原生方法，像前边的getPreferredLanguage方法，返回了一个像下面这样传递的字符串：

function onGPLSuccess(lang) {
    alert("Preferred language: " + lang.value);
}                          

这样当调用getPreferredLanguage成功时，onGPLSuccess函数执行并显示如下图：

失败函数传入了一个error对象，用来查询判断错误代码和错误信息，如下面代码所示：

function onGPLFailure(err) {
    alert("Error: " + err.code + " - " + err.message);
}

可能的错误代码如下：

• GlobalizationError.UNKNOWN_ERROR
• GlobalizationError.FORMATTING_ERROR
• GlobalizationError.PARSING_ERROR
• GlobalizationError.PATTERN_ERROR

下面表格列出了所有Globalization API方法和传入方法的参数

方法	参数	返回
dateToString	JS Date值，options	表示基于options格式化的日期的字符串值和用户当前的语言设置
getCurrencyPattern	货币代码	描述货币格式的Pattern对象和一个基于用户当前语言设置的货币值部分
getDateNames	Options	一个月和天的名字的数组，有长和短的版本，要看options和用户当前语言设置
getDatePattern	Options	描述基于用户当前语言设置的日期格式的Pattern对象
getFirstDayOfWeek		表示基于当前用户语言设置的周第一天数值
getLocaleName		表示用户当前位置的字符串，用ISO 3166国家代码表示
getNumberPattern	Options	描述基于用户当前语言设置的数值的格式的Pattern对象
getPreferredLanaguage		用户选用语言的字符串表示，使用ISO 639-1 双字母代码
isDayLightSavingsTie	Date	表示白天可用时间是否有效的字符值
numberToString	Number, Options	表示使用options和用户偏好格式化的数值的字符值
stringToDate	String, Options	把一个日期字符串解析成若干基于options和用户偏好的单个部分/td>
stringToNumber	String, Options	把一个数值字符串解析成基于options和用户偏好的单个部分

从表中可以看到一些方法接受属性对象，让开发者控制方法操作。如，使用dateToString方法把日期对象转换成字符串，应用中可能会这么用：

var d = new Date();
navigator.globalization.dateToString(d, onSuccess, onFailure);

onSuccess函数在日期转换完成后调用，传入一个可查询到显示结果的对象，如：

function onSuccess(res) {
    alert("Result: " + res.value);
}    

dateToString方法支持options参数，开发者用它改变输出格式，如：

var d = new Date();
var options = {
    formateLength: 'short',
    selector: 'date'
};
navigator.globalization.dateToString(d, onSuccess, onFailure, options);

上面例子中options对象定义了formateLength和selector属性，用来控制结果字符串长度和是否包括日期和(或)时间值。它返回了每个日期部分各自的属性对象：
{
"month":7,
"second":0,
"millisecond":0,
"day":31,
"year":2013,
"hour":10,
"minute":47
}

---

使用Contacts应用工作

Cordova Contacts API让开发者构建和通讯录或联系人应用交互的应用，它基于W3C Contacts API。它用于构建这样的应用：读取联系人列表并在应用中使用联系人数据，或使用应用数据向联系人列表中写新的联系人。

首先要安装Contacts插件：

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

因为每个移动平台上联系人的功能都不同，Contacts API使用起来有些不一样，像Android设备上使用的联系人一些字段与在iOS上不一样。另外Contacts的实现与其他API还有些不同。

Contacts API有两个方法和一个contacts对象，方法用来创建新的contacts对象和在设备上查找联系人，contacts对象表示设备上的联系人。

创建联系人使用API的create方法，如下：

var newContact = navigator.contacts.create();

和之前的API方法不一样，这个方法是同步的，没有提供success和failure回调函数。它并没有在设备联系人应用中创建联系人，只是创建了一个新的contact对象，上面代码创建了一个空的contact对象，直到使用save方法才会保存到联系人应用。

也可以在创建时填充contact对象，如下在对象中填充了一个displayName属性：

var newContact = navigator.contacts.create({"displayName": "Zhang San"});

contact对象包括以下属性：

• addresses: 包括联系人所有不同地址的数组。
• birthday: 联系人的生日。
• categories: 包括所有与联系人相关的用户定义的分类的数组。
• displayName: 联系人的显示名。
• emails: 包括联系人所有邮件地址的数组。
• id: 联系人的全局唯一标识符。
• ims: 包括联系人所有的即时消息地址的数组。
• nickname: 联系人的昵称。
• note: 和联系人相关的记录。
• organizations: 包括和联系人相关的所有的组织的数组。
• phoneNumbers: 包括所有与联系人相关的所有电话号码的数组。
• photos: 包括所有与联系人相关的图像的数组。
• urls: 包括所有与联系人相关的网页的数组。

一些属性是其他属性的数组。如联系人常常会有两个或更多的邮件地址。

可以像上例一样在创建对象时填充contact对象，或者在创建后再填充对象的属性。如下：

var newContact = navigator.contacts.create();

var fullName = "Zhang San";
newContact.displayName = fullName;
newContact.nickName = "GouSheng";

var tmpName = new ContactName();
tmpName.givenName = "San";
tmpName.familyName = "Zhang";     
tmpName.formatted = fullName;

newContact.name = tmpName;

上面代码创建了一个新的contact对象，然后用值填充。其中填充了一个ContactName对象(Contacts API中定义的)，然后添加到newContact对象。ContactName对象包括以下属性：

• familyName
• formatted
• givenName
• honorificsSuffix
• middleName

有许多不同的可以添加到联系人记录的对象类型和对象数组。关于支持的选项详情请参考API文档。

设定好contact对象属性后，必须调用save方法把改动添加到真实的联系人记录中：

newContact.save(onSuccess, onError);

和其他API一样save方法接受成功和失败函数作为参数，失败函数传入了一个error对象识别错误原因并做出相应的回应，如下：

function onError(err) {
    console.log("Error Saving Contact: " + err.code);
}     

如果要操作现有的联系人，可以用API的find方法定位记录，如下：

navigator.contacts.find(contactFields, onSuccess, onError, options);

上面的代码的contactFields对象表示字段名数组，如下:

var contactFileds = ["displayName", "name", "phoneNumbers", "emails", "address"];

find方法定义了在查找结果中返回哪些字段值。options对象定义了查找如何执行的参数，如下：

var options = {filter: "Zhang", multiple: true};

fileter属性用来向find方法提供用到的查找字符串。multiple属性是一个布尔值控制是返回一个或多个联系人。

下面代码完整展示了如何调用find方法，传入联系人字段列表和查找选项。在onSuccess函数中，代码把联系人详细信息写到控制台上：

function findContact() {
    var contactFileds = ["displayName", "name", "phoneNumbers", "emails", "address"];
    var contactOptions = {
        filter: "Zhang",
        multiple: true
    };
    navigator.contacts.find(contactFields, onSuccess, onError, contactOptions);
}                

function onSuccess(contacts) {
    for (var i = 0; i < contacts.length; i++) {
        console.log("Contact[" + i + "]: " + JSON.stringify(contacts[i]));
    }
}

下面是上面代码在我的设备上查找结果返回的JSON数据块：

其中可以看到电话号码是如何组织的：

每个电话号码有一个type、value、ID和推荐状态值。ID在把电话号码添加到联系人记录时自动创建。不同移动平台管理联系人数据也不一样，确定在每个平台上都测试联系人格式。

当调用find方法并返回了一个contact对象时，就可以改变对象属性并用save方法把改动写回联系人应用。如果要删除联系人，首先要找到联系人对象的句柄并调用remove：

foundContact.remove(onSuccess, onFailure);

关于Contacts API还有很多，请参考Cordova文档获得更多信息。

---

播放/记录媒体文件

Cordova API包括一个Media API让应用能记录或播放媒体文件。用它可以在手机后台播放音频文件或玩桌面视频游戏。

首先要安装插件：

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

Media API像其他API一样也是异步的，但触发回调函数的有些不一样。要用API，应用要创建一个Media对象，如下：

var mediaObj = new Media(srcFile, onSuccess, onError, onStatus);

这样创建了一个mediaObj对象，它指向一个由srcFile参数指定的媒体文件。应用还没有打开或连接文件，只是创建了一个引用文件的对象。

onSuccess和onFailure函数并不像以前的一样触发。上面代码中的回调函数实际上在media对象创建后以下方法调用时调用：

• getCurrentPosition
• getDuration
• pause
• play
• release
• seekTo
• setVolume
• startRecord
• stop
• stopRecord

比如要播放一个叫soundtrack.mp3的媒体文件，代码可以这么写：

srcFile = 'soundtrack.mp3';
var mediaObj = new Media(srcFile, onSuccess, onError, onStatus);
mediaObj.play();

function onSuccess() {
    console.log("Media: Success");
}               

function onError(error) {
    alert('Media Error: ' + error.code + ': ' + error.message);
}

function onStatus(statCode) {
    console.log("Media status: " + statCode);
}

停止播放只需调用mediaObj.stop();上面代码的onStatus函数传递了一个状态代码参数让应用理解媒体播放或记录的状态。可能的状态代码如下：

• Media.MEDIA_NONE
• Media.MEDIA_STARTING
• Media.MEDIA_RUNNING
• Media.MEDIA_PAUSED
• Media.MEDIA_STOPPED

使用Media API中所有的方法和回调函数可以构建一个完整的媒体播放应用，或者不用任何UI加载和播放音频文件。API还为开发者提供了可扩展性。

Cordova应用存储打包的媒体文件的位置因不同的移动设备平台而不同。如Android中位于/android_asset文件夹中。

---

InAppBrowser

InAppBrowser的版本和Cordova API的版本更接近，允许在在单独的窗口中加载网页。例如要向应用用户展示其他网页。当然可以很容易地在应用中加载网页内容并管理，但有时候需要不同的用户体验，InAppBrowser加载网页内容，应用用户可以更方便的直接返回到主应用。

使用前首先安装InAppBrowser插件：

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

加载内容

使用如下代码在窗口打开网页内容：

var ref = window.open('http://www.segmentFault.com', '_blank', 'location=yes');

上面代码打开一个网址并返回一个表示浏览器窗口的对象。稍后可以用这个对象和浏览器窗口交互。也可以创建一个浏览器窗口但不显示，如下：

var ref = window.open('http://www.segmentFault.com', '_blank', 'hidden=yes');

之后要想显示浏览器窗口，如下:

ref.show();

window.open方法的参数中，_blank告诉应用在自已的窗口中打开内容；也可以用_self，即在当前窗口中打开页面，_system在默认的网页浏览器打开内容。使用_self的问题是加载的网页替换了当前应用的网页内容，对于用户没法回退。

'location=yes'告诉InAppBrowser在浏览器窗口中显示页面地址。还有几个其他选项在加载页面时使用，这些选项因移动设备平台而异，更多信息请参考Cordova文档。调用的结果如下图，用户可以点击"X"按钮返回原应用：

要关闭页面地址栏，找开页面时使用如下代码：

var ref = window.open('http://www.segmentFault.com', '_blank', 'location=no');

也可以加载本地内容，如下，在项目的www文件夹中有一个叫help.html的文件：

var ref = window.open('help.html', '_blank');

想关闭网页只需要调用close方法：

ref.close();

浏览器窗口事件

应用在很多场景下需要知道在InAppBrowser窗口中进行的情况。为此InAppBrowser API在窗口生命周期的不同时期触发不同事件。支持的事件有：

• loadstart: 在InAppBrowser开始加载一个URL时触发。
• loadstop: 在InAppBrowser完成加载URL时触发。
• loaderror: 在InAppBrowser加载URL遇到错误时触发。
• exit: 在InAppBrowser窗口被关闭时触发(由用户或应用调用close方法)。

以下是一些代码段，用InAppBrowser打开一个本地HTML文件，然后为每个窗口事件定义了事件监听器：

var ref = window.open('help.html', '_blank');
ref.addEventListener('loadstart', onEvent);
ref.addEventListener('loadstop', onEvent);
ref.addEventListener('loaderror', onLoadError);
ref.addEventListener('exit', onEvent);

除了错误事件其他都用一个回调函数，是因为此时回调函数都传入了一个event对象，它描述了触发的事件，如下：

function onEvent(event) {
    console.log('Type: ' + event.type);
    console.log('URL: ' + event.url);

    // Do something based on event.type
}                   

开发者可以查询event.type并为特定的事件并做适当的处理。

错误发生时，错误回调函数传入了一个包括代码和消息属性的对象，如下。开发者之后查询event.code，并显示一个恰当的错误消息或者执行恰当的恢复步骤。

function onLoadError(event) {
    console.log('onLoadError: ' + event.code + '-' + event.message));
}

执行脚本

只是加载网页是不够的，可能会需要修改内容或执行页面的一些js脚本。InAppBrowser有让应用在窗口执行js代码的方法executeScript，如下：

ref.executeScript(scriptInfo, onSucess);

scriptInfo参数定义了执行的js代码和代码位置，可以直接传入方法或从文件加载。要执行特定的js代码，需要以code和一个包括字符串的值组成的属性传入一个js对象，其中字符串包括要执行的js代码，如下：

{code: "$('#heading').replaceWith('<h2>This is some injected text</h2>');"}

上面代码使用jQuery的replaceWith函数替换页面的一些内容。

可以在页面加载完成后执行js代码，一般是在页面加载后执行js脚本的位置添加对executeScript的调用，如在loadstop事件监听器中，如下：

var ref = window.open('help.html', '_blank', 'loaction=no');
ref.addEventListener('loadstop', function() {
    ref.executeScript({
        code: "$(#heading').replaceWith('<h2>This is some injected text</h2>');" 
    }, onSuccess);
});                

除了直接传入js代码，还可以把代码保存到文件中并发文件名通过scriptInfo参数传给executeScript，如下：

{ file: "myscript.js" }

执行结果是一样的，只是示例代码的js代码来源改变了。

插入CSS

和在InAppBrowser中执行js脚本一样，也可以使用方法向窗口中插入CSS。比如像网页来源于外部，想要改变它的样式来匹配应用的其他部分。调用InAppBrowser的insertCSS方法，传入CSS或CSS文件的引用，如下：

ref.insertCSS(cssInfo, onSuccess);        

cssInfo参数定义了插入的CSS脚本和它的位置，直接传入或从文件加载。要传入CSS脚本，要使用js对象，它包括code和一个值，值由表示CSS脚本的字符串构成，如下：

{code : "body {background-color:black; color:white}"}

不能在页面加载完成之前插入CSS，如下面代码在loadstop事件监听器处理：

var ref = window.open('help.html', '_blank', 'location=no');
ref.addEventListener('loadstop', function() {
    ref.insertCSS({
        code: "body {background:black; color:white}"
    }, onSuccess);
});        

也可以把CSS保存到文件，把文件名通过cssInfo参数传给insertCSS方法，如下：

{file: "mystuff.css"}

---

闪屏

Cordova提供了Splashscreen API能够用来在Cordova应用启动时显示自定义的闪屏。使用前首先安装插件：

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

要在创建适当的闪屏图像文件用于支持不同设备平台，还有各操作系统中各种表单元素。还有些要你为每个移动设备平台做手动设置，即修改Cordova容器代码。

如果有合适的图像并添加到Cordova和平台项目中，可以用如下代码展示和隐藏应用闪屏：

function showSplash() {
    navigator.splashscreen.show();
    setTimeout(hideSplash, 2000);
}            

function hideSplash() {
    navigator.splashscreen.hide();
}

上面例子中showSpash函数显示了闪屏，然后设置一个定时器让闪屏2秒后隐藏。

---

关于API的部分就先介绍到这里了，本篇内容比较多。下一篇介绍如何创建插件，再之后以一个综合示例结束。

本篇代码链接：http://yunpan.cn/cctIXAtxdv5GC （提取码：25c1）