PhoneGap API介绍：Capture-screen capture api

对象：

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

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

简单的范例：

// 采集操作成功完成后的回调函数 
var captureSuccess = function(mediaFiles) { 
var i, path, len; 
for (i = 0, len = mediaFiles.length; i < len; i += 1) { 
path = mediaFiles[i].fullPath; 
// 对文件进行感兴趣的操作 
} 
}; 
// 采集操作出错后的回调函数 
var captureError = function(error) { 
navigator.notification.alert('Error code: ' + error.code, null, 'Capture Error'); 
}; 
// 开始采集音频 
navigator.device.capture.captureAudio(captureSuccess, captureError, {limit:2});

完整的范例：

<!DOCTYPE html> 
<html> 
<head> 
<title>Capture Audio</title>   
     
<script type="text/javascript" charset="utf-8" src="phonegap.js"></script>  
<script type="text/javascript" charset="utf-8" src="json2.js"></script>  
<script type="text/javascript" charset="utf-8">  
 
    // 采集操作成功完成后的回调函数 
    function captureSuccess(mediaFiles) {  
        var i, len;  
        for (i = 0, len = mediaFiles.length; i < len; i += 1) { 
            uploadFile(mediaFiles[i]);  
        }  
    }  
     
    // 采集操作出错后的回调函数 
    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 = mediaFile.name;  
        ft.upload(path, 
                "http://my.domain.com/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 });   
    }   
     
</script> 
</head> 
<body> 
    <button onclick="captureAudio();">Capture Audio</button> 
</body> 
</html>

BlackBerry WebWorks的特异情况：

在BlackBerry WebWorks上，PhoneGap会尝试启动RIM提供的Voice Notes Recorder应用程序来采集音频录制。如果设备没有安装该应用程序，开发者会收到一个CaptureError.CATURE_NOT_SUPPORTED错误代码。

iOS的特异情况：

iOS没有默认的音频录制应用程序，因此仅提供一个简单的用户界面。

CaptureAudioOptions

封装音频采集的配置选项。

属性：

limit：在单个采集操作期间能够记录的音频剪辑数量最大值，必须设定为大于等于1(默认值为1)。

drration：一个音频剪辑的最长时间，单位为秒。

mode：选定的音频模式，必须设定为capture.supportedAudioModes枚举中的值。

简单的范例：

// 限制采集上限为3个媒体文件，每个文件不超过10秒 
var options = { limit: 3, duration: 10 }; 
navigator.device.capture.captureAudio(captureSuccess, captureError, options);

Android的特异情况：

不支持duration参数，无法通过程序限制录制长度。

不支持mode参数，无法通过程序修改音频录制格式。使用自适应多速率(AMR)格式(audio/amr)进行音频录制编码。

BlackBerry WebWorks的特异情况：

不支持duration参数，无法通过程序限制录制长度。

不支持mode参数，无法通过程序修改音频录制格式。使用自适应多速率(AMR)格式(audio/amr)进行音频录制编码。

iOS的特异情况：

不支持limit参数，每次调用只能创建一个录制。

不支持mode参数，无法通过程序修改音频录制格式。使用波形音频(WAV)格式(audio/wav)进行音频录制编码。

capture.captureImage

开启摄像头应用程序，返回采集到的图像文件信息。

navigator.device.capture.captureImage( 
CaptureCB captureSuccess, CaptureErrorCB captureError, [CaptureImageOptions options] 
);

说明：

该方法通过设备的摄像头应用程序开始一个异步操作以采集图像。该操作允许设备用户在一个会话中同时采集多个图像。

当用户退出摄像头应用程序，或系统到达CaptureImageOptions的limit参数所定义的最大图像数时都会停止采集操作。如果没有设置limit参数的值，则使用其默认值1，也就是说当用户采集到一个图像后采集操作就会终止。

当采集操作结束后，系统会调用CaptureCB回调函数，传递一个包含每个采集到的图像文件的MediaFile对象数组。如果用户在完成一个图像采集之前终止采集操作，系统会调用CaptureErrorCB回调函数，并传递一个包含CaptureError.CAPTURE_NO_MEDIA_FILES错误代码的CaptureError对象。

支持的平台：

Android

BlackBerry WebWorks (OS 5.0或更高版本)

iOS

简单的范例：

