跨平台的 PhoneGap 应用


第11章 跨平台的 PhoneGap 应用 11.1 PhoneGap 概述 11.1.1 认识 PhoneGap PhoneGap 是一款基于 HTML5 标准的跨平台开源手机应用开发框架。它允许用户通过 Web 技术就可以访问移动设备的本地应用、API 以及应用程序库等。 PhoneGap 将移动设备提供的 API 进行了抽象和简化,提供了一系列丰富的 API 供开发者 调用,只要开发者会编写 HTML 和 JavaScript 语言,就可以利用 PhoneGap 提供的 API 去调用 移动设备内置的各种功能,这样就可以让开发者们制作出各种手机平台上运行的应用程序。 PhoneGap 的官方网站是 http://www.phonegap.com,如图 11-1 所示。我们可以通过官方 网站获取关于 PhoneGap 的最新信息、版本以及 API 文档。 图 11-1 PhoneGap 官方网站 11.1.2 功能特性 PhoneGap 是一套非常优秀的手机应用程序框架,它包括有以下一些特性: 开源、免费。 跨平台框架,目前支持多种移动设备平台,包括:iOS、Android、BlackBerry、WebOS、 Symbian、Windows Phone、Bada 等。 基于 HTML5 标准的手机应用框架,支持 HTML5、CSS3、JavaScript 等 Web 技术。 真正实现了只写一次,云端编译。 PhoneGap 提供非常丰富的 API,它们包括:Accelerometer 移动感应器、Camera 摄像头、 Compass 设备指向、Contacts 通讯录、Device 设备参数、File 文件系统、GPS 感应器、Media 多媒体、Network 网络、Storage 存储以及 Notification 等。 API 的具体用法将会在后续章节中详细介绍。 11.2 搭建 PhoneGap 开发环境 11.2.1 如何在 Android 平台下搭建 PhoneGap 开发环境 搭建 Android 平台的 PhoneGap 应用程序之前,首先要准备一些必须的工具和 SDK,包括: Eclipse 3.4 版本以上的开发环境,该开发环境可以在 Eclipse 官方网站下载,地址是: http://www.eclipse.org/downloads/。 Android SDK 包,可以在 Android 官方网站下载 SDK 开发包,下载地址是:http://de veloper.android.com/sdk/index.html ADT Plugin for Eclipse 插件, PhoneGap 套件包 由于本书不是主要讲述如何在 Eclipse 部署 Android 开发环境,因此本节将不作 Android 部署的介绍,主要讲解如何在已有的 Android 开发环境下如何使用 PhoneGap。 1. 创建项目 (1) 首先打开 Eclipse。 (2) 然后点击“new”–>“Android Project”,创建一个新的 Adnroid 项目。如图 11-2 所 示。 (3) 在“ Project name”输入 Adnroid 项目的名称。在“Build Target”下的列表中选择“Target Name”名称为“Android 2.2”的选项。 (4) 在“Package Name”中指定项目的类包路径,如 com.phonegap.helloworld。 (5) 点击“finish”按钮完成项目的创建后,便进入项目的开发。 图 11-2 创建 Android 项目的界面(图片来源于官方网站) 2. 开发 PhoneGap 应用 (1) 在新建 Android 项目中的根目录下,创建两个新的文件目录:/libs 和/assets/www。 (2) 复制从网络上下载的 PhoneGap.js 文件到/assets/www 目录下。 (3) 复制从网络上下载的 PhoneGap.jar 文件到/libs 目录下。 (4) 在 com.phonegap.helloworld 类包下创建一个 class 类文件 app.java。 (5) 在 app.java 中将继承 Activity 类更改为 DroidGap 类,同时将 app.java 类内的 setCont entView()方法替换成 super.loadUrl(“file:///android_asset/www/index.html”); (6) 最后将 phoneGap 类包导入,如“import com.phongap.*;”。删除“import android. app.Activity”的类包。其效果如图 11-3 所示。 (7) 如果在使用 phonegap.jar 类库包时发现 java 中找不到类库,可以在项目的 build Pat hs 中导入该类库。地址在右击项目选择”properties”->”Java Build Path”->”Libraries”。 然后点击“Add JARs”将项目的 libs 目录下的 phonegap.jar 导入即可。 图 11-3 app.java 类文件图(图片来源于官方网站) 3. 修改配置 (1) 用文本方式打开项目根目录下的 AndroidManifest.xml。 (2) 然后将以下代码 11-1 复制到该 XML 文件中。 代码 11-1 AndroidManifest.xml 部分代码 (3) 接着增加一个 activity 配置文件代码,代码如下 11-2。 代码 11-2 增加 activity 文件 (4) 最后 AndroidManifest.xml 文件如下代码 11-3 所示。 代码 11-3 AndroidManifest.xml 配置文件代码 4. hello World 在 www 目录下新建 index.html,如下代码 11-4 所示: 代码 11-4 index.html 示例代码 PhoneGap 11.3.2 watchAcceleration 以一定时间间隔监控当前移动设备的移动加速度。 11.3.3 clearWatch 取消当前移动设备移动感应器的监视。 使用 watchAcceleration 和 clearWatch 方法的示例如代码 11-2 所示: 代码 11-6 使用 watchAcceleration 和 clearWatch 示例代码 Acceleration Example 2
11.4 Camera 相机 Camera 提供允许访问移动设备中摄像头拍摄的图片或从相册中获取的图片。 Camera 目前支持的平台包括 Android、iPhone、BlackBerry WebWorks (OS 5.0 and higher)。 camera.getPicture 方法通过配置不同的参数访问摄像头拍摄的图片或从相册中获取的图 片。通过该方法读取的相片会返回一个 base64 格式的字符串或一个 URI 路径的图片文件。利 用这两种不同的返回图像格式,我们可以通过 img 标签渲染当前页面的图像、也可以将 Base 64 格式的图像保存到如 LocalStorage 本地存储中、当然也可以将图片提交到远程服务器。 其语法如下: navigator.camera.getPicture(cameraSuccess,cameraError,[cameraOptio ns]); 第一个参数是读取相片成功后的回调函数;第二个参数是读取相片失败后的回调函数; 第三个参数为可选参数,用于传递各种读取配置属性。 那么如何读取返回 Base64 解码的图片呢?示例代码如下: navigator.camera.getPicture(onSuccess, onFail, { quality: 50 }); function onSuccess(imageData) { var image = document.getElementById('myImage'); image.src = "data:image/jpeg;base64," + imageData; } function onFail(message) { alert('Failed because: ' + message); } 通过 imageData 返回的图像 base64 编码字符串,需要指定前缀字符串“data:image/jp eg;base64,”以表示该图片是采用 base64 编码的图片。 采用返回 URI 路径方式的图片,其显示的代码和普通的 URI 地址基本一样,示例代码如 下: navigator.camera.getPicture(onSuccess, onFail, { quality: 50, destinationType: Camera.DestinationType.FILE_URI }); function onSuccess(imageURI) { var image = document.getElementById('myImage'); image.src = imageURI; } function onFail(message) { alert('Failed because: ' + message); } 在上述的例子中,onSuccess 方法返回的是一个 URI 地址,我们只需要在代码中通过直 接赋值到 image.src 中就能读取并显示该图片。 上述代码中的第三个参数传递了两个参数,实际上 Camera 提供非常多的配置参数,它们 分别是: quality 图片的质量,其值的范围是 0 至 100。 destinationType 定义返回的图片格式,Base64 还是 URI。 设置 Camera.DestinationType.DATA_URL 时,返回的格式是 Base64 格式字符串,DATA_ URL 的实际值是 0。当设置 Camera.DestinationType. FILE_URI 时,返回的格式是 URI 路径, FILE_URI 的实际值是 1。如没有指定该参数时,默认是 DATA_URL。 sourceType 指定图片的来源。当设置 Camera.PictureSourceType. PHOTOLIBRARY 时,指定从图像数 据库获取;当设置 Camera.PictureSourceType.CAMERA 时,指定从相机中获取;当设置 Came ra.PictureSourceType. SAVEDPHOTOALBUM 时,指定从已经保存在相册中获取。 allowEdit 指定选中图片之前是否允许编辑图片。 encodingType 指定返回的图像格式。当设置 Camera.EncodingType.JPEG 时,指定返回 jpeg 格式的图 像;当设置 Camera.EncodingType.PNG 时,指定返回 png 格式的图像。 targetWidth 指定图像的像素宽度。 targetHeight 指定图像的像素高度。 11.5 Capture 采集 Capture 主要提供移动的音频、视频、图像采集功能的访问。目前 Capture 支持的平台包 括 Android、iPhone、BlackBerry WebWorks (OS 5.0 and higher)。 Capture 对象可通过 navigator.device 对象获得,如 navigator.device.capture,因此其作用 域是全局范围。有了这个 Capture 对象,我们就能对手机中的音频、视频以及图像进行任何 采集操作。 11.5.1 音频采集 captureAudio 方法允许通过移动设备的音频录制应用程序采集录制的音频数据。该操 作允许设备用户在一个会话中同时采集多个音频数据。 音频采集功能语法如下: navigator.device.capture.captureAudio(CaptureCB captureSuccess,Cap tureErrorCB captureError,[CaptureAudioOptions options]); captureSuccess 参数为音频采集结束后的回调函数;captureError 参数为音频采集 过程中中断后的回调函数;CaptureAudioOptions 参数主要传递相关属性配置。 CaptureAudioOptions 参数的配置属性可以传入以下三个属性: limit 设置在一次采集过程中允许录制音频片段数量的最大值。该设置必须是大于或等于 1, 默认值为 1。 duration 设置允许录制音频片段的最长时间,单位为秒。该参数目前不支持 Android、iOS、 Black Berry 平台。 mode 设置选择音频的格式。使用 captureAudio 方法采集音频片段时,这个模式必须设定 为 capture.supportedAudioModes。该参数目前不支持 Android、iOS、Black Ber ry 平台。Android 和 Black Berry 平台使用 AMR 格式进行音频录制编码;iOS 平台使用 WAV 格式进行音频录制编码。 如何使用 captureAudio 方法采集音频片段?示例如下代码 11-3: 代码 11-7 captureAudio 示例 Capture Example 1 11.5.2 图像采集 captureImage 方法允许通过移动设备的摄像头应用程序采集生成的图像文件信息。该方 法允许设备用户在一个会话中同时采集多个图像。 captureImage 方法采集图像语法如下: navigator.device.capture.captureImage(CaptureCB captureSuccess,Cap tureErrorCB captureError,[CaptureImageOptions options]); CaptureCB 参数为采集成功后的回调函数;CaptureErrorCB 参数为采集过程中中断 时的回调函数;CaptureImageOption 可选参数主要传递相关属性配置。 CaptureImageOptions 参数的配置属性允许传入以下两个属性: limit 设置在一个采集过程中允许选择图像数量的最大值。该设置必须是大于或等于 1,默认 值是 1。目前只有 Android 和 Black Berry 平台支持该属性,而 iOS 平台只允许采集一 幅图像。 mode 设置图像的格式。使用 captureImage 方法采集图像时,这个模式必须设定为 captur e.supportedImageModes。该属性目前不支持 Android、iOS、Black Berry 平台。 不过设备用户可以修改图像的大小,默认保存的图像格式是 JPEG。 captureImage 方法的使用方法与 captureAudio 方法几乎一样,示例如下代码 11-4 所示: 代码 11-8 captureImage 示例代码 Capture Example 2 11.5.3 视频采集 captureVideo 方法允许通过移动设备的视频录制应用程序采集录制的视频数据。该方法 允许设备用户在一个会话中同时采集多个视频数据。 navigator.device.capture.captureVideo(CaptureCB captureSuccess,Cap tureErrorCB captureError,[CaptureVideoOptions options]); CaptureCB 参数为采集成功后的回调函数;CaptureErrorCB 参数为采集过程中中断 后的回调函数;CaptureVideoOptions 可选参数主要传递相关属性配置。 CaptureAudioOptions 参数的配置属性允许传入以下三个属性: limit 设置在一次采集过程中允许录制视频片段数量最大值。该设置必须是大于或等于 1,默 认值是 1。该属性支持 Android 和 BlackBerry 平台;iOS 平台不支持该属性,每次采集 都只允许采集一个视频文件。 duration 设置允许录制视频片段的长度,单位是秒。该参数目前不支持 Android、iOS、Black Berry 平台。因此无法通过 duration 属性设置视频片段的长度。 mode 设置选择视频的大小和格式。使用 captureVideo 方法采集视频时,这个模式必须设 定为 capture.supportedAudioModes。但是,该参数目前不支持 Android、iOS、Bl ack Berry 平台。 Android 平台和 Black Berry 平台录制的视频格式默认是 3GPP 格式。而 iOS 平台 录制的视频格式默认是 MOV 格式。 captureVideo 方法的使用方法与 captureAudio 方法几乎一样,示例如下代码 11-4 所 示: 代码 11-9 captureVideo 示例代码 Capture Example 3 11.5.4 采集文件 MediaFile Capture 采集多媒体数据后,在回调函数中会传递一个 MediaFile 对象到函数中。mediaFile 对象包含有以下属性:  name:采集文件的文件名。  fullPath:包含文件名的路径。  type:MIME 类型  lastModifiesDate:文件最后修改的日期时间  size:文件大小,单位为字节数。 通过 mediaFile.getFormatData 方法可以获取到媒体文件的格式信息。语法如下: mediaFile.getFormatData( MediaFileDataSuccessCB successCallback, [MediaFileDataErrorCB errorCallback] ); MediaFileDataSuccessCB 参数为获取媒体文件成功时回调函数,该回调函数会传递一个 MediaFileData 对象。MediaFileDataErrorCB 参数为获取媒体文件失败时回调函数。 MediaFileData 对象提供的是文件格式信息。它包含有 5 种属性,分别是 codecs、bitrate、 height、width、duration。各种平台对此 5 种属性的支持程度都不一致,表 11-1 列出 MediaFi leData 对象属性支持情况一览。 表 11-1 MediaFileData 对象属性支持情况一览表 属性 iOS Android Black Berry codecs 不支持,属性值总是 null 不支持,属性值总是 null 不支持,属性值总是 null bitrate iOS4 版本仅支持音频,图 像和视频属性值为 0 不支持,属性值总是 0 不支持,属性值总是 0 height 支持图像和视频文件 支持图像和视频文件 不支持,属性值总是 0 width 支持图像和视频文件 支持图像和视频文件 不支持,属性值总是 0 duration 支持音频和视频文件 支持音频和视频文件 不支持,属性值总是 0 11.6 Compass 手机指向 PhoneGap 支持通过手机读取手机指向的方向。目前 Compass 功能支持的平台包括 Android、iPhone。 PhoneGap 提供三种方法用于读取和监视手机的指向: 11.6.1 getCurrentHeading 读取当前手机的方向。该方法提供三个参数,compassSuccess 参数是读取成功后回调 函数;compassError 参数是读取失败后回调函数;compassOptions 可选参数是配置参数 属性。具体语法如下: navigator.compass.getCurrentHeading(compassSuccess, compassError, compassOptions); getCurrentHeading 方法的示例如下代码 11-6 所示: 代码 11-10 getCurrentHeading 方法示例代码 Compass Example 1 11.6.2 watchHeading 以一定时间间隔监视移动设备的指向变化。该方法传入的参数和 getCurrentHeading 方法 一样,其语法如下: navigator.compass.watchHeading(compassSuccess, compassError, compa ssOptions); compassOptions 参数可以传递一个属性 frequency,用于指定 watchHeading 方 法间隔多少时间更新一次 Compass。其单位是毫秒,默认值是 100。 11.6.3 clearWatch 取消当前移动设备指向情况的监视。 使用 watchHeading 和 clearWatch 方法的示例如下代码 11-7 所示: 代码 11-11 watchHeading 和 clearWatch 方法的示例代码 Compass Example 2 11.7 Connection 网络状态 connection对象用于访问移动设备中的蜂窝或wifi连接的信息。目前支持的平台包括 iOS、 Android、BlackBerry WebWorks (OS 5.0 and higher)三种。 该 connection 对象是通过 navigator.network.connection 读取。 connection 对象的属性 type 是用于确定当前移动设备的网络连接状态和连接类型。例如 以下代码: function checkConnection() { var networkState = navigator.network.connection.type; var states = {}; states[Connection.UNKNOWN] = 'Unknown connection'; states[Connection.ETHERNET] = 'Ethernet connection'; states[Connection.WIFI] = 'WiFi connection'; states[Connection.CELL_2G] = 'Cell 2G connection'; states[Connection.CELL_3G] = 'Cell 3G connection'; states[Connection.CELL_4G] = 'Cell 4G connection'; states[Connection.NONE] = 'No network connection'; alert('Connection type: ' + states[networkState]); } 从上述代码中可以看到,connection 对象还有非常多的属性,他们包括:  UNKNOW:找不到网络连接  ETHERNET:有线连接  WIFI:WIFI 联网  CELL_2G:2G 网络  CELL_3G:3G 网络  CELL_4G:4G 网络  NONE:找不到网络 11.8 Contacts 通讯录 Contacts 对象提供访问和操作移动设备上的通讯录数据库。目前支持的平台包括 Android、 iPhone、BlackBerry WebWorks (OS 5.0 and higher)。 11.8.1 Contacts 对象 create 方法是用于创建并返回一个新 Contact 对象,创建后的新对象并不会被持久化到通 讯录数据库中,如需要持久化到数据库中需要调用到 Contact.save 方法,该方法将会在后续 介绍到。create 方法的语法如下: var contact = navigator.contacts.create(properties); create 方法创建新 Contact 对象的示例如下代码 11-8 所示: 代码 11-12 Contacts Example 1 11.8.2 Contact 查询 Contact.find 方法允许查询通讯录数据库,并返回一个或多个指定字段的 Contact 对象数组。其语法如下: navigator.service.contacts.find(contactFields, contactSuccess, contactError, contactFindOptions); contactFields 参数用于指定返回的 Contact 对象结果中的字段,如果该参数定义 了0长度的字段参数,contactSuccess返回的Contact数组结果中只存在id属性字段。 contactSuccess 参数是查询通讯录成功后的回调函数。find 方法返回的结果会传递 到 contactSuccess 参数的回调函数中。 contactError 参数是查询通讯录中断或发生错误时的回调函数。该参数是可选的。 contactFindOptions 参数是用于过滤搜索结果的选项。该参数是可选的。 使用 Contact.find 方法的示例如下代码 11-9 所示: 代码 11-13 Contact.find 方法示例代码 Contacts Example 1 11.8.3 Contact 属性 Contact 对象包含非常多的属性,表 11-2 列出这些属性列表清单。 表 11-2 Contact 对象属性列表 属性名 类型 描述 id 字符串 全局唯一标识 displayname 字符串 联系人显示名称 name ContactName 联系人姓名所有部分的对象 nickname 字符串 昵称 phoneNumbers ContactField 联系人所有联系电话 emails ContactField 联系人所有 email 地址 addresses ContactAddresse 联系人所有联系地址 ims ContactField 联系人所有 IM 地址 organizations ContactOrganization 联系人所属所有组织 birthday 日期类型 联系人生日 note 字符串 联系人备注 photos ContactField 联系人所有照片 categories ContactField 联系人所属的自定义分组类别 urls ContactField 联系人的所有网址 表 11-2 中的属性并不是所有平台都支持的,即使是相同的平台之间,不同的版本也有 不同程度的支持。 1. Android 平台的特殊性 在 Android 1.X 版本中,以下属性都不支持,他们都总是返回 null。  name  nickname  birthday  photos  categories  urls 在 Android 2.X 版本中,只有 categories 属性是不支持,其余属性都得到支持。 2. iOS 平台的特殊性 在 iOS 平台,部分属性的支持也有特殊情况。  displayName iOS 不支持该属性。除非没有给联系人制定 ContactName,否则 该字段返回值总是 null。如果没有指定 ContactName,系统会依次返回 composite name,nickname 或空字符串。  birthday 该对象存储的必须是一个 JavaScript 日期对象,其返回值同样也是 一个日期对象。  photos 返回的照片会存储到应用程序的临时目录中并同时返回指向该所有照片 的文件 URL。在应用程序退出后,临时目录也会被删除。  categories 不支持该属性,返回值为 null 3. BlackBerry 平台的特殊性 在 Black Berry 平台,也有部分属性是不支持的。  nickname 不支持该属性,返回值为 null  phoneNumber 部分支持,不同类型的的电话号码会被存储到 Black Berry 中的 不同字段。  emails 部分支持,前三个邮件地址会分别存储到 Black Berry 中的 email1、 email2、email3 三个字段。  addresses 部分支持,第一地址会被存储到 Black Berry 的 homeAddress 字 段,而第二个地址将被存储到 workAddress 字段。  ims 不支持该属性,返回值为 null  organizations 第一个组织的名称会被存储到 Black Berry 的 company字段, 而第一个组织的职务被存储到 title 字段。  photos 部分支持。只支持一个缩略图大小的图片。  categories 部分支持。只支持“Business”和“Personal”两种类别  urls 部分支持。第一个 url 地址会被存储到 Black Berry 的 webpage 字段。 11.8.4 ContactAddress addresses 属性对应的类型是一个 ContactAddress 类型,该类型存储着一个联系人的地 址。 一个 Contact 对象允许存储一个或多个 ContactAddress 地址。addresses 属性存储的是 ContactAddress[]数组。 一个 ContactAddress 对象,包含有 8 种属性,他们分别是:  pref:如果该值为 true,则 ContactAddress 包含用户的首选值。iOS、Android 和 BlackBerry 都不支持该属性,默认返回 false。  type:表示该地址对应的类型的字符串。Android 1.X 版本不支持该属性,Black Berry 只能存储一个“home”类型和一个“work”类型的地址。  formatted:完整的地址格式。iOS 不支持该属性。  streeAddress:完整的街道地址。Android 1.X 版本不支持该属性。  locality:城市或地区。Android 1.X 版本不支持该属性。  region:州或省份。Android 1.X 版本不支持该属性。  postalCode:邮政编码。Android 1.X 版本不支持该属性。  country:国家名称。Android 1.X 版本不支持该属性。 11.8.5 ContactField ContactField 对象是一个用于存储 Contact 联系人信息的通用字段类型。该类型主要存 储 emails、addresses、phone、numbers 和 urls 等属性。 ContactField 对象包含有 3 个属性:  type:指明当前字段类型,如“home”。  value:字段对应的值。  pref:ContactField 包含用户的首选值。目前 iOS、Android、Black Berry 三个平 台都不支持该属性。 11.8.6 ContactName ContactName 对象是用于存储 Contact 联系人信息的 name 属性。 ContactName 对象包含有 6 个属性,如表 11-3 所示。 表 11-3 ContactName 对象属性表 属性名 描述 支持情况 formatted 全名 Android 返回的是 honorificPrefix+ givenN ame+middleName+familyName+honorificSuff ix 的串联字符串结果。BlackBerry 则返回 fi rstName 和 lastName 两个字段串联的结果。 familyName 姓氏 BlackBerry 存储到 lastName 字段。 givenName 名字 BlackBerry 存储到 firstName 字段 middleName 中间名 BlackBerry 不支持该属性。 honorificPrefix 敬语前缀,如 Mr. BlackBerry 不支持该属性。 honorificSuffix 敬语后缀,如 Esq BlackBerry 不支持该属性。 11.8.7 ContactOrganization ContactOrganization 对象存储的是 Contact 对象中的组织信息。Contact 对象允许存储 一个或多个 ContactOrganization 对象。Contact 对象的 Organizations 属性存储的是一个 ContactOrganization[]数组。 ContactOrganization 对象包含有 5 个属性,如表 11-4 所示。 表 11-4 ContactOrganization 对象属性表 属性名 描述 支持情况 pref ContactOrganization 包 含用户的首选值设置 iOS、Android、BlackBerry 平台都不支持该 属性 type 地址对应的类型的字符串 Android 1.X、iOS、BlackBerry 平台不支持 该属性。 name 组织名称 iOS平台会被存储到kABPersonOrganizatio nProperty 字段中;BlackBerry 平台会将第 一个组织名称存储到 company 字段。 department 部门 BlackBerry 不支持该属性;iOS 平台会被存 储到 kABPersonDepartmentProperty 字段 中。 title 职务 Android 1.X 不支持该属性;BlackBerry 平 台会将第一个职务存储到 jobTitle 字段;i OS平台会被存储到kABPersonJobTitleProp erty 字段。 1. 方法 save save 方法是将一个新 Contact 联系人对象存储到通讯录数据库中。如果通讯录数据库中 已经存在该 Contact 对象的 id 属性,则更新该记录。 save 方法的示例如下代码 11-10。 代码 11-14 Contact 对象的 save 方法示例代码 Contacts Example clone clone 方法是返回一个新 Contact 对象。它是调用对象的深度拷贝,其新 Contact 对象 的 id 属性值设为 null。 clone 方法的示例如下代码 11-11。 代码 11-15 clone 方法示例代码 Contacts Example remove remove 方法是从通讯录数据库中删除联系人。若删除失败时,会触发 ContactError 对 象的错误处理回调函数。 remove 方法的示例如下代码 11-12。 代码 11-16 remove 方法的示例代码 Contacts Example 11.9 Device 设备信息 Device 对象描述手机硬件和软件的信息。 目前支持的平台包括:iOS、Android、BlackBerry 、BlackBerry WebWorks (OS 5.0 and higher)。 Device 对象封装了以下五种属性: device.name 获取手机设备的型号或产品的名称。例如以下代码: var name = window.device.name; 这个名称根据不同产品的不同版本而显示不同。iPhone 返回的是设备定制的名称而不是 型号,如“sankyu’s iphone”; Android 平台是获取产品的名称,如 Motorola Droid 手机返回 的名称为“voles”; BlackBerry 平台的 Bold 8900 手机,返回的名称为“8900”。 device.phonegap 获取运行在移动设备上的 phonegap 版本信息。例如以下代码: var version = window.device.phonegap; device.platform 获取移动设备的操作系统名称。例如以下代码: var platform = window.device.platform; device.uuid 获取移动设备 UUID。UUID 值是由设备生产商决定的。例如以下代码: var deviceId = window.device.uuid; iPhone 返回的是由多个硬件设备标识所生成的哈希值;Android 返回的是随机的 64 位整 数;BlackBerry 返回的是一个九位数的唯一整数。 device.version 读取手机设备的操作系统版本信息。例如以下代码: var version = window.device.version; iPhone iOS 3.2 返回的版本是“3.2”; BlackBerry 平台使用 OS 4.6 的 Bold 9000 返回的是 “4.6.0.282”; Android 平台的 Friyo 返回的版本是“2.2”。 现在通过一个完整的示例讲解如何使用 device 的属性,如示例代码 11-13。 代码 11-17 device 对象示例代码 Device Example 11.10 Events 事件 Events 事件是用于监听 PhoneGap 中各类的操作。 11.10.1 backbutton 当用户在 Android 平台的移动设备上点击返回按钮时触发该事件。backbutton 事件目前 只支持 Android 平台。 backbutton 事件的使用方法示例如下代码 11-14 所示。 代码 11-18 backbutton 事件示例代码 backbutton Example 11.10.2 deviceready 当 PhoneGap 被完全加载后触发该事件。当移动设备触发该事件后,用户就可以使用 PhoneGap 的各种函数 API。 deviceready 事件目前支持平台包括:iOS、Android、BlackBerry。 实际上此事件已经在之前的章节已经涉及到,监听 deviceready 事件的用法如下: document.addEventListener("deviceready", onDeviceReady, false); 在 BlackBerry 平台有一种特殊的情况,RIM 的 BrowserField(网页浏览器视图)不支持 自定义事件,所以不会触发 deviceready 事件。 我们可以通过一种解决方案,就是程序一直查询PhoneGap.available方法直到PhoneGap 完全加载完毕。如下代码所示: function onLoad() { // BlackBerry OS 4 浏览器不支持自定义事件。 // 因此通过手动方式等待,直到 PhoneGap 加载完毕。 var intervalID = window.setInterval( function() { if (PhoneGap.available) { window.clearInterval(intervalID); onDeviceReady(); } }, 500 ); } function onDeviceReady() { // 现在可以安全地调用 PhoneGap API } 上述代码中利用 window.setInterval 不断轮询判断 PhoneGap.available 方法是否可用。如 果可用就直接调用 onDeviceReady 方法并移除 intervalID。 11.10.3 menubutton 当用户在 Android 平台的移动设备上点击菜单按钮时触发该事件。menubutton 事件目前 只支持 Android 平台。 menubutton 事件的使用方法示例如代码 11-15 所示。 代码 11-19 menubutton 事件示例代码 menubutton event Example 11.10.4 pause 当 PhoneGap 应用程序被放到后台时触发该事件。pause 事件目前支持的平台包括:iOS、 Android、BlackBerry。 pause 事件的使用方法示例如下代码 11-16 所示。 代码 11-20 pause 事件示例代码 Device Example 11.10.5 resume 当 PhoneGap 应用程序被恢复到前台运行时触发该事件。resume 事件目前支持的平台包 括 iOS、Android、BlackBerry。 resume 事件的使用方法示例如下代码 11-17 所示。 代码 11-21 resume 事件示例代码 Device Example 11.10.6 searchbutton 当用户在 Andriod 平台的设备上点击搜索按钮时触发该事件。searchbutton 事件目前只支 持 Android 平台。 searchbutton 事件的使用方法示例如下代码 11-8 所示。 代码 11-22 searchbutton 事件的示例代码 searchbutton event Example 11.10.7 online 当 PhoneGap 应用程序的网络连接改变为 online 时触发该事件。 online 事件的使用方法示例如下代码 11-19 所示。 代码 11-23 online event Example 11.10.8 offline 当 PhoneGap 应用程序的网络连接改变为 offline 时触发该事件。 offline 事件的使用方法示例如下代码 11-20 所示。 代码 11-24 offline 事件的示例代码 offline event Example 11.11 File 文件 File 对象是用于读取、写入和浏览移动设备文件系统的 API。 11.11.1 DirectoryEntry DirectoryEntry 对象表示文件系统中的一个目录。目前支持的平台包括:iOS、Android、 BlackBerry。 表 11-5 是 DirectoryEntry 对象可以使用的属性列表。 表 11-5 DirectoryEntry 对象的属性表 属性名 类型 描述 isFile boolean 总是 false。 isDirectory boolean 总是 true。 name DOMString 目录名称(不包含路径)。 fullPath DOMString DirectoryEntry 的完整路径。 PhoneGap 的 DirectoryEntry 对象提供非常丰富的方法用于操作目录相关的操作,如表 11 -6。 方法 描述 getMetadata 获取目录的元数据。 moveTo 移动一个目录到文件系统中不同位置。 copyTo 拷贝一个目录到文件系统中不同位置。 toURI 返回一个可以定位目录的 URI remove 删除一个目录,被删除的目录必须是空的。 getParent 查找父级目录。 createReader 创建一个可以从目录中读取条目的的新 DirectoryReader 对象。 getDirectory 创建或查找一个目录。 getFile 创建或查找一个文件。 removeRecursively 删除一个目录和它的所有内容。 1. getMetadata 方法 获取目录得元数据。其使用方法如下: getMetadata(successCallback,errorCallback); 其中 successCallback 参数是获取元数据成功后的回调函数,回调函数会传递一个 Metad ata 对象;errorCallback 参数是获取元数据失败时的回调函数,该回调函数会传递一个 FileErr or 对象。示例代码如下: entry.getMetadata(function(metadata){ console.log("directory name is " + metadata.name); },function(error){ alert("getMetadata error code is " + error.code); }); 2. moveTo 方法 移动一个目录到文件系统中不同位置。其使用方法如下: moveTo(parent,newName,successCallback,errorCallback); 其中 parent 参数是移动目标父级目录,参数类型是 DirectoryEntry;newName 参数是新 目录的名称,如没有指定,默认为当前名字;successCallback 参数是移动目录成功后的回调 函数,回调函数会传递一个 Metadata 对象;errorCallback 参数是移动目录失败时的回调函数, 回调函数会传递一个 FileError 对象。示例代码如下: function moveToEntry(){ var parent = document.getElementById("panret").value; var newname = document.getElementById("newname").value; parentEntry = new DirectoryEntry({fullPath:panret}); entry.moveTo(parentEntry,newname,function(entry){ console.log("new path is " + entry.fullPath); },function(error){ alert("moveTo error code is " + error.code); }); } 调用 moveTo 方法进行目录得移动时,以下这些情况会发生错误并运行回调函数 errorCal lback。  移动目录到自身目录或其目录的所有子目录;  将一个目录移动到它的父目录时没有提供和当前目录不同的名称;  移动目录到一个文件所占用的路径;  移动目录到一个非空目录所占用的路径。 3. copyTo 方法 拷贝一个目录到文件系统中不同位置。其使用方法是: copyTo(parent,newName,successCallback,errorCallback); parent 参数是复制目录的目标父级目录,参数类型是 DirectoryEntry;newName 参数是复 制的新目录名称,如没有指定,默认为当前名字;successCallback 参数是复制目录成功后的 回调函数,回调函数会传递一个 Metadata 对象到函数内部;errorCallback 参数是移动目录失 败时的回调函数,回调函数会传递一个 FileError 对象到函数内部。示例代码如下: function copyToEntry(){ var parent = document.getElementById("panret").value; var newname = document.getElementById("newname").value; parentEntry = new DirectoryEntry({fullPath:panret}); entry.copyTo(parentEntry,newname,function(entry){ console.log("new path is " + entry.fullPath); },function(error){ alert("copyTo error code is " + error.code); }); } 目录的复制总是递归操作,也就是说会将目录内的所有内容一并拷贝。调用 copyTo 方法 拷贝目录时,以下情况会发生错误并运行回调函数 errorCallback。  拷贝一个目录到其深度的子目录中;  将一个目录拷贝到它的父目录时没有提供和当前目录不同的名称; 4. remove 方法 删除一个目录,被删除的目录必须是空的。其使用方法如下: remove(successCallback,errorCallback); successCallback 参数是删除目录成功后的回调函数,该回调函数没有参数;errorCallback 参数是删除目录发生错误时的回调函数,该回调函数会传递一个 FileError 对象到函数内部。 示例代码如下: entry.remove(function(){ console.log("remove success"); },function(error){ alert("remove method error, code is " + error.code); }) 删除目录时在以下情况会发生错误并运行回调函数 errorCallback。  删除一个非空的目录;  删除文件系统的根目录。 5. getParent 方法 查找父级目录。其使用方法如下: getParent(successCallback,errorCallback); successCallback 参数是查找父级目录成功后的回调函数,该回调函数返回一个父级目录 D irectoryEntry 对象的参数;errorCallback 参数是查找父级目录发生错误时的回调函数,该回调 函数会传递一个 FileError 对象到函数内部。示例代码如下: entry.getParent(function(parentEntry){ console.log("parent directory name is" + parentEntry.name); },function(error){ alert("failed getParent method,code is" + error.code); }); 6. createReader 方法 创建一个可以从目录中读取条目的新 DirectoryReader 对象。其示例代码如下: var directoryReader = entry.createReader(); DirectoryReader 对象是包含目录中所有的文件和子目录的列表对象。DirectoryReader 对 象含有一个方法 readEntries,该方法用于读取目录中的所有条目。 它支持的平台包括:iOS、Android、BlackBerry。 其使用方法如下: directoryReader.readEntries(successCallback,errorCallback); successCallback 参数是读取条目成功时的回调函数,该函数含有一个参数,其参数是一 个包括 FileEntry 和 DirectoryEntry 的对象数组。ErrorCallback 参数是读取发生错误时的回调函 数,该函数含有一个 FileError 对象的参数。示例代码如下: var directoryReader = entry.createReader(); directoryReader.readEntries(function(entries){ for(var i=0;i FileWriter Object Example 该例子首先在文件系统的根目录下创建 readme.txt 文件,然后在其返回的 gotFileEnt ry 函数中调用 createWriter 方法创建 FileWriter 对象,并在创建成功后的回调函数 内执行文件操作。 在 gotFileWriter 函数内部首先将一个空白的 readme.txt 文件写入“fileWrite r writer text example”字符串数据,后然通过调用方法 truncate 方法,将字符串 截取前 22 个字符。 接着调用 seek 方法将文件的指针指向第 10 个字符中,也即字符‘r’。最后在字符‘r’ 的位置插入一段字符“Object”。最终 readme.txt 文件内的字符串内容就是“fileWri ter object writer text example”。 11.11.7 FileError FileError 对象是所有 File API 的错误回调函数的唯一参数对象。开发者可以通过该对象返 回的错误代码,识别出各种错误类型。 该对象只有一个属性,它就是 code 属性。该属性会返回一个常量的错误代码。根据这个 错误代码就可以实现各种错误的提醒。 FileError 对象的常量非常多,如表 11-14。 表 11-14 FileError 对象常量一览表 方法 描述 FileError.NOT_FOUND_ERR 没有找到对应的文件或目录。 FileError.SECURITY_ERR 安全错误。如当前文件在 Web 应用中被访问是 不安全的。 FileError.ABORT_ERR 中止错误。 FileError.NOT_READABLE_ERR 不能读取文件或目录。如读取该文件时,已经 被另一个应用获取该文件的引用并使用了并发 锁。 FileError.ENCODING_ERR 编码错误。 FileError.NO_MODIFICATION_ALLOWED_ERR 拒绝修改。如当试图尝试修改一个文件系统状 态是不能修改的文件或目录。 FileError.INVALID_STATE_ERR 无效状态。 FileError.SYNTAX_ERR 语法错误。 FileError.INVALID_MODIFICATION_ERR 非法的修改请求。如移动文件或目录到其目录 时没有提供和当前名称不同的名称。 FileError.QUOTA_EXCEEDED_ERR 超过配额错误。 FileError.TYPE_MISMATCH_ERR 类型不匹配。 FileError.PATH_EXISTS_ERR 路径已存在。如当尝试创建已经存在的文件或 目录时。 11.11.8 FileTransfer 1. FileTransfer FileTransfer 是一个提供上传文件到服务器的对象。 它提供一种将文件上传到服务器的方法,通过 http的post请求(支持 http和https协议), 可以传递一个由 FileUploadOptions 对象设定的可选参数给 upload 方法。当上传成功后,系统 会调用返回成功的回调函数并传递一个 FileUploadResult 对象。如上传过程中出现错误,系统 会调用上传失败的回调函数,并传递一个 FileTransferError 对象。 2. FileUploadOptions FileUploadOptions 对象将作为参数传递给 FileTransfer 对象的上传方法 upload 中,以指定 上传脚本的参数。 它有以下 4 个属性:  filekey:表单元素的 name 值。默认值为“file”。  fileName:指定文件存储到服务器的文件名,默认值为“image.jpg”。  mimeType:上传文件的 mime 类型,默认值为“image/jpg”。  params:Object 类型,发送到服务器的参数,key/value 值对。 3. FileUploadResult FileUploadResult 对象是 FileTransfer 对象的 upload 方法调用成功后,通过回调函数将一 个 FileUploadResult 对象返回给用户。 FileUploadResult 对象包括有以下 3 个属性:  bytesSent:上传文件时向服务器所发送的字节数。  responseCode:服务器返回的 http 请求代码。  response:服务器返回的 http 相应。 在 iOS 平台下,iOS 平台返回的 FileUploadResult 对象中不包含 bytesSent 和 responseCode 的值。 4. FileTransferError FileTransferError对象是当 FileTransfer 对象的upload方法上传文件出现错误时回调函数所 返回的参数对象。 FileTransferError 对象提供一个 code 属性,用于返回错误代码。同时,FileTransferError 对象还提供 3 个常量,用于判断返回的属性 code 的值属于哪种类型。常量如下:  FileTransferError.FILE_NOT_FOUND_ERR:文件未找到。  FileTransferError.INVALID_URL_ERR:无效的 URL 地址  FileTransferError.CONNECTION_ERR:连接错误。 上述 4 个对象都得到 iOS、Android、Black Berry 等平台的支持。 具体的示例代码如下: 代码 11-26 FileTransfer 具体示例代码 FileWriter Object Example 首先,在 deviceready 事件中通过 navigator.camera.getPicture 方法读取图像文件,并传递 一个读取图像文件成功后回调函数 uploadPhoto。 uploadPhoto 函数内用于处理将图像上传到服务器。其中通过 new FileUploadOptions()新 建一个参数对象。并传入各种的属性,如 fileKey、fileName 等。接着在函数内部创建一个 Filettransfer 对象,并通过 upload 方法上传到服务器中。 upload 方法中的第一个参数为从移动设备中读取到图像的 URI 地址;第二个参数为上传 到服务器的请求地址;第三个参数为上传成功后返回的回调函数;第四个参数为上传出错时 返回的回调函数;最后一个参数为 FileUploadOptions 对象参数。 在 upload 方法上传成功返回的函数中,通过输出对象的全部属性,用以处理各种用户自 定义的功能。 11.11.9 LocalFileSystem LocalFileSystem 对象用于获取根文件系统。 该对象提供 2 个方法: 1. requestFileSystem 方法 请求一个 FileSystem 对象。示例如下: window.requestFileSystem(LocalFileSystem.PERSISTENT,0,function (fileSystem){ console.log(fileSystem.name); },function(error){ console.log(error.code); }); 2. resolveLocalFileSystemURI 方法 通过本地 URI 参数查找 DirectoryEntry 或 FileEntry 对象。示例如下: window.resolveLocalFileSystemURI(“file:///example.txt”,function (fileSystem){ console.log(fileSystem.name); },function(error){ console.log(error.code); }); LocalFileSystem 对象还有 2 个常量,主要使用在 requestFileSystem 方法中。它们分别是: LocalFileSystem.PERSISTENT:用于不经过应用程序或用户许可就无法通过用户代理移 除的存储类型。 LocalFileSystem.TEMPORARY:用于不需要保证持久化的存储类型。 11.11.10 Metadata Metadata 对象提供一个文件或目录的状态信息。可以通过 DirectoryEntry 或 FileEntry 对 象的 getMetadata 方法获得 Metadata 对象的实例。 该接口只有一个属性:modificationTime。它是返回文件或目录的最后修改时间。 使用方法如下代码: entry.getMetadata(function(metadata){ console.log(“last modified is ” + metadata.modificationTim e); },null); 11.12 GeoLocation GeoLocation 对象提供对移动设备 GPS 传感器的访问。该对象 API 是基于 W3C Geo location API 实现的,它也是属于 HTML5 标准范畴内。 在第 8 章已经介绍过 GeoLocation 地理定位的相关知识。PhoneGap 是对其 API 有良好的 支持,其用法请参考第 8 章。 11.13 Media Media 对象提供录制和回放设备上的音频文件的功能。目前 Media 对象支持的平台包括: Android 和 iOS 平台。 目前,PhoneGap 的 Media 功能实现并没有遵守 W3C 媒体的相关规范,其主要是为了提 供方便。未来的版本实现将会遵守最新的 W3C 规范,并有可能不再支持当前的 API。因此本 节主要简单介绍 Media 的 API 接口。 创建一个 Media 对象方法如下: var media = new Media(src,mediaSuccess,[mediaError],[mediaStatu s]); 其中参数 src 为一个音频文件的 URI 地址;mediaSuccess 参数为当一个 Media 对象完成 当前的播放、录制、停止操作时触发的回调函数;mediaError 参数为当出现错误时调用的回 调函数;mediaStatus 参数为当状态发生变化时调用的回调函数。 Media 对象的方法如表 11-15: 表 11-15 Media 对象的方法一览表 方法 说明 getCurrentPosition(successCallb ack,[errorCallback]) 返回一个音频文件的当前位置。 getDuration() 返回一个音频文件的总时长。 play() 开始或恢复播放音频文件。 release() 释放底层操作系统的音频文件资源。 seekTo() 在音频文件中移动到相应的位置。 startRecord() 开始录制音频文件。 stopRecord() 停止录制音频文件。 stop() 停止播放音频文件。 11.14 Notification Notification 对象提供一类视觉、听觉、触觉方面的通知。比如对话框提示、震动提示、 蜂鸣声等。 11.14.1 alert 显示一个定制的警告或对话框。其语法如下: navigator.notification.alert(message,alertCallback,[title],[but tonName]); 其中:  message 参数为对话框的消息;  alertCallback 参数是当警告对话框被忽略时调用的回调函数;  title 参数是对话框标题,属于可选参数,默认值为“Alert”;  buttonName 参数是按钮名称,属于可选参数,默认值为“OK”。 目前该方法所支持的平台包括:iOS、Android、BlackBerry。 大部分 PhoneGap 的本地应用都使用这个方法实现对话框的定制功能。而浏览器的原生 函数通常是不能定制的。 11.14.2 confirm 显示一个可定制的确认对话框。其语法如下: navigator.notification.confirm(message,confirmCallback,[title], [buttonLabels]); 其中:  message 参数为对话框的消息;  confirmCallback 参数是按下按钮后触发的回调函数;  title 参数是对话框标题,属于可选参数,默认值为“Confirm”;  buttonLabels 参数是逗号分隔的按钮标签字符串,属于可选参数,默认值为“OK、 Cancel”。 notification.confirm 的定制功能相比于浏览器的原生 confirm 函数的定制功能强大。 11.14.3 beep 设备将发出蜂鸣声。其语法如下: navigator.notification.beep(times); 其中 times 参数是指定蜂鸣声的重复次数。目前支持的平台包括:iOS、Android、BlackB erry。 在 Android 平台下,beep 方法会播放在“设置/音效及显示”面板中指定的默认“通知铃 声”。 PhoneGap 在 iPhone 下的 beep 方法会被忽略蜂鸣次数的参数,并通过多媒体 API 播放音 频文件来实现蜂鸣。同时,用于必须提供一个包含所需蜂鸣声的文件,此文件的播放时长必 须少于 30 秒,而且文件命名是 beep.wav 和路径位于 www/root。 11.14.4 vibrate 设置设备震动指定的时长。其语法如下: navigator.notification.vibrate(milliseconds); 其中 milliseconds 参数是设定以毫秒为单位的设备震动时长,1000 毫秒为 1 秒。不过 iPhone 是忽略时长参数,震动的时长为预先设定值的。 该方法目前支持的平台包括:iOS、Android、BlackBerry 11.15 Storage 存储 Storage 对象提供对移动设备的存储的访问。该 API 是基于 W3C Web SQL DataBase Spe cification 和 W3C Web Storage API Specification。有些设备已经提供了对该规范的实现,因 此这类设备采用的是内置实现而不是使用 PhoneGap 的实现。 PhoneGap 的 Storage 对象支持 localStorage。localStorage 的使用方法参考第 4 章的 4.2 小 节。 PhoneGap 还支持采用 Web SQL DataBase 方式的本地数据库。通过这类 API 接口,我们可 以实现出创建本地的数据库、查询或插入数据以及执行 SQL 语句等功能。 鉴于目前在移动 Web 应用中,对于 Web SQL DataBase 数据存储和访问的方式在实际应 用项目当中用处并不多。本章节并不打算展开讲述其中的 API。读者可以阅读 PhoneGap 官方 API 文档学习。
还剩58页未读

继续阅读

下载pdf到电脑,查找使用更方便

pdf的实际排版效果,会与网站的显示效果略有不同!!

需要 10 金币 [ 分享pdf获得金币 ] 3 人已下载

下载pdf

pdf贡献者

正在考虑中

贡献于2012-07-20

下载需要 10 金币 [金币充值 ]
亲,您也可以通过 分享原创pdf 来获得金币奖励!
下载pdf