@cordova-ohos/cordova-plugin-photo-library

v2.3.2

Published

4 days ago

Cordova Photo Library Plugin

Downloads

833

0High
0Medium
0Low

cordova photo-library ecosystem:cordova cordova-openharmony

cordova-plugin-photo-library

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

cordova-plugin-photo-library

简介

cordova-plugin-photo-library 是一款专为 Cordova/PhoneGap 应用设计的手机相册交互插件，支持 iOS、Android 和 OHOS 平台实现相册照片/视频的读取、保存、删除、创建相册等核心功能，适配最新系统权限机制，适用于社交分享、内容编辑、媒体管理类应用场景。

在 OHOS 系统中，访问相册权限属于 OpenHarmony 的管控权限，需要单独向 OHOS 申请，只有符合 OHOS 要求的应用才能使用相册权限，因此该插件不能完全操作相册的敏感数据，只具备相册的选择照片、视频、保存到相册照片、保存到相册视频的功能，具体使用方法参考下面的使用示例。

支持平台

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-photo-library

指定平台安装 ohos

仅为 OHOS 平台安装插件：

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

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

从 GitCode 仓库安装

仅为 OHOS 平台安装插件，推荐获取最新稳定版：

# 仅安装到 OHOS 平台

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

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

离线安装（本地包）

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

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

安装后验证

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

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

卸载

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

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

约束与限制

兼容性

支持：

| 项目 | 版本/信息 | |-----|--------| | 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 平台说明

在 OHOS 系统中，访问相册权限属于 OpenHarmony 的管控权限，需要单独向 OHOS 申请，只有符合 OHOS 要求的应用才能使用相册权限。本插件仅开放相册基础操作权限，可实现照片/视频选择、保存功能，无法完全操作相册敏感数据，具体操作需遵循 OHOS 权限管控规则。

使用示例

插件挂载在 cordova.plugins.photoLibrary 对象上，所有方法均支持回调函数语法，以下为各核心功能的纯代码使用示例，可直接复制到项目中使用（API 及参数详情见「使用说明」章节）。

1. 选择照片

function selectPhotoFromAlbums() {
    cordova.plugins.photoLibrary.getLibrary(
        function (result) {
            let library = result.library;
            photos = library;
            // Here we have the library as array data:image/bmp;base64,
            let imgInfo = "";
            for(let i=0; i<library.length; i++) {
                imgInfo += "<img width='100%' src='data:"+library[i].mimeType+";base64,"+library[i].thumbnailBase64+"' />";
            }
            document.getElementById("libraryInfo").innerHTML = imgInfo;
        },
        function (err) {
            console.log('Error occurred');
        },
        { // optional options
            thumbnailWidth: 512,
            thumbnailHeight: 384,
            quality: 0.8,
            includeImages:true,  
            includeVideos:false
        }
    );
}

2. 选择相册

function selectAlbums() {
    cordova.plugins.photoLibrary.getAlbums(
        function (albums) {
            document.getElementById("albumsInfo").innerHTML = JSON.stringify(albums);
        },
        function (err) { }
    );
}

3. 获取缩略图

function getThumbnail() {
    if(photos && photos.length > 0) {
        cordova.plugins.photoLibrary.getThumbnail(photos[0],
            function (thumbnail) {
                document.getElementById("thumbnailInfo").src = window.URL.createObjectURL(thumbnail);
            },
            function (err) { }
        );
    }
}

4. 获取照片

function getLibraryPhoto() {
    if(photos && photos.length > 0) {
        cordova.plugins.photoLibrary.getPhoto(photos[0],
            function (photo) {
                document.getElementById("photoInfo").src = window.URL.createObjectURL(photo);
            },
            function (err) { }
        );
    }
}

5. 保存图片到相册

// 通过 getLibrary 选择图片保存到相册
function saveLibraryPhoto() {
    if(photos && photos.length > 0) {
        cordova.plugins.photoLibrary.saveImage(photos[0].uri, "",
            function (photo) {
                document.getElementById("saveInfo1").innerHTML = "保存成功";
            },
            function (err) { }
        );
    }
}
// 保存在线图片到相册，图片会自动下载
function saveLibraryPhoto2() {
    cordova.plugins.photoLibrary.saveImage("https://cordova.apache.org/static/img/cordova_bot.png", "",
        function (photo) {
            document.getElementById("saveInfo2").innerHTML = "保存成功";
        },
        function (err) { }
    );
}

6. 保存视频到相册

// 通过 getLibrary 选择的视频保存到相册
function saveLibraryVideo() {
    if(photos && photos.length > 0) {
        cordova.plugins.photoLibrary.saveVideo(photos[0].uri, "",
            function (photo) {
                document.getElementById("saveInfo3").innerHTML = "保存成功";
            },
            function (err) { }
        );
    }
}

// 保存在线视频，视频会自动下载，最好只保存短视频，不要保存大视频
function saveLibraryVideo2() {
    cordova.plugins.photoLibrary.saveVideo("https://example.com/SVID_20250928_140357_1.mp4", "",
        function (photo) {
            document.getElementById("saveInfo4").innerHTML = "保存成功";
        },
        function (err) { }
    );
}

使用说明

