@cordova-ohos/cordova-plugin-telerik-imagepicker
v2.3.7
Published
Cordova Telerik Image Picker Plugin
Readme
cordova-plugin-telerik-imagepicker
本项目基于 [email protected] 开发，本文档重点阐述其在 OpenHarmony（OHOS）系统中的具体应用。
简介
cordova-plugin-telerik-imagepicker 是一款功能强大的 Cordova 图片选择插件，支持从设备相册中批量选择图片、预览图片、限制选择数量及尺寸筛选等功能，适配 Android、iOS 和 OHOS 三平台，为混合式移动应用提供高效的图片选择解决方案。本文重点说明该插件在 OHOS 系统中的使用方法、配置及注意事项。
功能特性
批量选择：支持一次性选择多张图片，可自定义最大选择数量，满足多图上传等场景需求
图片预览：选择前可预览图片缩略图及原图，直观查看图片效果，提升用户操作体验
尺寸筛选：可根据图片宽度、高度筛选符合要求的图片，避免选择不符合应用需求的图片
格式支持：兼容 JPG、PNG 等主流图片格式，适配不同拍摄场景和图片来源
权限管理：自动处理相册访问权限申请，提供权限拒绝回调，便于开发者处理权限异常场景
丰富元数据：选择图片后返回完整元数据，包括图片路径、尺寸、大小等，满足后续业务处理需求
多平台适配：完美适配 Android、iOS、OHOS 三平台，无需额外修改代码即可跨平台使用
异步接口：所有 API 均为异步执行，通过回调函数处理结果，不阻塞应用主线程
支持平台
Android（API 级别 14 及以上）
iOS（iOS 9.0 及以上）
OHOS（5.0 及以上）
前置准备
在集成插件前，确保开发环境已满足以下基础条件，无需额外在第三方平台注册配置：
已安装 Node.js（v14.0.0 及以上）和 npm（v6.0.0 及以上）
已安装 HCordova CLI（10.0.0 及以上），用于插件的安装、卸载和管理
已创建 Cordova 项目（若未创建，可通过
cordova create imagePickerDemo com.example.imagepicker ImagePickerDemo命令创建）确保目标设备（或模拟器）已开启相册权限，便于插件正常访问设备相册
下载安装
通过 hcordova CLI 即可快速安装插件，支持基础稳定版安装、指定版本安装，也可从 GitCode 仓库获取最新开发版，安装流程简洁高效。
前提条件
安装插件前，需先安装 HCordova CLI，执行以下命令安装：
npm install -g hcordova从 npm 安装（基础稳定版）
# 安装最新稳定版（全平台）
hcordova plugin add cordova-plugin-telerik-imagepicker安装指定版本
适用于需要固定插件版本的场景，可指定版本号并仅安装到 OHOS 平台：
# 安装 1.0.0 版本（指定 OHOS 平台）
hcordova plugin add [email protected] --platform ohos从 GitCode 仓库安装（开发版）
适用于需要体验最新功能的开发者，仅为 OHOS 平台安装开发版插件：
# 仅支持 OHOS 平台
hcordova plugin add https://gitcode.com/CPF-Cordova/cordova-plugin-telerik-imagepicker.git --platform ohos
# 指定标签/分支安装
hcordova plugin add https://gitcode.com/CPF-Cordova/cordova-plugin-telerik-imagepicker.git@develop --platform ohos离线安装（本地包）
适用于无网络环境，先下载插件包到本地，再执行离线安装：
# 下载插件包到本地（示例路径：~/Downloads/cordova-plugin-telerik-imagepicker）
# 执行离线安装
hcordova plugin add ~/Downloads/cordova-plugin-telerik-imagepicker --platform ohos安装后验证
安装完成后，可通过以下命令验证插件是否成功添加到项目中：
# 查看已安装的插件列表，若包含本插件 ID 则表示插件已成功安装
hcordova plugin list卸载
如需移除插件，进入项目根目录执行以下命令，卸载后建议重新构建项目以清理残留文件：
# 全平台卸载
hcordova plugin remove cordova-plugin-telerik-imagepicker
# 指定 OHOS 卸载
hcordova plugin remove cordova-plugin-telerik-imagepicker --platform ohosOHOS 配置
在 OHOS 使用安全相机，无需配置相机访问权限
约束与限制
依赖插件：无强制依赖，可直接集成到 Cordova 项目中使用
图片限制：仅支持 JPG、PNG 等主流图片格式，GIF、WebP 可能无法正常预览和选择
API 调用限制：所有 API 均为异步执行，需通过成功回调和错误回调处理结果，不可同步调用
选择数量限制：最大选择数量可自定义，但需结合设备性能和内存情况合理设置，避免选择过多图片导致应用卡顿
OHOS 特殊限制：OHOS 5.0 及以上版本支持，低于该版本的设备可能无法正常使用插件功能
兼容性
支持：
| 项目 | 版本/信息 | |-----|--------| | 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) |
使用示例
插件所有方法均在全局对象 window.imagePicker 下可用，所有方法均为异步执行，通过成功回调和错误回调处理结果。以下为各核心功能的完整使用示例，可直接复制到项目中使用。
1. 基础用法：批量选择图片并预览
选择多张图片（最多 9 张），筛选宽度不小于 800px 的图片，并在页面中预览选择的图片：
// 等待 Cordova 加载完成
document.addEventListener("deviceready", () => {
// 选择多张照片
window.imagePicker.getPictures(
function (results) {
// 成功回调：results 为选择的图片路径数组
if (results.length <= 0) {
console.log("未选择任何图片");
return;
}
// 拼接图片标签，用于页面预览
var src = "";
for (var i = 0; i < results.length; i++) {
// OHOS 平台图片路径需拼接 localhost 前缀
src += "<img src='https://localhost" + results[i] + "' width='100%' />";
}
// 将图片渲染到页面指定元素
document.getElementById("imgInfo").innerHTML = src;
},
function (error) {
console.log('图片选择失败：', error);
},
{
maximumImagesCount: 9, // 最大选择数量
width: 800 // 图片最小宽度筛选（像素）
}
);
}, false);2. 自定义配置选择图片
自定义最大选择数量、图片尺寸筛选，同时获取图片元数据：
document.addEventListener("deviceready", () => {
window.imagePicker.getPictures(
function (results) {
if (results.length <= 0) {
return;
}
// 遍历图片路径，获取图片元数据（需结合额外逻辑获取尺寸、大小）
results.forEach((imagePath, index) => {
console.log(`第${index+1}张图片路径：`, imagePath);
// 可通过图片路径进一步获取图片尺寸、大小等信息
var img = new Image();
img.src = "https://localhost" + imagePath;
img.onload = function() {
console.log(`第${index+1}张图片尺寸：${this.width}x${this.height}`);
};
});
},
function (error) {
console.error('Error: ' + error);
},
{
maximumImagesCount: 5, // 自定义最大选择数量为 5 张
width: 600, // 最小宽度 600px
height: 400, // 最小高度 400px
quality: 80 // 图片质量（0-100），仅对压缩后的图片有效
}
);
}, false);3. 处理权限拒绝场景
当用户拒绝相册权限时，给出友好提示并引导用户开启权限：
document.addEventListener("deviceready", () => {
window.imagePicker.getPictures(
function (results) {
if (results.length > 0) {
var src = "";
for (var i = 0; i < results.length; i++) {
src += "<img src='https://localhost" + results[i] + "' width='100%' />";
}
document.getElementById("imgInfo").innerHTML = src;
}
},
function (error) {
// 处理权限拒绝错误
if (error.includes("permission")) {
alert("请开启相册权限，否则无法选择图片！");
// 可引导用户跳转到权限设置页面（OHOS 平台需结合原生 API 实现）
} else {
console.log('图片选择失败：', error);
}
},
{
maximumImagesCount: 3,
width: 500
}
);
}, false);使用说明
以下为插件使用的核心说明，包括 API 详解、参数说明、注意事项等，帮助开发者快速上手并避免异常。
1. 核心 API 说明
插件所有方法均挂载在全局对象 window.imagePicker 下，无需额外引入，需在 Cordova 加载完成后（deviceready 事件触发后）调用，否则会出现 API 未定义、调用失败等异常。所有方法均为异步执行，通过成功回调和错误回调处理结果。
1.1 getPictures：批量选择图片
功能：打开设备相册，允许用户批量选择图片，支持筛选图片尺寸、限制选择数量，选择完成后返回图片路径数组。
语法：
window.imagePicker.getPictures(successCallback, errorCallback, options)1.2 回调函数说明
successCallback（必传）：选择成功时触发的回调函数，参数
results为图片路径数组，每个元素为选中图片的本地路径（OHOS 平台需拼接https://localhost前缀才能正常显示）。errorCallback（必传）：选择失败时触发的回调函数，参数
error为错误信息字符串，常见错误包括权限拒绝、相册访问失败、无图片可选择等。
2. 核心配置参数（options）说明
| 参数名称 | 类型 | 说明 | 默认值 | |---|---|---|---| | maximumImagesCount | 数字 | 最大选择图片数量，最小值为 1，最大值根据设备性能可自定义 | 1 | | width | 数字 | 图片最小宽度（像素），筛选宽度不小于该值的图片；0 表示不筛选宽度 | 0 | | height | 数字 | 图片最小高度（像素），筛选高度不小于该值的图片；0 表示不筛选高度 | 0 | | quality | 数字 | 图片质量（0-100），值越高图片越清晰，文件体积越大；仅对需要压缩的图片有效 | 80 | | allowEdit | 布尔值 | 是否允许编辑图片（如裁剪、旋转），部分平台支持 | false |
3. 常见问题（FAQ）
Q1: 调用 getPictures 方法无反应怎么办？
检查 API 调用时机：确保在
deviceready事件触发后调用该方法，否则window.imagePicker可能未定义检查插件安装：执行
hcordova plugin list确认插件已成功安装检查权限配置：OHOS 平台需在配置文件中声明相册读写权限，确保权限配置正确
重新构建项目：执行
hcordova build ohos，确保插件资源和配置正确加载
Q2: 选择图片后无法显示怎么办？
检查图片路径：OHOS 平台图片路径需拼接
https://localhost前缀，例如https://localhost${imagePath}检查图片格式：确保选择的图片为 JPG、PNG 等主流格式，避免选择不支持的格式
检查设备权限：确认应用已获取相册访问权限，若未获取，需重新申请权限
Q3: 权限拒绝后如何处理？
在 errorCallback 中判断错误信息是否包含“permission”，若为权限拒绝，可通过弹窗提示用户开启权限，并引导用户跳转到设备权限设置页面（OHOS 平台需结合原生 API 实现跳转）。
4. 注意事项
API 调用时机：所有 JavaScript API 必须在
deviceready事件触发后调用，否则会出现 window.imagePicker 未定义、调用失败等异常。图片路径处理：OHOS 平台返回的图片本地路径需拼接
https://localhost前缀，才能在页面中正常显示图片。权限处理：需在错误回调中处理权限拒绝场景，给出友好提示，提升用户体验。
选择数量控制：根据设备性能合理设置 maximumImagesCount，避免选择过多图片导致应用卡顿或内存溢出。
图片筛选：width 和 height 参数为最小尺寸筛选，仅筛选尺寸不小于该值的图片，若需筛选最大尺寸，需在选择后自行处理。
兼容性提示：确保 OHOS 设备版本为 5.0 及以上，HCordova CLI 版本为 10.0.0 及以上，否则可能出现功能异常。
目录结构
cordova-plugin-telerik-imagepicker # [根目录] 图片选择器插件项目根目录
├── src # [源码目录] 存放原生平台代码
│ └── main # [主目录] 主代码目录
│ └── cpp # [C++ 目录] C++ 原生代码目录
│ └── ImagePicker # [C++ 模块] 图片选择 C++ 模块文件夹
│ ├── ImagePicker.cpp # [C++ 实现] C++ 源文件，实现图片选择/拍照的底层逻辑
│ └── ImagePicker.h # [C++ 声明] C++ 头文件，定义图片选择接口
├── www # [前端目录] 存放供 Web 端调用的 JS 接口文件
│ └── imagepicker.js # [JS 文件] 暴露给 Web 端的 JS 接口，用于调用原生图片选择功能
├── .gitignore # [配置] Git 版本控制忽略文件配置
├── LICENSE # [文本] 开源许可证文件
├── OAT.xml # [配置] 门禁配置文件
├── package.json # [配置] 项目依赖和元数据配置文件
├── plugin.xml # [配置] Cordova 插件配置文件，定义插件结构和映射
└── README.md # [文档] 项目说明文档，通常包含安装和使用指南贡献代码
使用过程中发现任何问题都可以提 Issue，当然也非常欢迎发 PR 共建。
许可证
本插件基于 Apache License 2.0 开源，详见 LICENSE 文件。
官方资源
Android 和 iOS：cordova-plugin-telerik-imagepicker 官方指南