PhoneGap API介紹：Capture

作者：佚名 2011-12-19 16:26:39

移動(dòng)開發(fā)

本文將介紹PhoneGap API——Capture使用設(shè)備的媒體采集應(yīng)用程序采集媒體文件,提供對(duì)設(shè)備音頻、圖像和視頻采集功能的訪問(wèn)。

對(duì)象：

Capture
CaptureAudioOptions
CaptureImageOptions
CaptureVideoOptions
CaptureCB
CaptureErrorCB
ConfigurationData
MediaFile
MediaFileData

方法：

capture.captureAudio
capture.captureImage
capture.captureVideo
MediaFile.getFormatData

范圍：

capture對(duì)象被分配給navigator.device對(duì)象，因此作用域?yàn)槿址秶?/p>

簡(jiǎn)單的范例：

// 全局范圍的capture對(duì)象 
var capture = navigator.device.capture;

屬性：

supportedAudioModes：當(dāng)前設(shè)備所支持的音頻錄制格式。(ConfigurationData[] 類型)

supportedImageModes：當(dāng)前設(shè)備所支持的拍攝圖像尺寸及格式。(ConfigurationData[] 類型)

supportedVideoModes：當(dāng)前設(shè)備所支持的拍攝視頻分辨率及格式。(ConfigurationData[] 類型)

方法：

capture.captureAudio：?jiǎn)?dòng)設(shè)備錄制音頻剪輯的音頻錄制應(yīng)用程序。

capture.captureImage：?jiǎn)?dòng)設(shè)備拍攝照片的攝像頭應(yīng)用程序。

capture.captureVideo：?jiǎn)?dòng)設(shè)備拍攝視頻的視頻錄制應(yīng)用程序。

支持的平臺(tái)：

Android

BlackBerry WebWorks (OS 5.0或更高版本)

iOS

capture.captureAudio

啟動(dòng)錄音機(jī)應(yīng)用程序并返回采集的音頻剪輯文件。

navigator.device.capture.captureAudio(CaptureCB captureSuccess, 
CaptureErrorCB captureError, [CaptureAudioOptions options] );

說(shuō)明：

該方法通過(guò)設(shè)備默認(rèn)的音頻錄制應(yīng)用程序開始一個(gè)異步操作以采集音頻錄制。該操作允許設(shè)備用戶在一個(gè)會(huì)話中同時(shí)采集多個(gè)錄音。

當(dāng)用戶退出音頻錄制應(yīng)用程序，或系統(tǒng)到達(dá)CaptureAudioOptions的limit參數(shù)所定義的最大錄制數(shù)時(shí)都會(huì)停止采集操作。如果沒(méi)有設(shè)置limit參數(shù)的值，則使用其默認(rèn)值1，也就是說(shuō)當(dāng)用戶錄制好一個(gè)音頻剪輯后采集操作就會(huì)終止。

當(dāng)采集操作結(jié)束后，系統(tǒng)會(huì)調(diào)用CaptureCB回調(diào)函數(shù)，傳遞一個(gè)包含所有采集到的音頻剪輯文件的MediaFile對(duì)象數(shù)組。如果用戶在完成一個(gè)音頻剪輯采集之前終止采集操作，系統(tǒng)會(huì)調(diào)用CaptureErrorCB回調(diào)函數(shù)，并傳遞一個(gè)包含CaptureError.CAPTURE_NO_MEDIA_FILES錯(cuò)誤代碼的CaptureError對(duì)象。

支持的平臺(tái)：

Android

BlackBerry WebWorks (OS 5.0或更高版本)

iOS

簡(jiǎn)單的范例：