插件调用：所有 API 均通过全局对象 cordova.plugins.photoLibrary 调用，无需额外引入，直接调用对应方法即可。
方法说明：各 API 的参数需严格按照规范传入，尤其是 options 参数和回调函数的使用，避免因参数错误导致功能异常。
媒体处理说明：保存在线图片/视频时，插件会自动下载媒体文件，建议仅保存短视频和小体积图片，避免下载大文件导致应用卡顿或流量消耗过大。
错误处理：API 调用失败时，可通过 error 回调函数获取错误信息。
兼容性说明：确保项目中 Cordova 版本、DevEco Studio 版本及 OHOS SDK 版本符合兼容性要求，避免因版本不兼容导致功能异常。

1. 选择照片

API 说明

cordova.plugins.photoLibrary.getLibrary(success, error, options);

options 参数说明

thumbnailWidth：缩略图目标宽度
thumbnailHeight：缩略图目标高度
quality：图片压缩质量
includeImages：是否包含照片（布尔值）
includeVideos：是否包含视频（布尔值）

2. 选择相册

API 说明

cordova.plugins.photoLibrary.getAlbums(success, error)

参数说明

success：操作成功后的回调函数
error：操作失败后的回调函数

3. 获取缩略图

API 说明

cordova.plugins.photoLibrary.getThumbnail(photoIdOrLibraryItem, success, error, options)

参数说明

photoIdOrLibraryItem：通过 getLibrary 方法返回的图片对象，需传入单个图片
success：操作成功后的回调函数
error：操作失败后的回调函数
options：可选参数，包含 thumbnailWidth、thumbnailHeight、quality（同选择照片的 options 参数）

4. 获取照片

API 说明

cordova.plugins.photoLibrary.getPhoto(photoIdOrLibraryItem, success, error, options)

参数说明

photoIdOrLibraryItem：通过 getLibrary 方法返回的图片对象，需传入单个图片
success：操作成功后的回调函数
error：操作失败后的回调函数

5. 保存图片到相册

API 说明

cordova.plugins.photoLibrary.saveImage(url, album, success, error, options)

参数说明

url：图片 URL（可是沙箱路径或在线图片 URL）
album：相册名称，可传空字符串（使用默认相册）
success：操作成功后的回调函数
error：操作失败后的回调函数

6. 保存视频到相册

API 说明

cordova.plugins.photoLibrary.saveVideo(url, album, success, error, options)

参数说明

url：视频 URL（可是本地视频路径或在线视频 URL）
album：相册名称，可传空字符串（使用默认相册）
success：操作成功后的回调函数
error：操作失败后的回调函数

目录结构

cordova-plugin-photo-library       # [根目录] 相册插件项目根目录
├── src                            # [源码目录] 存放原生平台代码
│   └── main                       # [主目录] 主代码目录
│       ├── cpp                    # [C++ 目录] C++ 原生代码目录
│       │   └── ImagePicker        # [C++ 模块] 图片选择 C++ 模块文件夹
│       │       ├── PhotoLibrary.cpp # [C++ 实现] C++ 源文件，实现相册访问底层逻辑
│       │       └── PhotoLibrary.h   # [C++ 声明] C++ 头文件，定义相册接口
│       └── ets                    # [ArkTS 目录] ArkTS/ETS 代码目录
│           └── components         # [组件目录] 存放逻辑组件
│               └── MediaAction    # [TS 模块] 媒体操作逻辑文件夹
│                   └── MediaAction.ets # [ETS 文件] 媒体操作的 ArkTS 实现
├── www                            # [前端目录] 存放供 Web 端调用的 JS 接口文件
│   └── async                      # [JS 库目录] 存放异步控制流库
│       └── dist                   # [分发目录] 编译后的库文件
│           └── async.min.js       # [JS 文件] 压缩版的 async 库，用于处理异步操作
│   └── PhotoLibrary.js            # [JS 文件] 插件的主入口 JS 文件
├── .gitignore                     # [Git 配置] 指定 Git 版本控制中需要忽略的文件和目录
├── LICENSE                        # [许可证] 项目的开源协议或版权声明
├── OAT.xml                        # [门禁配置] OHOS 系统的安全或权限配置文件
├── package.json                   # [NPM 配置] 项目元数据，包含版本、依赖等信息
├── plugin.xml                     # [Cordova 配置] 核心配置文件，定义插件如何修改配置文件或注入逻辑
└── README.md                      # [说明文档] 项目的使用说明和功能介绍

贡献代码

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

许可证

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

官方资源

OHOS Cordova: https://gitcode.com/CPF-Cordova/cordova-plugin-photo-library

Android/iOS: https://npmjs.com/cordova-plugin-photo-library

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

cordova-plugin-photo-library

简介

支持平台

下载安装

从 npm 安装（推荐）

指定平台安装 ohos

从 GitCode 仓库安装

离线安装（本地包）

安装后验证

卸载

约束与限制

兼容性

OHOS 平台说明

使用示例

1. 选择照片

2. 选择相册

3. 获取缩略图

4. 获取照片

5. 保存图片到相册

6. 保存视频到相册

使用说明

1. 选择照片

API 说明

options 参数说明

2. 选择相册

API 说明

参数说明

3. 获取缩略图

API 说明

参数说明

4. 获取照片

API 说明

参数说明

5. 保存图片到相册

API 说明

参数说明

6. 保存视频到相册

API 说明

参数说明

目录结构

贡献代码

许可证

官方资源