{"_id":"@cordova-ohos/cordova-plugin-photo-library","_rev":"3-6417002a3971a4b61fda93fb2cb1b5c3","name":"@cordova-ohos/cordova-plugin-photo-library","dist-tags":{"latest":"2.3.2"},"versions":{"2.3.1":{"name":"@cordova-ohos/cordova-plugin-photo-library","version":"2.3.1","keywords":["cordova","photo-library","ecosystem:cordova","cordova-openharmony"],"author":{"name":"Huawei Device, Inc. Ltd. and","email":"马弓手"},"license":"Apache-2.0","_id":"@cordova-ohos/cordova-plugin-photo-library@2.3.1","maintainers":[{"name":"luqi_tan","email":"295099422@qq.com"},{"name":"wanpengsz","email":"wanpengsz@163.com"},{"name":"xkh111","email":"xukaihui11@163.com"}],"bugs":{"url":"https://gitcode.com/OpenHarmony-Cordova/cordova-plugin-photo-library/issues"},"dist":{"shasum":"9f66b4a267f4499863d45040c9d3e68230418b11","tarball":"https://registry.npmjs.org/@cordova-ohos/cordova-plugin-photo-library/-/cordova-plugin-photo-library-2.3.1.tgz","fileCount":10,"integrity":"sha512-2Qy8wshsKg5yQrTbIYUi0kG1atzMqk3hdr+/jKDCw/K2BQGYT7nGpWqRg3tdzRHQ66DgKMswqIMh04ySGT5gKw==","signatures":[{"sig":"MEUCIH4QuWf9A5YrxBbQAo+pyCKfzsGRmebN4djmv2ckrdPLAiEAmEmCvnN8tbFcf0QMsV6PnyiupxxH+0IImGSbXX7iykQ=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":119963},"cordova":{"id":"cordova-plugin-photo-library","platforms":["ohos"]},"engines":{"cordovaDependencies":{"2.3.1":{"hcordova":">=1.0.0","@cordova-ohos/ohos":">=2.0.0"}}},"gitHead":"4739e0e92c5555eab12d0210a99597178fd971c4","_npmUser":{"name":"wanpengsz","email":"wanpengsz@163.com"},"repository":{"url":"gitcode:OpenHarmony-Cordova/cordova-plugin-photo-library","type":"git"},"_npmVersion":"9.6.2","description":"Cordova photo-library Plugin","directories":{},"_nodeVersion":"20.16.0","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/cordova-plugin-photo-library_2.3.1_1773997463077_0.7374615409804928","host":"s3://npm-registry-packages-npm-production"}},"2.3.2":{"name":"@cordova-ohos/cordova-plugin-photo-library","version":"2.3.2","description":"Cordova Photo Library Plugin","cordova":{"id":"cordova-plugin-photo-library","platforms":["ohos"]},"repository":{"type":"git","url":"gitcode:CPF-Cordova/cordova-plugin-photo-library"},"bugs":{"url":"https://gitcode.com/CPF-Cordova/cordova-plugin-photo-library/issues"},"keywords":["cordova","photo-library","ecosystem:cordova","cordova-openharmony"],"engines":{"cordovaDependencies":{"2.3.2":{"@cordova-ohos/ohos":">=2.0.0","hcordova":">=1.0.0"}}},"author":{"name":"Huawei Device, Inc. Ltd. and","email":"马弓手"},"license":"Apache-2.0","_id":"@cordova-ohos/cordova-plugin-photo-library@2.3.2","gitHead":"1dd7d02e68a6cab2085001a4a6fa772020a21e33","_nodeVersion":"22.0.0","_npmVersion":"10.5.1","dist":{"integrity":"sha512-wmNwPDv38a9DUDoMdyyr201uv6fUQA9VKvNIt0TmxLzs4i1gHsIImdNxFyIOVBNBYXAp3l+LFQwS5LW4wnJ73A==","shasum":"75c836ff963ac524a8449056a341fa4a693c3574","tarball":"https://registry.npmjs.org/@cordova-ohos/cordova-plugin-photo-library/-/cordova-plugin-photo-library-2.3.2.tgz","fileCount":11,"unpackedSize":145063,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDl2PATDBIf6Z1a7oIFvoJVJJNMmACW/QKoLSJr0b3V9AIhAJ4VPX3p9pdnmXSByeUeA6A/uIZgezS7N5nKXJ716gw/"}]},"_npmUser":{"name":"luqi_tan","email":"295099422@qq.com"},"directories":{},"maintainers":[{"name":"luqi_tan","email":"295099422@qq.com"},{"name":"wanpengsz","email":"wanpengsz@163.com"},{"name":"xkh111","email":"xukaihui11@163.com"},{"name":"hcordova","email":"chenlihuiabc@163.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/cordova-plugin-photo-library_2.3.2_1785159243480_0.7361389151323599"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-20T09:04:23.012Z","modified":"2026-07-27T13:34:03.878Z","2.3.1":"2026-03-20T09:04:23.270Z","2.3.2":"2026-07-27T13:34:03.645Z"},"bugs":{"url":"https://gitcode.com/CPF-Cordova/cordova-plugin-photo-library/issues"},"author":{"name":"Huawei Device, Inc. Ltd. and","email":"马弓手"},"license":"Apache-2.0","keywords":["cordova","photo-library","ecosystem:cordova","cordova-openharmony"],"repository":{"type":"git","url":"gitcode:CPF-Cordova/cordova-plugin-photo-library"},"description":"Cordova Photo Library Plugin","maintainers":[{"name":"luqi_tan","email":"295099422@qq.com"},{"name":"wanpengsz","email":"wanpengsz@163.com"},{"name":"xkh111","email":"xukaihui11@163.com"},{"name":"hcordova","email":"chenlihuiabc@163.com"}],"readme":"# cordova-plugin-photo-library\r\n\r\n[](README.md)\r\n[](README.en.md)\r\n\r\n本项目基于 [cordova-plugin-photo-library@2.3.1](https://www.npmjs.com/package/cordova-plugin-photo-library/v/2.3.1) 开发，本文档重点阐述其在 OpenHarmony（OHOS）系统中的具体应用。\r\n\r\n- [cordova-plugin-photo-library](#cordova-plugin-photo-library)\r\n - [简介](#简介)\r\n - [支持平台](#支持平台)\r\n - [下载安装](#下载安装)\r\n - [从 npm 安装（推荐）](#从-npm-安装推荐)\r\n - [指定平台安装 ohos](#指定平台安装-ohos)\r\n - [从 GitCode 仓库安装](#从-gitcode-仓库安装)\r\n - [离线安装（本地包）](#离线安装本地包)\r\n - [安装后验证](#安装后验证)\r\n - [卸载](#卸载)\r\n - [约束与限制](#约束与限制)\r\n - [兼容性](#兼容性)\r\n - [OHOS 平台说明](#ohos-平台说明)\r\n - [使用示例](#使用示例)\r\n - [1. 选择照片](#1-选择照片)\r\n - [2. 选择相册](#2-选择相册)\r\n - [3. 获取缩略图](#3-获取缩略图)\r\n - [4. 获取照片](#4-获取照片)\r\n - [5. 保存图片到相册](#5-保存图片到相册)\r\n - [6. 保存视频到相册](#6-保存视频到相册)\r\n - [使用说明](#使用说明)\r\n - [1. 选择照片](#1-选择照片-1)\r\n - [API 说明](#api-说明)\r\n - [options 参数说明](#options-参数说明)\r\n - [2. 选择相册](#2-选择相册-1)\r\n - [API 说明](#api-说明-1)\r\n - [参数说明](#参数说明)\r\n - [3. 获取缩略图](#3-获取缩略图-1)\r\n - [API 说明](#api-说明-2)\r\n - [参数说明](#参数说明-1)\r\n - [4. 获取照片](#4-获取照片-1)\r\n - [API 说明](#api-说明-3)\r\n - [参数说明](#参数说明-2)\r\n - [5. 保存图片到相册](#5-保存图片到相册-1)\r\n - [API 说明](#api-说明-4)\r\n - [参数说明](#参数说明-3)\r\n - [6. 保存视频到相册](#6-保存视频到相册-1)\r\n - [API 说明](#api-说明-5)\r\n - [参数说明](#参数说明-4)\r\n - [目录结构](#目录结构)\r\n - [贡献代码](#贡献代码)\r\n - [许可证](#许可证)\r\n - [官方资源](#官方资源)\r\n\r\n## 简介\r\n\r\ncordova-plugin-photo-library 是一款专为 Cordova/PhoneGap 应用设计的手机相册交互插件，支持 iOS、Android 和 OHOS 平台实现相册照片/视频的读取、保存、删除、创建相册等核心功能，适配最新系统权限机制，适用于社交分享、内容编辑、媒体管理类应用场景。\r\n\r\n在 OHOS 系统中，访问相册权限属于 OpenHarmony 的管控权限，需要单独向 OHOS 申请，只有符合 OHOS 要求的应用才能使用相册权限，因此该插件不能完全操作相册的敏感数据，只具备相册的选择照片、视频、保存到相册照片、保存到相册视频的功能，具体使用方法参考下面的使用示例。\r\n\r\n## 支持平台\r\n\r\n- **Android**：API 19 及以上（Android 4.4+）\r\n\r\n- **iOS**：10.0 及以上\r\n\r\n- **OHOS**：5.0+\r\n\r\n## 下载安装\r\n\r\n通过 hcordova CLI 即可快速安装插件，支持从 npm 仓库或 GitCode 仓库获取。\r\n\r\n### 从 npm 安装（推荐）\r\n\r\n```bash\r\n# 使用 hcordova CLI 安装\r\n\r\n# 安装 hcordova 命令化工具\r\nnpm install -g hcordova\r\n\r\n# 全平台安装插件\r\nhcordova plugin add cordova-plugin-photo-library\r\n```\r\n\r\n### 指定平台安装 ohos\r\n\r\n仅为 OHOS 平台安装插件：\r\n\r\n```bash\r\n# 仅安装到 OHOS 平台\r\nhcordova plugin add cordova-plugin-photo-library --platform ohos\r\n\r\n# 指定版本安装\r\nhcordova plugin add cordova-plugin-photo-library@1.0.0 --platform ohos\r\n```\r\n\r\n### 从 GitCode 仓库安装\r\n\r\n仅为 OHOS 平台安装插件，推荐获取最新稳定版：\r\n\r\n```bash\r\n# 仅安装到 OHOS 平台\r\n\r\n# 默认分支安装\r\nhcordova plugin add https://gitcode.com/CPF-Cordova/cordova-plugin-photo-library.git --platform ohos\r\n\r\n# 指定标签/分支安装\r\nhcordova plugin add https://gitcode.com/CPF-Cordova/cordova-plugin-photo-library.git@develop --platform ohos\r\n```\r\n\r\n\r\n### 离线安装（本地包）\r\n\r\n适用于无网络环境，先下载插件包到本地，再执行离线安装：\r\n\r\n```bash\r\n# 下载插件包到本地（示例路径：~/Downloads/cordova-plugin-photo-library）\r\n# 执行离线安装\r\nhcordova plugin add ~/Downloads/cordova-plugin-photo-library --platform ohos\r\n```\r\n\r\n### 安装后验证\r\n\r\n安装完成后，可通过以下命令验证插件是否成功添加到项目中：\r\n\r\n```bash\r\n# 查看已安装的插件列表，若包含本插件 ID 则表示插件已成功安装\r\nhcordova plugin list\r\n```\r\n\r\n\r\n### 卸载\r\n\r\n```bash\r\n# Cordova CLI 全平台卸载\r\nhcordova plugin remove cordova-plugin-photo-library \r\n\r\n# 指定平台卸载\r\nhcordova plugin remove cordova-plugin-photo-library --platform ohos\r\n```\r\n\r\n## 约束与限制\r\n### 兼容性\r\n\r\n支持：\r\n\r\n| 项目 | 版本/信息 |\r\n|-----|--------|\r\n| SDK | API12+ |\r\n| IDE | DevEco Studio: 5.0+ |\r\n| ROM | 5.1+ |\r\n| Emulator | OpenHarmony 6.0+ |\r\n\r\n在以下版本中已测试通过：\r\n\r\n| 项目 | 版本/信息 |\r\n|-----|--------|\r\n| @cordova-ohos/ohos | 14.0.1-ohos-14.0.1 |\r\n| SDK | 5.0.0(12) |\r\n| IDE | DevEco Studio: 6.0.13.200 |\r\n| ROM | 5.1.0.120 SP3 |\r\n| Emulator | OpenHarmony 6.0.1(21) |\r\n\r\n### OHOS 平台说明\r\n\r\n在 OHOS 系统中，访问相册权限属于 OpenHarmony 的管控权限，需要单独向 OHOS 申请，只有符合 OHOS 要求的应用才能使用相册权限。本插件仅开放相册基础操作权限，可实现照片/视频选择、保存功能，无法完全操作相册敏感数据，具体操作需遵循 OHOS 权限管控规则。\r\n\r\n## 使用示例\r\n\r\n插件挂载在 `cordova.plugins.photoLibrary` 对象上，所有方法均支持回调函数语法，以下为各核心功能的纯代码使用示例，可直接复制到项目中使用（API 及参数详情见「使用说明」章节）。\r\n\r\n### 1. 选择照片\r\n\r\n```javascript\r\nfunction selectPhotoFromAlbums() {\r\n cordova.plugins.photoLibrary.getLibrary(\r\n function (result) {\r\n let library = result.library;\r\n photos = library;\r\n // Here we have the library as array data:image/bmp;base64,\r\n let imgInfo = \"\";\r\n for(let i=0; i\";\r\n }\r\n document.getElementById(\"libraryInfo\").innerHTML = imgInfo;\r\n },\r\n function (err) {\r\n console.log('Error occurred');\r\n },\r\n { // optional options\r\n thumbnailWidth: 512,\r\n thumbnailHeight: 384,\r\n quality: 0.8,\r\n includeImages:true, \r\n includeVideos:false\r\n }\r\n );\r\n}\r\n```\r\n\r\n### 2. 选择相册\r\n\r\n```javascript\r\nfunction selectAlbums() {\r\n cordova.plugins.photoLibrary.getAlbums(\r\n function (albums) {\r\n document.getElementById(\"albumsInfo\").innerHTML = JSON.stringify(albums);\r\n },\r\n function (err) { }\r\n );\r\n}\r\n```\r\n\r\n### 3. 获取缩略图\r\n\r\n```javascript\r\nfunction getThumbnail() {\r\n if(photos && photos.length > 0) {\r\n cordova.plugins.photoLibrary.getThumbnail(photos[0],\r\n function (thumbnail) {\r\n document.getElementById(\"thumbnailInfo\").src = window.URL.createObjectURL(thumbnail);\r\n },\r\n function (err) { }\r\n );\r\n }\r\n}\r\n```\r\n\r\n### 4. 获取照片\r\n\r\n```javascript\r\nfunction getLibraryPhoto() {\r\n if(photos && photos.length > 0) {\r\n cordova.plugins.photoLibrary.getPhoto(photos[0],\r\n function (photo) {\r\n document.getElementById(\"photoInfo\").src = window.URL.createObjectURL(photo);\r\n },\r\n function (err) { }\r\n );\r\n }\r\n}\r\n```\r\n\r\n### 5. 保存图片到相册\r\n\r\n```javascript\r\n// 通过 getLibrary 选择图片保存到相册\r\nfunction saveLibraryPhoto() {\r\n if(photos && photos.length > 0) {\r\n cordova.plugins.photoLibrary.saveImage(photos[0].uri, \"\",\r\n function (photo) {\r\n document.getElementById(\"saveInfo1\").innerHTML = \"保存成功\";\r\n },\r\n function (err) { }\r\n );\r\n }\r\n}\r\n// 保存在线图片到相册，图片会自动下载\r\nfunction saveLibraryPhoto2() {\r\n cordova.plugins.photoLibrary.saveImage(\"https://cordova.apache.org/static/img/cordova_bot.png\", \"\",\r\n function (photo) {\r\n document.getElementById(\"saveInfo2\").innerHTML = \"保存成功\";\r\n },\r\n function (err) { }\r\n );\r\n}\r\n```\r\n\r\n### 6. 保存视频到相册\r\n\r\n```javascript\r\n// 通过 getLibrary 选择的视频保存到相册\r\nfunction saveLibraryVideo() {\r\n if(photos && photos.length > 0) {\r\n cordova.plugins.photoLibrary.saveVideo(photos[0].uri, \"\",\r\n function (photo) {\r\n document.getElementById(\"saveInfo3\").innerHTML = \"保存成功\";\r\n },\r\n function (err) { }\r\n );\r\n }\r\n}\r\n\r\n// 保存在线视频，视频会自动下载，最好只保存短视频，不要保存大视频\r\nfunction saveLibraryVideo2() {\r\n cordova.plugins.photoLibrary.saveVideo(\"https://example.com/SVID_20250928_140357_1.mp4\", \"\",\r\n function (photo) {\r\n document.getElementById(\"saveInfo4\").innerHTML = \"保存成功\";\r\n },\r\n function (err) { }\r\n );\r\n}\r\n```\r\n\r\n## 使用说明\r\n\r\n1. 插件调用：所有 API 均通过全局对象 `cordova.plugins.photoLibrary` 调用，无需额外引入，直接调用对应方法即可。\r\n2. 方法说明：各 API 的参数需严格按照规范传入，尤其是 options 参数和回调函数的使用，避免因参数错误导致功能异常。\r\n3. 媒体处理说明：保存在线图片/视频时，插件会自动下载媒体文件，建议仅保存短视频和小体积图片，避免下载大文件导致应用卡顿或流量消耗过大。\r\n4. 错误处理：API 调用失败时，可通过 error 回调函数获取错误信息。\r\n5. 兼容性说明：确保项目中 Cordova 版本、DevEco Studio 版本及 OHOS SDK 版本符合兼容性要求，避免因版本不兼容导致功能异常。\r\n\r\n### 1. 选择照片\r\n\r\n#### API 说明\r\n\r\ncordova.plugins.photoLibrary.getLibrary(success, error, options);\r\n\r\n#### options 参数说明\r\n\r\n- **thumbnailWidth**：缩略图目标宽度\r\n\r\n- **thumbnailHeight**：缩略图目标高度\r\n\r\n- **quality**：图片压缩质量\r\n\r\n- **includeImages**：是否包含照片（布尔值）\r\n\r\n- **includeVideos**：是否包含视频（布尔值）\r\n\r\n### 2. 选择相册\r\n\r\n#### API 说明\r\n\r\ncordova.plugins.photoLibrary.getAlbums(success, error)\r\n\r\n#### 参数说明\r\n\r\n- **success**：操作成功后的回调函数\r\n\r\n- **error**：操作失败后的回调函数\r\n\r\n### 3. 获取缩略图\r\n\r\n#### API 说明\r\n\r\ncordova.plugins.photoLibrary.getThumbnail(photoIdOrLibraryItem, success, error, options)\r\n\r\n#### 参数说明\r\n\r\n- **photoIdOrLibraryItem**：通过 getLibrary 方法返回的图片对象，需传入单个图片\r\n\r\n- **success**：操作成功后的回调函数\r\n\r\n- **error**：操作失败后的回调函数\r\n\r\n- **options**：可选参数，包含 thumbnailWidth、thumbnailHeight、quality（同选择照片的 options 参数）\r\n\r\n### 4. 获取照片\r\n\r\n#### API 说明\r\n\r\ncordova.plugins.photoLibrary.getPhoto(photoIdOrLibraryItem, success, error, options)\r\n\r\n#### 参数说明\r\n\r\n- **photoIdOrLibraryItem**：通过 getLibrary 方法返回的图片对象，需传入单个图片\r\n\r\n- **success**：操作成功后的回调函数\r\n\r\n- **error**：操作失败后的回调函数\r\n\r\n### 5. 保存图片到相册\r\n\r\n#### API 说明\r\n\r\ncordova.plugins.photoLibrary.saveImage(url, album, success, error, options)\r\n\r\n#### 参数说明\r\n\r\n- **url**：图片 URL（可是沙箱路径或在线图片 URL）\r\n\r\n- **album**：相册名称，可传空字符串（使用默认相册）\r\n\r\n- **success**：操作成功后的回调函数\r\n\r\n- **error**：操作失败后的回调函数\r\n\r\n### 6. 保存视频到相册\r\n\r\n#### API 说明\r\n\r\ncordova.plugins.photoLibrary.saveVideo(url, album, success, error, options)\r\n\r\n#### 参数说明\r\n\r\n- **url**：视频 URL（可是本地视频路径或在线视频 URL）\r\n\r\n- **album**：相册名称，可传空字符串（使用默认相册）\r\n\r\n- **success**：操作成功后的回调函数\r\n\r\n- **error**：操作失败后的回调函数\r\n\r\n\r\n## 目录结构\r\n\r\n```\r\ncordova-plugin-photo-library # [根目录] 相册插件项目根目录\r\n├── src # [源码目录] 存放原生平台代码\r\n│ └── main # [主目录] 主代码目录\r\n│ ├── cpp # [C++ 目录] C++ 原生代码目录\r\n│ │ └── ImagePicker # [C++ 模块] 图片选择 C++ 模块文件夹\r\n│ │ ├── PhotoLibrary.cpp # [C++ 实现] C++ 源文件，实现相册访问底层逻辑\r\n│ │ └── PhotoLibrary.h # [C++ 声明] C++ 头文件，定义相册接口\r\n│ └── ets # [ArkTS 目录] ArkTS/ETS 代码目录\r\n│ └── components # [组件目录] 存放逻辑组件\r\n│ └── MediaAction # [TS 模块] 媒体操作逻辑文件夹\r\n│ └── MediaAction.ets # [ETS 文件] 媒体操作的 ArkTS 实现\r\n├── www # [前端目录] 存放供 Web 端调用的 JS 接口文件\r\n│ └── async # [JS 库目录] 存放异步控制流库\r\n│ └── dist # [分发目录] 编译后的库文件\r\n│ └── async.min.js # [JS 文件] 压缩版的 async 库，用于处理异步操作\r\n│ └── PhotoLibrary.js # [JS 文件] 插件的主入口 JS 文件\r\n├── .gitignore # [Git 配置] 指定 Git 版本控制中需要忽略的文件和目录\r\n├── LICENSE # [许可证] 项目的开源协议或版权声明\r\n├── OAT.xml # [门禁配置] OHOS 系统的安全或权限配置文件\r\n├── package.json # [NPM 配置] 项目元数据，包含版本、依赖等信息\r\n├── plugin.xml # [Cordova 配置] 核心配置文件，定义插件如何修改配置文件或注入逻辑\r\n└── README.md # [说明文档] 项目的使用说明和功能介绍\r\n```\r\n\r\n## 贡献代码\r\n\r\n使用过程中发现任何问题都可以提 [Issue](https://gitcode.com/CPF-Cordova/cordova-plugin-photo-library/issues) ，当然也非常欢迎发 [PR](https://gitcode.com/CPF-Cordova/cordova-plugin-photo-library/pulls) 共建。\r\n\r\n## 许可证\r\n\r\n本插件基于 **Apache License 2.0** 开源，详见 [LICENSE](LICENSE) 文件。\r\n\r\n## 官方资源\r\n\r\nOHOS Cordova: [https://gitcode.com/CPF-Cordova/cordova-plugin-photo-library](https://gitcode.com/CPF-Cordova/cordova-plugin-photo-library)\r\n\r\nAndroid/iOS: [https://npmjs.com/cordova-plugin-photo-library](https://npmjs.com/cordova-plugin-photo-library)\r\n","readmeFilename":"README.md"}