// 采集操作成功完成后的回調(diào)函數(shù) 
var captureSuccess = function(mediaFiles) { 
var i, path, len; 
for (i = 0, len = mediaFiles.length; i < len; i += 1) { 
path = mediaFiles[i].fullPath; 
// 對(duì)文件進(jìn)行感興趣的操作 
} 
}; 
// 采集操作出錯(cuò)后的回調(diào)函數(shù) 
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">  
 
    // 采集操作成功完成后的回調(diào)函數(shù) 
    function captureSuccess(mediaFiles) {  
        var i, len;  
        for (i = 0, len = mediaFiles.length; i < len; i += 1) { 
            uploadFile(mediaFiles[i]);  
        }  
    }  
     
    // 采集操作出錯(cuò)后的回調(diào)函數(shù) 
    function captureError(error) {  
        var msg = 'An error occurred during capture: ' + error.code; 
        navigator.notification.alert(msg, null, 'Uh oh!');  
    }  
     
    // “Capture Audio”按鈕點(diǎn)擊事件觸發(fā)函數(shù) 
    function captureAudio() {  
     
        // 啟動(dòng)設(shè)備的音頻錄制應(yīng)用程序,   
        // 允許用戶最多采集2個(gè)音頻剪輯 
        navigator.device.capture.captureAudio(captureSuccess, captureError, {limit: 2}); 
    }  
      
    // 上傳文件到服務(wù)器  
    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會(huì)嘗試啟動(dòng)RIM提供的Voice Notes Recorder應(yīng)用程序來(lái)采集音頻錄制。如果設(shè)備沒(méi)有安裝該應(yīng)用程序，開發(fā)者會(huì)收到一個(gè)CaptureError.CATURE_NOT_SUPPORTED錯(cuò)誤代碼。

iOS的特異情況：

iOS沒(méi)有默認(rèn)的音頻錄制應(yīng)用程序，因此僅提供一個(gè)簡(jiǎn)單的用戶界面。

CaptureAudioOptions

封裝音頻采集的配置選項(xiàng)。

屬性：

limit：在單個(gè)采集操作期間能夠記錄的音頻剪輯數(shù)量最大值，必須設(shè)定為大于等于1(默認(rèn)值為1)。

drration：一個(gè)音頻剪輯的最長(zhǎng)時(shí)間，單位為秒。

mode：選定的音頻模式，必須設(shè)定為capture.supportedAudioModes枚舉中的值。

簡(jiǎn)單的范例：

// 限制采集上限為3個(gè)媒體文件，每個(gè)文件不超過(guò)10秒 
var options = { limit: 3, duration: 10 }; 
navigator.device.capture.captureAudio(captureSuccess, captureError, options);

Android的特異情況：

不支持duration參數(shù)，無(wú)法通過(guò)程序限制錄制長(zhǎng)度。

不支持mode參數(shù)，無(wú)法通過(guò)程序修改音頻錄制格式。使用自適應(yīng)多速率(AMR)格式(audio/amr)進(jìn)行音頻錄制編碼。

BlackBerry WebWorks的特異情況：

不支持duration參數(shù)，無(wú)法通過(guò)程序限制錄制長(zhǎng)度。

不支持mode參數(shù)，無(wú)法通過(guò)程序修改音頻錄制格式。使用自適應(yīng)多速率(AMR)格式(audio/amr)進(jìn)行音頻錄制編碼。

iOS的特異情況：

不支持limit參數(shù)，每次調(diào)用只能創(chuàng)建一個(gè)錄制。

不支持mode參數(shù)，無(wú)法通過(guò)程序修改音頻錄制格式。使用波形音頻(WAV)格式(audio/wav)進(jìn)行音頻錄制編碼。

capture.captureImage

開啟攝像頭應(yīng)用程序，返回采集到的圖像文件信息。

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

說(shuō)明：

該方法通過(guò)設(shè)備的攝像頭應(yīng)用程序開始一個(gè)異步操作以采集圖像。該操作允許設(shè)備用戶在一個(gè)會(huì)話中同時(shí)采集多個(gè)圖像。

當(dāng)用戶退出攝像頭應(yīng)用程序，或系統(tǒng)到達(dá)CaptureImageOptions的limit參數(shù)所定義的最大圖像數(shù)時(shí)都會(huì)停止采集操作。如果沒(méi)有設(shè)置limit參數(shù)的值，則使用其默認(rèn)值1，也就是說(shuō)當(dāng)用戶采集到一個(gè)圖像后采集操作就會(huì)終止。

