PhoneGap API介紹：Capture

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

移動開發

本文將介紹PhoneGap API——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

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：支持(僅限音頻或視頻文件)。

責任編輯：佚名來源： PhoneGap中國

PhoneGap API Capture