@cordova-ohos/cordova-plugin-camera

v8.0.1

Published

23 days ago

Cordova Camera Plugin

0High
0Medium
0Low

cordova camera ecosystem:cordova cordova-openharmony

cordova-plugin-camera

本项目基于 [email protected] 开发，本文档重点阐述其在 OpenHarmony（OHOS）系统中的具体应用。

cordova-plugin-camera

简介

cordova-plugin-camera 是 Harmony Cordova 生态系统中一款核心插件，用于为 Cordova 应用提供访问设备摄像头的能力，支持拍摄照片、从相册选取图片，并能对获取的图片进行压缩、裁剪等基础处理。

调用设备原生摄像头拍摄照片
从设备相册中选择已有的图片
配置图片质量、尺寸、格式（JPEG/PNG）
支持图片压缩与裁剪
提供 base64 编码或文件路径两种图片返回格式

支持平台

Android：API 19 及以上（Android 4.4+）
iOS：10.0 及以上
OHOS：5.0+

下载安装

通过 hcordova CLI 即可快速安装插件，支持从 npm 仓库或 GitCode 仓库获取。

从 npm 安装（推荐）

# 使用 hcordova CLI 安装

# 安装 hcordova 命令化工具
npm install -g hcordova

# 全平台安装插件
hcordova plugin add cordova-plugin-camera

指定平台安装 ohos

仅为 OHOS 平台安装插件：

# 仅安装到 OHOS 平台
hcordova plugin add cordova-plugin-camera --platform ohos

# 指定版本安装
hcordova plugin add [email protected] --platform ohos

从 GitCode 仓库安装

仅为 OHOS 平台安装插件：

# 仅安装到 OHOS 平台

# 默认分支安装
hcordova plugin add https://gitcode.com/CPF-Cordova/cordova-plugin-camera.git --platform ohos

# 指定标签/分支安装
hcordova plugin add https://gitcode.com/CPF-Cordova/cordova-plugin-camera.git@develop --platform ohos

离线安装（本地包）

适用于无网络环境，先下载插件包到本地，再执行离线安装：

# 下载插件包到本地（示例路径：~/Downloads/cordova-plugin-camera）
# 执行离线安装
hcordova plugin add ~/Downloads/cordova-plugin-camera --platform ohos

安装后验证

安装完成后，可通过以下命令验证插件是否成功添加到项目中：

# 查看已安装的插件列表，若包含本插件 ID 则表示插件已成功安装
hcordova plugin list

卸载

# Cordova CLI 全平台卸载
hcordova plugin remove cordova-plugin-camera 

# 指定平台卸载
hcordova plugin remove cordova-plugin-camera --platform ohos

约束与限制

依赖插件：无强制依赖，若需处理图片路径，可搭配 cordova-plugin-file 使用

兼容性

支持：

| 项目 | 版本/信息 | |-----|--------| | SDK | API12+ | | IDE | DevEco Studio: 5.0+ | | ROM | 5.1+ | | Emulator | OpenHarmony 6.0+ |

在以下版本中已测试通过：

| 项目 | 版本/信息 | |-----|--------| | @cordova-ohos/ohos | 14.0.1-ohos-14.0.1 | | SDK | 5.0.0(12) | | IDE | DevEco Studio: 6.0.13.200 | | ROM | 5.1.0.120 SP3 | | Emulator | OpenHarmony 6.0.1(21) |

权限要求

OHOS 相机功能，调用系统相机拍摄照片，无需权限申请

使用示例

以下提供常见场景的使用示例，涵盖“拍摄照片”“从相册选图”“获取 base64 图片”。

// 前置摄像头拍摄照片
function openCamera() {
    var options = {
        // Some common settings are 20, 50, and 100
        quality: 100,
        destinationType: Camera.DestinationType.FILE_URI,
        sourceType: Camera.PictureSourceType.CAMERA,
        encodingType: Camera.EncodingType.JPEG,
        mediaType: Camera.MediaType.PICTURE,
        allowEdit: true,
        cameraDirection:Camera.Direction.FRONT,
        correctOrientation: true  // Corrects Android orientation quirks
    }
    navigator.camera.getPicture(function cameraSuccess(imageUri) {
        var elem = document.getElementById('imgInfo1');
        elem.src = imageUri;
        elem.onload = function(){
            document.getElementById('imgSize1').innerHTML = "width:"+elem.naturalWidth+",height:"+elem.naturalHeight;
        }
    }, function cameraError(error) {
        console.debug("Unable to obtain picture: " + error, "app");
    }, options);
}

// 后置摄像头录制视频
function openCameraVod() {
    var options = {
        quality: 100,
        destinationType: Camera.DestinationType.FILE_URI,
        sourceType: Camera.PictureSourceType.CAMERA,
        encodingType: Camera.EncodingType.JPEG,
        mediaType: Camera.MediaType.VIDEO,
        allowEdit: false,
        cameraDirection:Camera.Direction.BACK,
        correctOrientation: true  // Corrects Android orientation quirks
    }

    navigator.camera.getPicture(function cameraSuccess(imageUri) {
        var fileName = imageUri;
    }, function cameraError(error) {
        console.debug("Unable to obtain picture: " + error, "app");
    }, options);
}

// 从相册选择一个图片，指定高度、宽度和压缩图片质量
function openPhoto() {
    var options = {
        quality: 80,
        destinationType: Camera.DestinationType.DATA_URL,
        sourceType: Camera.PictureSourceType.PHOTOLIBRARY,
        encodingType: Camera.EncodingType.JPEG,
        mediaType: Camera.MediaType.PICTURE,
        targetWidth:800,
        targetHeight:600,
        allowEdit: true,
        correctOrientation: true  // Corrects Android orientation quirks
    }
    navigator.camera.getPicture(function cameraSuccess(imageData) {
        var elem = document.getElementById('imgInfo2');
        elem.src = "data:image/jpeg;base64,"+imageData;
        elem.onload = function(){
            document.getElementById('imgSize2').innerHTML = "width:"+elem.naturalWidth+",height:"+elem.naturalHeight;
        }
    }, function cameraError(error) {
        console.debug("Unable to obtain picture: " + error, "app");
    }, options);
}