當(dāng)采集操作結(jié)束后，系統(tǒng)會(huì)調(diào)用CaptureCB回調(diào)函數(shù)，傳遞一個(gè)包含每個(gè)采集到的圖像文件的MediaFile對(duì)象數(shù)組。如果用戶在完成一個(gè)圖像采集之前終止采集操作，系統(tǒng)會(huì)調(diào)用CaptureErrorCB回調(diào)函數(shù)，并傳遞一個(gè)包含CaptureError.CAPTURE_NO_MEDIA_FILES錯(cuò)誤代碼的CaptureError對(duì)象。

支持的平臺(tái)：

Android

BlackBerry WebWorks (OS 5.0或更高版本)

iOS

簡(jiǎn)單的范例：

// 采集操作成功完成后的回調(diào)函數(shù) 
var captureSuccess = function(mediaFiles) { 
var i, path, len; 
for (i = 0, len = mediaFiles.length; i < len; i += 1) { 
path = mediaFiles[i].fullPath; 
// 對(duì)文件進(jìn)行感興趣的操作 
} 
}; 
// 采集操作出錯(cuò)后的回調(diào)函數(shù) 
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">  
 
    // 采集操作成功完成后的回調(diào)函數(shù) 
    function captureSuccess(mediaFiles) {  
        var i, len;  
        for (i = 0, len = mediaFiles.length; i < len; i += 1) {  
            uploadFile(mediaFiles[i]);  
        }       
    }  
     
    // 采集操作出錯(cuò)后的回調(diào)函數(shù) 
    function captureError(error) {  
        var msg = 'An error occurred during capture: ' + error.code;  
        navigator.notification.alert(msg, null, 'Uh oh!');  
    }  
     
    // “Capture Image”按鈕點(diǎn)擊事件觸發(fā)函數(shù) 
    function captureImage() { 
        // 啟動(dòng)設(shè)備的攝像頭應(yīng)用程 
        // 允許用戶最多采集2個(gè)圖像 
        navigator.device.capture.captureImage(captureSuccess, captureError, {limit: 2}); 
    }  
     
    // 上傳文件到服務(wù)器 
    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

封裝圖像采集的配置選項(xiàng)。

屬性：

limit：在單個(gè)采集操作期間能夠采集的圖像數(shù)量最大值，必須設(shè)定為大于等于1(默認(rèn)值為1)。

mode：選定的圖像模式，必須設(shè)定為capture.supportedImageModes枚舉中的值。

簡(jiǎn)單的范例：

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

Android的特異情況：

不支持mode參數(shù)，無(wú)法通過(guò)程序修改圖像的大小和格式。不過(guò)設(shè)備用戶可以修改圖像的大小，圖像會(huì)以JPEG格式(image/jpeg)存儲(chǔ)。

BlackBerry WebWorks的特異情況：

iOS的特異情況：

不支持limit參數(shù)，每調(diào)用一次采集一幅圖像。

不支持mode參數(shù)，無(wú)法通過(guò)程序修改圖像的大小和格式。圖像會(huì)以JPEG格式(image/jpeg)存儲(chǔ)。

capture.captureVideo

開啟視頻錄制應(yīng)用程序，返回采集到的視頻剪輯文件信息。

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

說(shuō)明：

該方法通過(guò)設(shè)備的視頻錄制應(yīng)用程序開始一個(gè)異步操作以采集視頻錄制。該操作允許設(shè)備用戶在一個(gè)會(huì)話中同時(shí)采集多個(gè)視頻錄制。

當(dāng)用戶退出視頻錄制應(yīng)用程序，或系統(tǒng)到達(dá)CaptureVideoOptions的limit參數(shù)所定義的最大錄制數(shù)時(shí)都會(huì)停止采集操作。如果沒(méi)有設(shè)置limit參數(shù)的值，則使用其默認(rèn)值1，也就是說(shuō)當(dāng)用戶錄制到一個(gè)視頻剪輯后采集操作就會(huì)終止。

當(dāng)采集操作結(jié)束后，系統(tǒng)會(huì)調(diào)用CaptureCB回調(diào)函數(shù)，傳遞一個(gè)包含每個(gè)采集到的視頻剪輯文件的MediaFile對(duì)象數(shù)組。如果用戶在完成一個(gè)視頻剪輯采集之前終止采集操作，系統(tǒng)會(huì)調(diào)用CaptureErrorCB回調(diào)函數(shù)，并傳遞一個(gè)包含CaptureError.CAPTURE_NO_MEDIA_FILES錯(cuò)誤代碼的CaptureError對(duì)象。

