PhoneGap中文API参考.doc

PhoneGap中文API参考【翻译，刘晓涛整理编辑】Accelerometer“采集设备在x、y、z方向上的动作。方法： accelerometer.getCurrentAcceleration accelerometer.watchAcceleration accelerometer.clearWatch 参数： accelerometerSuccess accelerometerError accelerometerOptions 对象（只读）： Acceleration accelerometer.getCurrentAcceleration返回当前沿x、y和z方向的加速度。 navigator.accelerometer.getCurrentAcceleration(accelerometerSuccess, accelerometerError);说明： 加速计是检测设备在当前方向上所做相对运动变化（增、减量）的运动传感器。加速计可以检测沿X、Y和Z轴的三维运动。 加速度数据通过accelerometerSuccess回调函数返回。 支持的平台： Android BlackBerry WebWorks (OS 5.0或更高版本) iPhone 简单的范例： function onSuccess(acceleration) alert(Acceleration X: + acceleration.x + n +Acceleration Y: + acceleration.y + n +Acceleration Z: + acceleration.z + n +Timestamp: + acceleration.timestamp + n);function onError() alert(onError!);navigator.accelerometer.getCurrentAcceleration(onSuccess, onError);完整的范例： Acceleration Example/ 等待加载PhoneGap document.addEventListener(deviceready, onDeviceReady, false); / PhoneGap加载完毕function onDeviceReady() navigator.accelerometer.getCurrentAcceleration(onSuccess, onError);/ onSuccess: 返回当前加速度数据的快照function onSuccess(acceleration) alert(Acceleration X: + acceleration.x + n +Acceleration Y: + acceleration.y + n +Acceleration Z: + acceleration.z + n +Timestamp: + acceleration.timestamp + n);/ onError: 返回加速度数据失败function onError() alert(onError!);ExamplegetCurrentAccelerationiPhone的特异情况： iPhone没有获取在任何给定点当前加速度数据的概念。 你必须通过给定时间间隔查看加速度并获得数据。 因此，getCurrentAcceleration函数会返回从phoneGap watchAccelerometer调用开始后的最近一个返回值。 accelerometer.watchAcceleration在固定的时间间隔获取沿x、y和z轴的加速度。 var watchID = navigator.accelerometer.watchAcceleration(accelerometerSuccess,accelerometerError,accelerometerOptions);说明： 加速计是检测设备在当前方向上所做相对运动变化（增、减量）的动作传感器。加速计可以检测沿X、Y和Z轴的三维运动。 accelerometer.watchAcceleration 每隔固定时间就获取一次设备的当前加速度。每次取得加速度后，accelerometerSuccess回调函数会被执行。通过 acceleratorOptions对象的frequency参数可以设定以毫秒为单位的时间间隔。 返回的watch id是加速度计监视周期的引用，可以通过accelerometer.clearWatch调用该watch ID以停止对加速度计的监视。 支持的平台： Android BlackBerry WebWorks (OS 5.0或更高版本) iPhone 简单的范例： function onSuccess(acceleration) alert(Acceleration X: + acceleration.x + n +Acceleration Y: + acceleration.y + n +Acceleration Z: + acceleration.z + n +Timestamp: + acceleration.timestamp + n);function onError() alert(onError!);var options = frequency: 3000 ; / 每隔3秒更新一次var watchID = navigator.accelerometer.watchAcceleration(onSuccess, onError, options);完整的范例： Acceleration Example/ watch id 是当前“watchAcceleration”的引用var watchID = null;/ 等待加载PhoneGapdocument.addEventListener(deviceready, onDeviceReady, false);/ PhoneGap加载完毕function onDeviceReady() startWatch();/ 开始监视加速度function startWatch() / 每隔3秒钟更新一次加速度数据var options = frequency: 3000 ;watchID = navigator.accelerometer.watchAcceleration(onSuccess, onError, options);/ 停止监视加速度function stopWatch() if (watchID) navigator.accelerometer.clearWatch(watchID);watchID = null;/ onSuccess: 获取当前加速度数据的快照function onSuccess(acceleration) var element = document.getElementById(accelerometer);element.innerHTML = Acceleration X: + acceleration.x + +Acceleration Y: + acceleration.y + +Acceleration Z: + acceleration.z + +Timestamp: + acceleration.timestamp + ;/ onError: 获取加速度失败function onError() alert(onError!);Waiting for accelerometer.iPhone的特异情况： 在请求的时间间隔，PhoneGap将调用success回调指向的函数，并传递加速度计数据。 不过，PhoneGap将对设备的请求间隔时间限制为最小40ms，最大1000ms。 例如，如果你设定每隔3秒（3000毫秒）请求一次，PhoneGap仍然每隔1秒请求一次设备，但是每隔3秒才调用一次success回调函数。 accelerometer.clearWatch停止watch ID参数指向的加速度监视。 navigator.accelerometer.clearWatch(watchID); watchID：由accelerometer.watchAcceleration返回的引用标识ID。 支持的平台： Android BlackBerry WebWorks (OS 5.0或更高版本) iPhone 简单的范例： var watchID = navigator.accelerometer.watchAcceleration(onSuccess, onError, options);/ . 后续处理 .navigator.accelerometer.clearWatch(watchID);完整的范例： Acceleration Example/ watch id 是当前“watchAcceleration”的引用var watchID = null;/ 等待加载PhoneGapdocument.addEventListener(deviceready, onDeviceReady, false);/ PhoneGap加载完毕function onDeviceReady() startWatch();/ 开始监视加速度function startWatch() / 每隔3秒钟更新一次加速度数据var options = frequency: 3000 ;watchID = navigator.accelerometer.watchAcceleration(onSuccess, onError, options);/ 停止监视加速度function stopWatch() if (watchID) navigator.accelerometer.clearWatch(watchID);watchID = null;/ onSuccess: 获取当前加速度数据的快照function onSuccess(acceleration) var element = document.getElementById(accelerometer);element.innerHTML = Acceleration X: + acceleration.x + +Acceleration Y: + acceleration.y + +Acceleration Z: + acceleration.z + +Timestamp: + acceleration.timestamp + ;/ onError: 获取加速度失败function onError() alert(onError!);Waiting for accelerometer.Stop WatchingAcceleration包含特定时间点采集到的加速计数据。 属性： x：在X轴的运动量，0, 1范围（数字类型） y：在Y轴的运动量，0, 1范围（数字类型） z：在Z轴的运动量，0, 1范围（数字类型） timestamp：以毫秒为单位的创建时间戳。（DOMTimeStamp类型） 说明： 这个对象是由phoneGap创建和填充，并由Acce这个对象是由PhoneGap创建和填充，并由Accelerometer的方法返回。 支持的平台： Android BlackBerry WebWorks (OS 5.0或更高版本) iPhone Windows Phone 7 ( Mango ) 简单的范例： function onSuccess(acceleration) alert(Acceleration X: + acceleration.x + n +Acceleration Y: + acceleration.y + n +Acceleration Z: + acceleration.z + n +Timestamp: + acceleration.timestamp + n);function onError() alert(onError!);navigator.accelerometer.getCurrentAcceleration(onSuccess,onError);完整的范例： Acceleration Example/ 等待加载PhoneGapdocument.addEventListener(deviceready, onDeviceReady, false);/ PhoneGap加载完毕function onDeviceReady() navigator.accelerometer.getCurrentAcceleration(onSuccess, onError);/ onSuccess: 获得加速度数据的快照function onSuccess(acceleration) alert(Acceleration X: + acceleration.x + n +Acceleration Y: + acceleration.y + n +Acceleration Z: + acceleration.z + n +Timestamp: + acceleration.timestamp + n);/ onError: 获取加速度失败function onError() alert(onError!);ExamplegetCurrentAccelerationaccelerometerSuccess提供加速度信息的onSuccess回调函数。 function(acceleration) / 进一步处理参数： acceleration： 在某一时刻的加速度(Acacceleration：在某一时刻的加速度。(Acceleration对象类型) function onSuccess(acceleration) alert(Acceleration X: + acceleration.x + n +Acceleration Y: + acceleration.y + n +Acceleration Z: + acceleration.z + n +Timestamp: + acceleration.timestamp + n);accelerometerError加速度方法的onError回调函数。 function() / 错误处理accelerometerOptions定制检索加速度计的可选参数。 选项： frequency：多少毫秒获取一次Acceleration。（数字类型）（默认值：10000） Camera“camera对象提供对设备默认摄像头应用程序的访问。方法： camera.getPicture camera.getPicture选择使用摄像头拍照，或从设备相册中获取一张照片。图片以base64编码的字符串或图片URI形式返回。 简单的范例： navigator.camera.getPicture( cameraSuccess, cameraError, cameraOptions );说明： camera.getPicture函数打开设备的默认摄像头应用程序，使用户可以拍照（如果 Camera.sourceType 设置为 Camera.PictureSourceType.CAMERA，这也是默认值）。一旦拍照结束，摄像头应用程序会关闭并恢复用户应用程序。 如果Camera.sourceType = Camera.PictureSourceType.PHOTOLIBRARY或Camera.PictureSourceType.SAVEDPHOTOALBUM，系统弹出照片选择对话框，用户可以从相集中选择照片。 返回值会按照用户通过cameraOptions参数所设定的下列格式之一发送给cameraSuccess回调函数： 一个字符串，包含Base64编码的照片图像（默认情况）。 一个字符串，表示在本地存储的图像文件位置。你可以对编码的图片或URI做任何处理，例如： 通过标签渲染图片（参看后续范例） 存储为本地数据（LocalStorage，Lawnchair*等） 将数据发送到远程服务器 备注： 较新的设备上使用摄像头拍摄的照片的质量是相当不错的，使用Base64对这些照片进行编码已导致其中的一些设备出现内存问题（如IPHONE4、 BlackBerry Torch 9800）。因此，强烈建议将“Camera.destinationType”设为FILE_URI。 支持的平台： Android BlackBerry WebWorks (OS 5.0或更高版本) iPhone Windows Phone 7 ( Mango ) 简单的范例： 拍照并获取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);拍照并获取图像文件路径： 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);完整的范例： Capture Photovar pictureSource;/图片来源var destinationType;/设置返回值的格式/ 等待PhoneGap连接设备document.addEventListener(deviceready,onDeviceReady,false);/ PhoneGap准备就绪，可以使用！function onDeviceReady() pictureSource=navigator.camera.PictureSourceType;destinationType=navigator.camera.DestinationType;/ 当成功获得一张照片的Base64编码数据后被调用function onPhotoDataSuccess(imageData) / 取消注释以查看Base64编码的图像数据/ console.log(imageData);/ 获取图像句柄var smallImage = document.getElementById(smallImage); / 取消隐藏的图像元素smallImage.style.display = block;/ 显示拍摄的照片/ 使用内嵌CSS规则来缩放图片smallImage.src = data:image/jpeg;base64, + imageData; / 当成功得到一张照片的URI后被调用 function onPhotoURISuccess(imageURI) / 取消注释以查看图片文件的URI/ console.log(imageURI);/ 获取图片句柄var largeImage = document.getElementById(largeImage); / 取消隐藏的图像元素largeImage.style.display = block;/ 显示拍摄的照片/ 使用内嵌CSS规则来缩放图片largeImage.src = imageURI; / “Capture Photo”按钮点击事件触发函数 function capturePhoto() / 使用设备上的摄像头拍照，并获得Base64编码字符串格式的图像navigator.camera.getPicture(onPhotoDataSuccess, onFail, quality: 50 ); / “Capture Editable Photo”按钮点击事件触发函数 function capturePhotoEdit() / 使用设备上的摄像头拍照，并获得Base64编码字符串格式的可编辑图像navigator.camera.getPicture(onPhotoDataSuccess, onFail, quality: 20, allowEdit: true ); /“From Photo Library”/“From Photo Album”按钮点击事件触发函数 function getPhoto(source) / 从设定的来源处获取图像文件URInavigator.camera.getPicture(onPhotoURISuccess, onFail, quality: 50,destinationType: destinationType.FILE_URI,sourceType: source ); / 当有错误发生时触发此函数 function onFail(mesage) alert(Failed because: + message); Capture Photo Capture Editable Photo From Photo LibraryFrom Photo AlbumcameraSuccess提供图像数据的onSuccess回调函数。 function(imageData) / 对图像进行处理参数： imageData：根据cameraOptions的设定值，为Base64编码的图像数据或图像文件的URI。（字符串类型） 范例： / 显示图片function cameraCallback(imageData) var image = document.getElementById(myImage);image.src = data:image/jpeg;base64, + imageData;cameraError提供错误信息的onError回调函数。 function(message) / 显示有用信息参数： message：设备本地代码提供的错误信息。（字符串类型） cameraOptions定制摄像头设置的可选参数。 quality : 75,destinationType : Camera.DestinationType.DATA_URL,sourceType : Camera.PictureSourceType.CAMERA,allowEdit : true,encodingType : Camera.EncodingType.JPEG,targetWidth : 100,targetHeight : 100;选项： quality：存储图像的质量，范围是0,100。（数字类型） destinationType：选择返回数据的格式。通过navigator.camera.DestinationType进行定义。（数字类型） Camera.DestinationType = DATA_URL : 0,/返回Base64编码字符串的图像数据FILE_URI : 1/返回图像文件的URI sourceType：设定图片来源。通过nagivator.camera.PictureSourceType进行定义。（数字类型） Camera.PictureSourceType = PHOTOLIBRARY : 0,CAMERA : 1,SAVEDPHOTOALBUM : 2 allowEdit：在选择图片进行操作之前允许对其进行简单编辑。（布尔类型） EncodingType：选择返回图像文件的编码方式，通过navigator.camera.EncodingType进行定义。（数字类型） Camera.EncodingType = JPEG : 0,/ 返回JPEG格式图片PNG : 1/ 返回PNG格式图片; targetWidth：以像素为单位的图像缩放宽度，必须和targetHeight同时使用。相应的宽高比保持不变。（数字类型） targetHeight：以像素为单位的图像缩放高度，必须和targetWidth同时使用。相应的宽高比保持不变。（数字类型） MediaType：设置选择图片的类型，只有当PictureSourceType is PHOTOLIBRARY or SAVEDPHOTOALBUM时才会生效，该参数由nagivator.camera.MediaType (数字类型)定义 Camera.MediaType = PICTURE: 0, / allow selection of still pictures only. DEFAULT. Will return format specified via DestinationType /默认值，返回的是Picture，返回由DestinationType指定的格式 VIDEO: 1, / allow selection of video only, WILL ALWAYS RETURN FILE_URI /选出的只能是video类型，返回值是FILE_URI ALLMEDIA : 2 /allow selection from all media types 允许选出的是所有类型Android的特异情况： 忽略allowEdit参数。 Camera.PictureSourceType.PHOTOLIBRARY 或 Camera.PictureSourceType.SAVEDPHOTOALBUM 都会显示同一个相集。 Camera.EncodingType不被支持。 BlackBerry的特异情况： 忽略quality参数。 忽略sourceType参数。 忽略allowEdit参数。 当拍照结束后，应用程序必须有按键注入权限才能关闭本地Camera应用程序。 使用大图像尺寸，可能会导致新近带有高分辨率摄像头的型号设备无法对图像进行编码（如：Torch 9800）。 Camera.MediaType不Capture“提供对设备音频、图像和视频采集功能的访问。对象： Capture CaptureAudioOptions CaptureImageOptions CaptureVideoOptions CaptureCB CaptureErrorCB ConfigurationData MediaFile MediaFileData 方法： capture.captureAudio capture.captureImage capture.captureVideo MediaFile.getFormatData 范围： capture对象被分配给navigator.device对象，因此作用域为全局范围。 简单的范例： / 全局范围的capture对象var capture = navigator.device.capture;属性： supportedAudioModes：当前设备所支持的音频录制格式。（ConfigurationData 类型） supportedImageModes：当前设备所支持的拍摄图像尺寸及格式。（ConfigurationData 类型） supportedVideoModes：当前设备所支持的拍摄视频分辨率及格式。（ConfigurationData 类型） 方法： capture.captureAudio：启动设备录制音频剪辑的音频录制应用程序。 capture.captureImage：启动设备拍摄照片的摄像头应用程序。 capture.captureVideo：启动设备拍摄视频的视频录制应用程序。 支持的平台： Android BlackBerry WebWorks (OS 5.0或更高版本) iOS Windows Phone 7 ( Mango ) capture.captureAudio“启动录音机应用程序并返回采集的音频剪辑文件。navigator.device.capture.captureAudio(CaptureCB captureSuccess, CaptureErrorCB captureError, CaptureAudioOptions options );说明： 该方法通过设备默认的音频录制应用程序开始一个异步操作以采集音频录制。该操作允许设备用户在一个会话中同时采集多个录音。 当用户退出音频录制应用程序，或系统到达CaptureAudioOptions的limit参数所定义的最大录制数时都会停止采集操作。如果没有设置limit参数的值，则使用其默认值1，也就是说当用户录制好一个音频剪辑后采集操作就会终止。 当 采集操作结束后，系统会调用CaptureCB回调函数，传递一个包含所有采集到的音频剪辑文件的MediaFile对象数组。如果用户在完成一个音频剪 辑采集之前终止采集操作，系统会调用CaptureErrorCB回调函数，并传递一个包含 CaptureError.CAPTURE_NO_MEDIA_FILES错误代码的CaptureError对象。 支持的平台： Android BlackBerry WebWorks (OS 5.0或更高版本) iOS Windows Phone 7 ( Mango ) 简单的范例： / 采集操作成功完成后的回调函数var captureSuccess = function(mediaFiles) var i, path, len;for (i = 0, len = mediaFiles.length; i len; i += 1) path = mediaFilesi.fullPath; / 对文件进行感兴趣的操作 ; / 采集操作出错后的回调函数var captureError = function(error) navigator.notification.alert(Error code: + error.code, null, Capture Error); ; / 开始采集音频navigator.device.capture.captureAudio(captureSuccess, captureError, limit:2);完整的范例： Capture Audio / 采集操作成功完成后的回调函数function captureSuccess(mediaFiles) var i, len; for (i = 0, len = mediaFiles.length; i len; i += 1) uploadFile(mediaFilesi); / 采集操作出错后的回调函数function captureError(error) var msg = An error occurred during capture: + error.code;navigator.notification.alert(msg, null, Uh oh!); / “Capture Audio”按钮点击事件触发函数function captureAudio() / 启动设备的音频录制应用程序, / 允许用户最多采集2个音频剪辑navigator.device.capture.captureAudio(captureSuccess, captureError, limit: 2); / 上传文件到服务器 function uploadFile(mediaFile) var ft = new FileTransfer(), path = mediaFile.fullPath, name = mediaF; ft.upload(path,/upload.php,function(result) console.log(Upload success: + result.responseCode); console.log(result.bytesSent + bytes sent); , function(error) console.log(Error uploading file + path + : + error.code); , fileName: name