使用说明

插件核心通过 navigator.camera 对象暴露 API，主要方法为 getPicture()，用于获取图片。

核心方法：getPicture()

方法定义

navigator.camera.getPicture(
  successCallback,  // 成功回调（返回图片数据）
  errorCallback,    // 失败回调（返回错误信息）
  options           // 配置参数（可选）
);

回调函数说明

successCallback(imageData)：
- 功能：获取图片成功后触发
- 参数 imageData：根据 options.destinationType 返回不同格式：
  - DATA_URL：返回 base64 编码的图片字符串（格式：data:image/jpeg;base64,...）
  - FILE_URI/NATIVE_URI：返回图片文件的本地路径，该路径可以直接在 img 标签中引用（如 https://localhost/data/storage/el2/base/haps/entry/cache/17636018073030.png）
errorCallback(error)：
- 功能：获取图片失败或用户取消时触发
- 参数 error：包含错误信息的字符串

配置参数（options）

| 参数名 | 类型 | 可选 | 默认值 | 说明 | | --- | --- | --- | --- | --- | | quality | Number | 0-100 | 50 | 图片质量（0 最低，100 最高）OHOS 图片质量压缩参考新特性 | | destinationType | Number | Camera.DestinationType.DATA_URL Camera.DestinationType.FILE_URI Camera.DestinationType.NATIVE_URI | FILE_URI | 图片返回格式 | | sourceType | Number | Camera.PictureSourceType.CAMERA Camera.PictureSourceType.PHOTOLIBRARY Camera.PictureSourceType.SAVEDPHOTOALBUM | CAMERA | 图片来源（摄像头/相册/保存的相册） | | allowEdit | Boolean | true（仅用于兼容 Android/iOS，该字段在 OHOS 平台默认 true） | true | 是否允许用户编辑图片（裁剪） | | encodingType | Number | Camera.EncodingType.JPEG Camera.EncodingType.PNG | JPEG | 图片编码格式 | | targetWidth | Number | 正整数 | -1（原尺寸） | 图片目标宽度（像素），会按比例缩放 | | targetHeight | Number | 正整数 | -1（原尺寸） | 图片目标高度（像素），会按比例缩放 | | mediaType | Number | Camera.MediaType.PICTURE Camera.MediaType.VIDEO Camera.MediaType.ALLMEDIA | PICTURE | 媒体类型（仅图片/仅视频/所有媒体） | | correctOrientation | Number | true/false | true | 保持图片正确方向 | | saveToPhotoAlbum | Boolean | true/false | true | OHOS 平台无需申请权限，图片默认保存到相册 | | cameraDirection | Number | Direction.BACK Direction.FRONT | BACK | 摄像头（后置摄像头、前置摄像头） |

新增特性

可在 config.xml 中配置图片压缩行为：

| 配置项 | 类型 | 说明 | 默认值 | | --- | --- | --- | --- | | CameraImageCompress | Boolean | 是否启用图片压缩功能 | true | | maxCompressSize | Number | 压缩后图片的目标大小（单位：MB），系统会尽量将图片压缩至接近该值 | 4 | | showToastText | String | 压缩时显示的提示文本，为空则不显示提示框 | 压缩图片，请稍后 |

<!-- config.xml 不配置，默认压缩图片最大 4M，压缩时 showToastText 提醒内容为：“压缩图片，请稍后” -->
<!-- config.xml 增加配置以下，显示压缩图片的提示框内容，showToastText 为空，不显示提示框，maxCompressSize 为压缩图片最后的大小，单位 M，例如 2M，压缩无限接近 2M 的图片 -->
<preference name="CameraImageCompress" value="true" maxCompressSize="2" showToastText="处理中..." />

目录结构

cordova-plugin-camera/
├── src/                          # 源代码目录
│   └── main/                     # 主要源代码
│       ├── cpp/                  # C++ 原生代码
│       │   └── camera/           # 相机模块
│       │       ├── CameraLauncher.cpp  # 相机启动功能的 C++ 实现
│       │       └── CameraLauncher.h    # 相机启动功能的头文件
│       └── ets/                  # ArkTS 代码（OpenHarmony API）
│           └── components/       # 组件目录
│               ├── ImageCompress/     # 图片压缩组件
│               └── MediaAction/       # 媒体动作组件
│                   └── MediaAction.ets  # 媒体操作的实现
├── www/                          # Web 资源目录
│   ├── Camera.js                 # JavaScript 相机接口（Cordova 桥接层）
│   ├── CameraConstants.js        # 相机常量定义
│   ├── CameraPopoverHandle.js    # 相机弹窗处理
│   └── CameraPopoverOptions.js   # 相机弹窗选项配置
├── .gitignore                    # Git 忽略文件配置
├── LICENSE                       # 项目开源许可证
├── OAT.xml                       # OpenHarmony 审核配置文件
├── package.json                  # Node.js 包配置
├── plugin.xml                    # Cordova 插件描述文件（核心配置）
└── README.md                     # 项目说明文档

贡献代码

使用过程中发现任何问题都可以提 Issue ，当然也非常欢迎发 PR 共建。

许可证

本插件基于 Apache License 2.0 开源，详见 LICENSE 文件。

官方资源

Android 和 iOS：cordova-plugin-camera 官方指南
GitCode 仓库：CPF-Cordova/cordova-plugin-camera