支持的平臺(tái)：

Android

BlackBerry WebWorks (OS 5.0或更高版本)

iOS

簡(jiǎn)單的范例：

// 采集操作成功完成后的回調(diào)函數(shù) 
var captureSuccess = function(mediaFiles) { 
var i, path, len; 
for (i = 0, len = mediaFiles.length; i < len; i += 1) { 
path = mediaFiles[i].fullPath; 
// 對(duì)文件進(jìn)行感興趣的操作 
} 
}; 
// 采集操作出錯(cuò)后的回調(diào)函數(shù) 
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">  
 
    // 采集操作成功完成后的回調(diào)函數(shù) 
    function captureSuccess(mediaFiles) {  
        var i, len;  
        for (i = 0, len = mediaFiles.length; i < len; i += 1) {  
            uploadFile(mediaFiles[i]);  
        }         
    }  
 
    // 采集操作出錯(cuò)后的回調(diào)函數(shù)  
    function captureError(error) {  
        var msg = 'An error occurred during capture: ' + error.code;  
        navigator.notification.alert(msg, null, 'Uh oh!');  
    }  
  
    // “Capture Video”按鈕點(diǎn)擊事件觸發(fā)函數(shù) 
    function captureVideo() {   
        // 啟動(dòng)設(shè)備的視頻錄制應(yīng)用程序, 
        // 允許用戶最多采集2個(gè)視頻剪輯  
        navigator.device.capture.captureVideo(captureSuccess, captureError, {limit: 2});  
    }  
 
    // 上傳文件到服務(wù)器 
    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會(huì)嘗試啟動(dòng)RIM提供的Video Recorder應(yīng)用程序來(lái)采集視頻錄制。如果設(shè)備沒(méi)有安裝該應(yīng)用程序，開發(fā)者會(huì)收到一個(gè)CaptureError.CATURE_NOT_SUPPORTED錯(cuò)誤代碼。

CaptureVideoOptions

封裝視頻采集的配置選項(xiàng)。

屬性：

limit：在單個(gè)采集操作期間能夠采集的視頻剪輯數(shù)量最大值，必須設(shè)定為大于等于1(默認(rèn)值為1)。

drration：一個(gè)視頻剪輯的最長(zhǎng)時(shí)間，單位為秒。

mode：選定的視頻采集模式，必須設(shè)定為capture.supportedVideoModes枚舉中的值。

簡(jiǎn)單的范例：

// 最多采集3個(gè)視頻剪輯 
var options = { limit: 3 }; 
navigator.device.capture.captureVideo(captureSuccess, captureError, options);

Android的特異情況：

不支持duration參數(shù)，無(wú)法通過(guò)程序限制錄制長(zhǎng)度。

不支持mode參數(shù)，無(wú)法通過(guò)程序修改視頻的大小和格式。不過(guò)，設(shè)備用戶可以修改這些參數(shù)，默認(rèn)情況下視頻會(huì)以3GPP格式(video/3gpp)存儲(chǔ)。

BlackBerry WebWorks的特異情況：

不支持duration參數(shù)，無(wú)法通過(guò)程序限制錄制長(zhǎng)度。

不支持mode參數(shù)，無(wú)法通過(guò)程序修改視頻的大小和格式。不過(guò)，設(shè)備用戶可以修改這些參數(shù)，默認(rèn)情況下視頻會(huì)以3GPP(video/3gpp)格式存儲(chǔ)。

iOS的特異情況：

不支持limit參數(shù)，每調(diào)用一次采集一個(gè)視頻。

不支持duration參數(shù)，無(wú)法通過(guò)程序限制錄制長(zhǎng)度。

不支持mode參數(shù)，無(wú)法通過(guò)程序修改視頻的大小和格式。默認(rèn)情況下視頻會(huì)以MOV(video/3gpp)格式存儲(chǔ)。

CaptureCB

媒體采集成功后調(diào)用的回調(diào)函數(shù)。

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

說(shuō)明：

