Cordova - 媒体捕获

Cordova - 媒体捕获

cordova-plugin-media-capture 插件提供了访问设备原生音频、图像和视频捕获功能的能力。这允许用户直接在应用程序内录制音频、拍照或录制视频。

步骤 1 - 安装媒体捕获插件

通过命令行将插件添加到你的项目：

cordova plugin add cordova-plugin-media-capture

注意：此插件可能还需要 cordova-plugin-file 作为依赖项，用于处理捕获的媒体文件。

步骤 2 - 添加 UI (用户界面) 元素 (按钮)

在 index.html 中，创建按钮以触发音频、图像和视频捕获。

<!-- 在 index.html 中 -->
<button id="captureAudioButton">Capture Audio</button>
<button id="captureImageButton">Capture Image</button>
<button id="captureVideoButton">Capture Video</button>
<div id="mediaFilesStatus" style="margin-top:10px;"></div>

步骤 3 - 添加事件监听器

在你的 JavaScript 文件（例如 index.js）中，在 deviceready 事件后为这些按钮设置事件监听器。

// 在 index.js 中，在 'deviceready' 事件后
document.addEventListener('deviceready', () => {
    if (!navigator.device || !navigator.device.capture) {
        alert("媒体捕获 API 不可用。插件是否已安装？");
        return;
    }
    document.getElementById("captureAudioButton").addEventListener("click", captureUserAudio);
    document.getElementById("captureImageButton").addEventListener("click", captureUserImage);
    document.getElementById("captureVideoButton").addEventListener("click", captureUserVideo);
}, false);

步骤 4 - 实现捕获函数

插件通过 navigator.device.capture 对象暴露了 captureAudio()、captureImage() 和 captureVideo() 等方法。

A. 捕获音频 (captureUserAudio)

此函数会启动原生的音频录制应用程序。

function captureUserAudio() {
    const options = {
        limit: 1, // 最大录制音频片段数量
        duration: 10 // 单个音频片段的最大持续时间（秒）
    };
    navigator.device.capture.captureAudio(onCaptureSuccess, onCaptureError, options);
}

// 所有捕获类型的共享成功回调
function onCaptureSuccess(mediaFiles) {
    let statusHtml = '<h4>捕获成功！</h4>';
    for (let i = 0, len = mediaFiles.length; i < len; i += 1) {
        const mediaFile = mediaFiles[i];
        statusHtml += '<p>**名称：** ' + mediaFile.name + '<br>' +
                      '**完整路径：** ' + mediaFile.fullPath + '<br>' +
                      '**类型：** ' + mediaFile.type + '<br>' +
                      '**大小：** ' + mediaFile.size + ' 字节</p>';
        console.log('捕获的文件：', mediaFile);
        // 你可以使用 mediaFile.fullPath 结合 cordova-plugin-file 来读取/上传文件
        // 或者，如果是图像/视频，则显示它。
    }
    document.getElementById('mediaFilesStatus').innerHTML = statusHtml;
}

// 共享错误回调
function onCaptureError(error) {
    const msg = '捕获错误：代码 ' + error.code + '\n' + (error.message || '');
    console.error(msg);
    alert(msg);
    document.getElementById('mediaFilesStatus').innerHTML = '<p style="color:red;">' + msg + '</p>';
}

当按下 AUDIO 按钮时，设备的录音 UI 将打开。录制完成后，onCaptureSuccess 会收到一个 MediaFile 对象数组。

控制台和状态区域将显示捕获的音频文件的详细信息。例如：

// 音频控制台输出示例：
// 捕获的文件：{name: "audio_...mp3", fullPath: "cdvfile://localhost/persistent/path/to/audio.mp3", type: "audio/mpeg", ...}

B. 捕获图像 (captureUserImage)

此函数会启动原生相机应用程序进行拍照。注意：如需对图像捕获进行更多控制（例如质量、编码、直接获取 base64 数据），通常首选 cordova-plugin-camera。此插件的 captureImage 方法更适用于基本的图像捕获。

function captureUserImage() {
    const options = {
        limit: 1 // 最大捕获图像数量
    };
    // 注意：对于图像捕获，options 对象目前仅在 iOS 上受支持。
    // 它通常更简单，并且可能不如 cordova-plugin-camera 提供更多选项。
    navigator.device.capture.captureImage(onCaptureSuccess, onCaptureError, options);
}

按下 IMAGE 按钮会打开相机。捕获的图像详细信息由 onCaptureSuccess 处理。

控制台和状态区域将显示捕获的图像文件的详细信息。

C. 捕获视频 (captureUserVideo)

此函数会启动原生的视频录制应用程序。

function captureUserVideo() {
    const options = {
        limit: 1, // 最大视频片段数量
        duration: 15, // 单个视频片段的最大持续时间（秒）
        // quality: 1 // (0=低, 1=高)。仅适用于 iOS。Android 使用设备默认设置。
    };
    navigator.device.capture.captureVideo(onCaptureSuccess, onCaptureError, options);
}

按下 VIDEO 按钮会打开摄像机。捕获的视频详细信息由 onCaptureSuccess 处理。

控制台和状态区域将显示捕获的视频文件的详细信息。

MediaFile 对象

onCaptureSuccess 回调会收到一个 MediaFile 对象数组。每个 MediaFile 对象具有以下属性：

• name：文件名，不包含路径信息。
• fullPath：设备上文件的完整路径。此路径可与 cordova-plugin-file 一起使用。
• type：文件的 MIME 类型 (例如 image/jpeg、audio/aac、video/mp4)。
• lastModifiedDate：文件最后修改的日期和时间（Date 对象）。
• size：文件大小（字节）（Number）。

此外，MediaFile 对象上还提供 getFormatData(successCallback, errorCallback) 方法，用于检索格式信息，例如 codec (编解码器)、bitrate (比特率)、持续时间（音频/视频）、高度和宽度（图像/视频）。

CaptureError 对象

onCaptureError 回调会收到一个 CaptureError 对象，该对象包含 code 属性（在某些平台上还包含可选的 message）：

• CaptureError.CAPTURE_INTERNAL_ERR (代码 0)：相机、麦克风或其他内部错误。
• CaptureError.CAPTURE_APPLICATION_BUSY (代码 1)：捕获应用程序正忙于处理请求。
• CaptureError.CAPTURE_INVALID_ARGUMENT (代码 2)：API 参数无效。
• CaptureError.CAPTURE_NO_MEDIA_FILES (代码 3)：用户在捕获任何内容之前退出了捕获应用程序。
• CaptureError.CAPTURE_NOT_SUPPORTED (代码 20)：设备不支持请求的操作。

重要注意事项

• 权限：插件会处理请求相机、麦克风和存储所需的必要权限。如果遇到权限问题，请确保你的 config.xml 或特定平台的清单文件已正确设置，尽管插件通常会处理这些。
• 用户体验：用户会被带到原生的捕获应用程序。捕获期间的界面外观将是操作系统的样式，而不是你的应用程序的样式。
• 文件处理：捕获的媒体会保存到临时位置。如果需要，使用 cordova-plugin-file 将这些文件移动或复制到持久位置。
• 替代方案：如需对图像捕获进行更精细的控制（例如自定义覆盖层、特定分辨率、Base64 输出），考虑使用 cordova-plugin-camera。如需对音频录制进行更多控制，cordova-plugin-media 可能是一个替代方案。
• iOS 特性：在 iOS 上，对于 captureImage，limit: 1 实际上始终为真；用户一次只能选择/拍摄一张图像。视频质量选项是 iOS 特有的。

有关最新详细信息和特定平台行为，请参阅 cordova-plugin-media-capture 的官方文档。