// 采集操作成功完成后的回调函数 
var captureSuccess = function(mediaFiles) { 
var i, path, len; 
for (i = 0, len = mediaFiles.length; i < len; i += 1) { 
path = mediaFiles[i].fullPath; 
// 对文件进行感兴趣的操作 
} 
}; 
// 采集操作出错后的回调函数 
var captureError = function(error) { 
navigator.notification.alert('Error code: ' + error.code, null, 'Capture Error'); 
}; 
// 开始采集图像 
navigator.device.capture.captureImage(captureSuccess, captureError, {limit:2});

完整的范例：

<!DOCTYPE html> 
<html> 
<head>   
<title>Capture Image</title>  
 
<script type="text/javascript" charset="utf-8" src="phonegap.js"></script>  
<script type="text/javascript" charset="utf-8" src="json2.js"></script>  
<script type="text/javascript" charset="utf-8">  
 
    // 采集操作成功完成后的回调函数 
    function captureSuccess(mediaFiles) {  
        var i, len;  
        for (i = 0, len = mediaFiles.length; i < len; i += 1) {  
            uploadFile(mediaFiles[i]);  
        }       
    }  
     
    // 采集操作出错后的回调函数 
    function captureError(error) {  
        var msg = 'An error occurred during capture: ' + error.code;  
        navigator.notification.alert(msg, null, 'Uh oh!');  
    }  
     
    // “Capture Image”按钮点击事件触发函数 
    function captureImage() { 
        // 启动设备的摄像头应用程 
        // 允许用户最多采集2个图像 
        navigator.device.capture.captureImage(captureSuccess, captureError, {limit: 2}); 
    }  
     
    // 上传文件到服务器 
    function uploadFile(mediaFile) { 
        var ft = new FileTransfer(), 
            path = mediaFile.fullPath,  
            name = mediaFile.name;  
     
        ft.upload(path,"http://my.domain.com/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 }); 
    }   
 
</script> 
</head> 
<body> 
    <button onclick="captureImage();">Capture Image</button> 
</body> 
</html>

CaptureImageOptions

封装图像采集的配置选项。

属性：

limit：在单个采集操作期间能够采集的图像数量最大值，必须设定为大于等于1(默认值为1)。

mode：选定的图像模式，必须设定为capture.supportedImageModes枚举中的值。

简单的范例：

// 最多采集3幅图像 
var options = { limit: 3 }; 
navigator.device.capture.captureImage(captureSuccess, captureError, options);

Android的特异情况：

不支持mode参数，无法通过程序修改图像的大小和格式。不过设备用户可以修改图像的大小，图像会以JPEG格式(image/jpeg)存储。

BlackBerry WebWorks的特异情况：

不支持mode参数，无法通过程序修改图像的大小和格式。不过设备用户可以修改图像的大小，图像会以JPEG格式(image/jpeg)存储。

iOS的特异情况：

不支持limit参数，每调用一次采集一幅图像。

不支持mode参数，无法通过程序修改图像的大小和格式。图像会以JPEG格式(image/jpeg)存储。

capture.captureVideo

开启视频录制应用程序，返回采集到的视频剪辑文件信息。

navigator.device.capture.captureVideo( 
CaptureCB captureSuccess, CaptureErrorCB captureError, [CaptureVideoOptions options] 
);

说明：

该方法通过设备的视频录制应用程序开始一个异步操作以采集视频录制。该操作允许设备用户在一个会话中同时采集多个视频录制。

当用户退出视频录制应用程序，或系统到达CaptureVideoOptions的limit参数所定义的最大录制数时都会停止采集操作。如果没有设置limit参数的值，则使用其默认值1，也就是说当用户录制到一个视频剪辑后采集操作就会终止。

当采集操作结束后，系统会调用CaptureCB回调函数，传递一个包含每个采集到的视频剪辑文件的MediaFile对象数组。如果用户在完成一个视频剪辑采集之前终止采集操作，系统会调用CaptureErrorCB回调函数，并传递一个包含CaptureError.CAPTURE_NO_MEDIA_FILES错误代码的CaptureError对象。

支持的平台：

Android

BlackBerry WebWorks (OS 5.0或更高版本)

iOS

简单的范例：

// 采集操作成功完成后的回调函数 
var captureSuccess = function(mediaFiles) { 
var i, path, len; 
for (i = 0, len = mediaFiles.length; i < len; i += 1) { 
path = mediaFiles[i].fullPath; 
// 对文件进行感兴趣的操作 
} 
}; 
// 采集操作出错后的回调函数 
var captureError = function(error) { 
navigator.notification.alert('Error code: ' + error.code, null, 'Capture Error'); 
}; 
// 开始采集视频 
navigator.device.capture.captureVideo(captureSuccess, captureError, {limit:2});

完整的范例：

<!DOCTYPE html> 
<html> 
<head> 
<title>Capture Video</title>  
 
<script type="text/javascript" charset="utf-8" src="phonegap.js"></script>  
<script type="text/javascript" charset="utf-8" src="json2.js"></script>  
<script type="text/javascript" charset="utf-8">  
 
    // 采集操作成功完成后的回调函数 
    function captureSuccess(mediaFiles) {  
        var i, len;  
        for (i = 0, len = mediaFiles.length; i < len; i += 1) {  
            uploadFile(mediaFiles[i]);  
        }         
    }  
 
    // 采集操作出错后的回调函数  
    function captureError(error) {  
        var msg = 'An error occurred during capture: ' + error.code;  
        navigator.notification.alert(msg, null, 'Uh oh!');  
    }  
  
    // “Capture Video”按钮点击事件触发函数 
    function captureVideo() {   
        // 启动设备的视频录制应用程序, 
        // 允许用户最多采集2个视频剪辑  
        navigator.device.capture.captureVideo(captureSuccess, captureError, {limit: 2});  
    }  
 
    // 上传文件到服务器 
    function uploadFile(mediaFile) {  
        var ft = new FileTransfer(),  
            path = mediaFile.fullPath,  
            name = mediaFile.name;  
 
        ft.upload(path,"http://my.domain.com/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 });     
    }   
 
</script> 
</head> 
<body> 
    <button onclick="captureVideo();">Capture Video</button> 
</body> 
</html>

BlackBerry WebWorks 的特异情况：

在BlackBerry WebWorks上，PhoneGap会尝试启动RIM提供的Video Recorder应用程序来采集视频录制。如果设备没有安装该应用程序，开发者会收到一个CaptureError.CATURE_NOT_SUPPORTED错误代码。

CaptureVideoOptions

封装视频采集的配置选项。

属性：

limit：在单个采集操作期间能够采集的视频剪辑数量最大值，必须设定为大于等于1(默认值为1)。

drration：一个视频剪辑的最长时间，单位为秒。

mode：选定的视频采集模式，必须设定为capture.supportedVideoModes枚举中的值。

简单的范例：

// 最多采集3个视频剪辑 
var options = { limit: 3 }; 
navigator.device.capture.captureVideo(captureSuccess, captureError, options);

Android的特异情况：

不支持duration参数，无法通过程序限制录制长度。

不支持mode参数，无法通过程序修改视频的大小和格式。不过，设备用户可以修改这些参数，默认情况下视频会以3GPP格式(video/3gpp)存储。

BlackBerry WebWorks的特异情况：

不支持duration参数，无法通过程序限制录制长度。

不支持mode参数，无法通过程序修改视频的大小和格式。不过，设备用户可以修改这些参数，默认情况下视频会以3GPP(video/3gpp)格式存储。

iOS的特异情况：

不支持limit参数，每调用一次采集一个视频。

不支持duration参数，无法通过程序限制录制长度。

不支持mode参数，无法通过程序修改视频的大小和格式。默认情况下视频会以MOV(video/3gpp)格式存储。

CaptureCB

媒体采集成功后调用的回调函数。

function captureSuccess( MediaFile[] mediaFiles ) { ... }

说明：

当完成一个成功的采集操作后会调用该函数。这意味着已经采集到一个媒体文件，同时要么用户已经退出媒体采集应用程序，要么已经到达采集数量上限。

每个MediaFile对象都指向一个采集到的媒体文件。

简单的范例：

// 采集操作成功完成后的回调函数 
function captureSuccess(mediaFiles) { 
var i, path, len; 
for (i = 0, len = mediaFiles.length; i < len; i += 1) { 
path = mediaFiles[i].fullPath; 
//对文件进行感兴趣的操作 
} 
}

CaptureErrorCB

媒体采集操作发生错误后调用的回调函数。

function captureError( CaptureError error ) { ... }

说明：

出现以下情况会调用该函数：试图在采集应用程序繁忙时启动媒体采集操作而引起错误、采集操作正在工作时出现错误、用户在没有任何媒体文件采集完成前取消采集操作。

该函数调用时会传递一个包含相应错误代码的CaptureError对象。

简单的范例：

// 采集操作出错后的回调函数 
var captureError = function(error) { 
navigator.notification.alert('Error code: ' + error.code, null, 'Capture Error'); 
}

ConfigurationData

封装设备支持的媒体采集参数集。

说明：

该对象用于描述设备所支持的媒体采集模式，配置数据包括MIME类型和采集尺寸(适用于视频和图像采集)。

MIME类型应该符合RFC2046规范，例如：

video/3gpp

video/quicktime

image/jpeg

audio/amr

audio/wav

属性：

type：用小写ASCII编码字符串表示的媒体类型。(DOMString格式)

height：用像素表示的图像或视频高度，音频剪辑为0。(数字类型)

width：用像素表示的图像或视频宽度，音频剪辑为0。(数字类型)

简单的范例：

// 获得支持的图像模式 
var imageModes = navigator.device.capture.supportedImageModes; 
// 选择最高水平分辨率的模式 
var width = 0; 
var selectedmode; 
foreach (var mode in imageModes) { 
if (mode.width > width) { 
width = mode.width; 
selectedmode = mode; 
} 
}

没有任何一个平台支持，所有配置数据数组都为空。

MediaFile

封装采集到的媒体文件的属性。

属性：

name：不含路径信息的文件名。(DOMString类型)

fullPath：包含文件名的文件全路径。(DOMString类型)

type： MIME类型。(DOMString类型)

lastModifiesDate：文件最后修改的日期和时间。(日期类型)

size：以字节数表示的文件大小。(数字类型)

方法：

MediaFile.getFormatData：获取媒体文件的格式信息

MediaFile.getFormatData

获取采集到的媒体文件的格式信息。

mediaFile.getFormatData( 
MediaFileDataSuccessCB successCallback, 
[MediaFileDataErrorCB errorCallback] 
)

说明：

该方法通过异步方式尝试获取媒体文件的格式信息。获取成功的情况下该方法会调用MediaFileDataSuccessCB回调并传递一个MediaFileData对象，尝试失败的情况下该方法会调用MediaFileDataErrorCB回调。

支持的平台：

Android

BlackBerry WebWorks (OS 5.0或更高版本)

iOS

BlackBerry WebWorks的特异情况：

没有提供媒体文件格式信息的API，因此，所有MediaFileData对象都会返回默认值。参考MediaFileData文档。

Android的特异情况：

获取媒体文件格式信息的API受到限制，因此，不是所有的MediaFileData属性都支持。参考MediaFileData文档。

iOS的特异情况：

获取媒体文件格式信息的API受到限制，因此，不是所有的MediaFileData属性都支持。参考MediaFileData文档。

MediaFileData

封装媒体文件的格式信息。

属性：

codecs：音频及视频内容的实际格式。(DOMString类型)

bitrate：文件内容的平均比特率。对于图像文件，属性值为0。(数字类型)

height：用像素表示的图像或视频高度，音频剪辑的该属性值为0。(数字类型)

width：用像素表示的图像或视频的宽度，音频剪辑的该属性值为0。(数字类型)

duration：以秒为单位的视频或音频剪辑时长，图像文件的该属性值为0。(数字类型)

BlackBerry WebWorks的特异情况：

没有提供媒体文件格式信息的API，因此MediaFile.getFormatData方法返回的MediaFileData对象包含以下默认值：

codecs：不支持，该属性始终为空。

bitrate：不支持，该属性始终为0。

heigh：不支持，该属性始终为0。

width：不支持，该属性始终为0。

duration：不支持，该属性始终为0。

Android的特异情况：

MediaFileData属性的支持情况如下：

codecs：不支持，该属性始终为空。

bitrate：不支持，该属性始终为0。

height：支持(仅限图像或视频文件)。

width：支持(仅限图像或视频文件)。

duration：支持(仅限音频或视频文件)。

iOS的特异情况：

MediaFileData属性的支持情况如下：

codecs：不支持，该属性始终为空。

bitrate：iOS4设备上仅支持音频，对于图像和视频此属性值为0。

height：支持(仅限图像或视频文件)。

width：支持(仅限图像或视频文件)。

duration：支持(仅限音频或视频文件)。