當(dāng)完成一個(gè)成功的采集操作后會(huì)調(diào)用該函數(shù)。這意味著已經(jīng)采集到一個(gè)媒體文件，同時(shí)要么用戶已經(jīng)退出媒體采集應(yīng)用程序，要么已經(jīng)到達(dá)采集數(shù)量上限。

每個(gè)MediaFile對(duì)象都指向一個(gè)采集到的媒體文件。

簡(jiǎn)單的范例：

// 采集操作成功完成后的回調(diào)函數(shù) 
function captureSuccess(mediaFiles) { 
var i, path, len; 
for (i = 0, len = mediaFiles.length; i < len; i += 1) { 
path = mediaFiles[i].fullPath; 
//對(duì)文件進(jìn)行感興趣的操作 
} 
}

CaptureErrorCB

媒體采集操作發(fā)生錯(cuò)誤后調(diào)用的回調(diào)函數(shù)。

function captureError( CaptureError error ) { ... }

說(shuō)明：

出現(xiàn)以下情況會(huì)調(diào)用該函數(shù)：試圖在采集應(yīng)用程序繁忙時(shí)啟動(dòng)媒體采集操作而引起錯(cuò)誤、采集操作正在工作時(shí)出現(xiàn)錯(cuò)誤、用戶在沒(méi)有任何媒體文件采集完成前取消采集操作。

該函數(shù)調(diào)用時(shí)會(huì)傳遞一個(gè)包含相應(yīng)錯(cuò)誤代碼的CaptureError對(duì)象。

簡(jiǎn)單的范例：

// 采集操作出錯(cuò)后的回調(diào)函數(shù) 
var captureError = function(error) { 
navigator.notification.alert('Error code: ' + error.code, null, 'Capture Error'); 
}

ConfigurationData

封裝設(shè)備支持的媒體采集參數(shù)集。

說(shuō)明：

該對(duì)象用于描述設(shè)備所支持的媒體采集模式，配置數(shù)據(jù)包括MIME類型和采集尺寸(適用于視頻和圖像采集)。

MIME類型應(yīng)該符合RFC2046規(guī)范，例如：

video/3gpp

video/quicktime

image/jpeg

audio/amr

audio/wav

屬性：

type：用小寫ASCII編碼字符串表示的媒體類型。(DOMString格式)

height：用像素表示的圖像或視頻高度，音頻剪輯為0。(數(shù)字類型)

width：用像素表示的圖像或視頻寬度，音頻剪輯為0。(數(shù)字類型)

簡(jiǎn)單的范例：

// 獲得支持的圖像模式 
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; 
} 
}

沒(méi)有任何一個(gè)平臺(tái)支持，所有配置數(shù)據(jù)數(shù)組都為空。

MediaFile

封裝采集到的媒體文件的屬性。

屬性：

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

fullPath：包含文件名的文件全路徑。(DOMString類型)

type： MIME類型。(DOMString類型)

lastModifiesDate：文件最后修改的日期和時(shí)間。(日期類型)

size：以字節(jié)數(shù)表示的文件大小。(數(shù)字類型)

方法：

MediaFile.getFormatData：獲取媒體文件的格式信息

MediaFile.getFormatData

獲取采集到的媒體文件的格式信息。

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

說(shuō)明：

該方法通過(guò)異步方式嘗試獲取媒體文件的格式信息。獲取成功的情況下該方法會(huì)調(diào)用MediaFileDataSuccessCB回調(diào)并傳遞一個(gè)MediaFileData對(duì)象，嘗試失敗的情況下該方法會(huì)調(diào)用MediaFileDataErrorCB回調(diào)。

支持的平臺(tái)：

Android

BlackBerry WebWorks (OS 5.0或更高版本)

iOS

BlackBerry WebWorks的特異情況：

沒(méi)有提供媒體文件格式信息的API，因此，所有MediaFileData對(duì)象都會(huì)返回默認(rèn)值。參考MediaFileData文檔。

Android的特異情況：

獲取媒體文件格式信息的API受到限制，因此，不是所有的MediaFileData屬性都支持。參考MediaFileData文檔。

iOS的特異情況：

獲取媒體文件格式信息的API受到限制，因此，不是所有的MediaFileData屬性都支持。參考MediaFileData文檔。

MediaFileData

封裝媒體文件的格式信息。