{"_id":"@cordova-ohos/org.devgeeks.canvas2imageplugin","_rev":"3-3e6e71c8f473cd28599af2b649bd5687","name":"@cordova-ohos/org.devgeeks.canvas2imageplugin","dist-tags":{"latest":"1.0.2"},"versions":{"1.0.1":{"name":"@cordova-ohos/org.devgeeks.canvas2imageplugin","version":"1.0.1","keywords":["cordova","canvas2image","ecosystem:cordova","cordova-openharmony"],"author":{"name":"Huawei Device, Inc. Ltd. and","email":"马弓手"},"license":"Apache-2.0","_id":"@cordova-ohos/org.devgeeks.canvas2imageplugin@1.0.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/org.devgeeks.canvas2imageplugin/issues"},"dist":{"shasum":"813f837ea8a2104f1d1d20b999ed08cce8da83dc","tarball":"https://registry.npmjs.org/@cordova-ohos/org.devgeeks.canvas2imageplugin/-/org.devgeeks.canvas2imageplugin-1.0.1.tgz","fileCount":5,"integrity":"sha512-2RQQLNBCqXWU0Wca9FVxOaX6cPkcs8fmgnsmaAjQG6Ol6W3NqU2Cs0okmMgjbYMFt7zH9jjdhRF15a14DIclgg==","signatures":[{"sig":"MEQCIF+qlfqvNVf4dNL+r/wf6HxBnmvN4ZdmXKKqq3zCrvFnAiBpPtms8UL3StjL6qk4jtjie+xUVptHiISiiabjEfdQSQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":21285},"cordova":{"id":"org.devgeeks.canvas2imageplugin","platforms":["ohos"]},"engines":{"cordovaDependencies":{"1.0.1":{"hcordova":">=1.0.0","@cordova-ohos/ohos":">=2.0.0"}}},"gitHead":"398313f4643fea0651d277a552ef55ed0b38f311","_npmUser":{"name":"luqi_tan","email":"295099422@qq.com"},"repository":{"url":"gitcode:OpenHarmony-Cordova/org.devgeeks.canvas2imageplugin","type":"git"},"_npmVersion":"10.5.1","description":"Cordova canvas2image Plugin","directories":{},"_nodeVersion":"22.0.0","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/org.devgeeks.canvas2imageplugin_1.0.1_1774229244847_0.6648408223987599","host":"s3://npm-registry-packages-npm-production"}},"1.0.2":{"name":"@cordova-ohos/org.devgeeks.canvas2imageplugin","version":"1.0.2","description":"Cordova canvas2image Plugin","cordova":{"id":"org.devgeeks.canvas2imageplugin","platforms":["ohos"]},"repository":{"type":"git","url":"gitcode:CPF-Cordova/org.devgeeks.canvas2imageplugin"},"bugs":{"url":"https://gitcode.com/CPF-Cordova/org.devgeeks.canvas2imageplugin/issues"},"keywords":["cordova","canvas2image","ecosystem:cordova","cordova-openharmony"],"engines":{"cordovaDependencies":{"1.0.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/org.devgeeks.canvas2imageplugin@1.0.2","gitHead":"4e3730414861085f3f6cd659283e4ade1d306944","_nodeVersion":"22.0.0","_npmVersion":"10.5.1","dist":{"integrity":"sha512-S/DdLmJvK8891D4G7EpSN7ogxMF0h6fG1aB6NzZ0/gdwl/xRTVpT1Q4ktYDbR350A6xV1dgS7TQEnxLi/jDu6g==","shasum":"03db0a9d1fe6b5136ee8015e500a81b9e9a5edde","tarball":"https://registry.npmjs.org/@cordova-ohos/org.devgeeks.canvas2imageplugin/-/org.devgeeks.canvas2imageplugin-1.0.2.tgz","fileCount":6,"unpackedSize":50647,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDo3/dhNhXb6xaz4nH/tuJeiUVQSWhoAZw55zNx41qBOAIhAMLURNMfVYP9u8q4fiIq/k6lZLHwGc/fy/7K/rYrIamy"}]},"_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/org.devgeeks.canvas2imageplugin_1.0.2_1785149532006_0.31871795506872647"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-23T01:27:24.763Z","modified":"2026-07-27T10:52:12.613Z","1.0.1":"2026-03-23T01:27:24.983Z","1.0.2":"2026-07-27T10:52:12.132Z"},"bugs":{"url":"https://gitcode.com/CPF-Cordova/org.devgeeks.canvas2imageplugin/issues"},"author":{"name":"Huawei Device, Inc. Ltd. and","email":"马弓手"},"license":"Apache-2.0","keywords":["cordova","canvas2image","ecosystem:cordova","cordova-openharmony"],"repository":{"type":"git","url":"gitcode:CPF-Cordova/org.devgeeks.canvas2imageplugin"},"description":"Cordova canvas2image 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":"# <center>org.devgeeks.canvas2imageplugin</center>\r\n\r\n[![zh-CN](https://img.shields.io/badge/lang-中文-blue.svg)](README.md)\r\n[![en](https://img.shields.io/badge/lang-English-blue.svg)](README.en.md)\r\n\r\n本项目基于 [org.devgeeks.canvas2imageplugin@1.0.1](https://www.npmjs.com/package/org.devgeeks.canvas2imageplugin/v/1.0.1) 开发，本文档重点阐述其在 OpenHarmony（OHOS）系统中的具体应用，本项目依赖于 cordova-plugin-canvas2image 项目，并无功能的改进和升级，只为 Android/iOS 项目移植到 OHOS 平台，提供接口的一致性。\r\n\r\n- [org.devgeeks.canvas2imageplugin](#orgdevgeekscanvas2imageplugin)\r\n  - [简介](#简介)\r\n  - [功能特性](#功能特性)\r\n  - [支持平台](#支持平台)\r\n  - [前置准备](#前置准备)\r\n  - [下载安装](#下载安装)\r\n    - [前提条件](#前提条件)\r\n    - [基础安装（推荐，从 npm 仓库）](#基础安装推荐从-npm-仓库)\r\n    - [指定版本安装](#指定版本安装)\r\n    - [从 GitCode 安装（开发版）](#从-gitcode-安装开发版)\r\n    - [离线安装（本地包）](#离线安装本地包)\r\n    - [安装后验证](#安装后验证)\r\n    - [卸载插件](#卸载插件)\r\n  - [约束与限制](#约束与限制)\r\n    - [兼容性](#兼容性)\r\n  - [使用示例](#使用示例)\r\n    - [基础使用（保存 Canvas 到相册）](#基础使用保存-canvas-到相册)\r\n  - [使用说明](#使用说明)\r\n    - [1. 核心 API 说明](#1-核心-api-说明)\r\n      - [1.1 保存 Canvas 到相册（核心 API）](#11-保存-canvas-到相册核心-api)\r\n    - [2. 常见问题（FAQ）](#2-常见问题faq)\r\n      - [Q1: 调用 saveImageDataToLibrary 后提示权限不足，保存失败怎么办？](#q1-调用-saveimagedatatolibrary-后提示权限不足保存失败怎么办)\r\n      - [Q2: 保存图片后，在系统相册中找不到怎么办？](#q2-保存图片后在系统相册中找不到怎么办)\r\n      - [Q3: 导出的图片为空白，怎么办？](#q3-导出的图片为空白怎么办)\r\n      - [Q4: 保存 JPG 图片时，透明背景变成白色，怎么办？](#q4-保存-jpg-图片时透明背景变成白色怎么办)\r\n    - [3. 注意事项](#3-注意事项)\r\n  - [目录结构](#目录结构)\r\n  - [贡献代码](#贡献代码)\r\n  - [许可证](#许可证)\r\n  - [官方资源](#官方资源)\r\n\r\n\r\n## 简介\r\n\r\norg.devgeeks.canvas2imageplugin 是一款高效、跨平台的 Canvas 转图片解决方案，专为 Cordova/PhoneGap 应用设计，核心功能是将 HTML5 Canvas 元素导出为 PNG/JPG 格式图片，并保存到设备相册，适配移动端各类图片处理场景（如截图保存、画布内容导出、自定义图片生成等）。本文档仅介绍该插件在 OHOS 系统中的应用、安装、配置、使用方法及注意事项，帮助开发者快速集成 Canvas 转图片功能，重点突出 OHOS 平台的适配特性与使用规范。\r\n\r\n## 功能特性\r\n\r\n- **高效转码**：快速将 HTML5 Canvas 元素转为 PNG/JPG 格式，转码速度快、画质无损，适配移动端性能需求\r\n\r\n- **跨平台兼容**：完美支持 Android、iOS、OHOS 三大主流移动平台，适配各系统最新版本，重点适配 OHOS 5.0+ 系统\r\n\r\n- **简洁易用**：提供极简 API 接口，仅需一行代码即可完成 Canvas 转图片及保存操作，降低集成难度\r\n\r\n- **完整回调支持**：提供成功、失败回调函数，可实时获取操作结果，便于异常处理和用户反馈\r\n\r\n- **轻量无依赖**：插件体积小巧，无额外第三方依赖，不占用过多应用内存，不影响应用运行性能\r\n\r\n\r\n## 支持平台\r\n\r\n- **OHOS**（5.0+，适配系统沙箱机制，支持 Canvas 转 PNG/JPG、本地保存，需申请相册写入和文件访问权限，兼容 DevEco Studio 5.0+）\r\n\r\n- **Android**（适配主流版本，支持全量功能，可保存到相册或自定义路径，无特殊权限限制）\r\n\r\n- **iOS**（适配主流版本，支持全量功能，遵循 iOS 沙箱机制，保存到系统相册需申请权限）\r\n\r\n## 前置准备\r\n\r\n在集成插件前，需确保开发环境满足基础要求，完成必要的前置配置，具体步骤如下：\r\n\r\n- 已安装 Node.js（v14.0.0 及以上）和 npm（v6.0.0 及以上），可通过 `node -v` 和 `npm -v` 命令验证版本；\r\n\r\n- 已创建 Cordova 项目（若尚未创建，可通过 `cordova create canvas2ImageApp com.example.canvas2imageapp Canvas2ImageApp` 命令快速创建）；\r\n\r\n- 确保项目适配 OHOS 5.0 及以上版本，DevEco Studio 版本为 5.0+，SDK 为 API12+，避免因版本过低导致插件功能异常；\r\n\r\n## 下载安装\r\n\r\n通过 HCordova CLI 即可快速安装插件，支持全平台安装或指定 OHOS 平台安装，安装流程简洁高效，安装后可通过命令验证安装结果。\r\n\r\n### 前提条件\r\n\r\n安装插件前，需先安装 HCordova CLI，执行以下命令安装：\r\n\r\n```bash\r\nnpm install -g hcordova\r\n```\r\n\r\n### 基础安装（推荐，从 npm 仓库）\r\n\r\n在 Cordova 项目根目录执行以下命令，插件会自动处理各平台依赖与基础配置，默认安装最新稳定版本，支持全平台或指定 OHOS 平台安装：\r\n\r\n```bash\r\n# 安装最新稳定版（全平台）\r\nhcordova plugin add org.devgeeks.canvas2imageplugin\r\n\r\n# 指定 OHOS 平台安装（推荐，仅适配 OHOS 系统）\r\nhcordova plugin add org.devgeeks.canvas2imageplugin --platform ohos\r\n```\r\n\r\n### 指定版本安装\r\n\r\n若需使用特定版本插件，可指定版本号安装，仅适配 OHOS 平台：\r\n\r\n```bash\r\n# 安装特定版本（示例：1.0.0 版本，仅 OHOS 平台）\r\nhcordova plugin add org.devgeeks.canvas2imageplugin@1.0.0 --platform ohos\r\n```\r\n\r\n### 从 GitCode 安装（开发版）\r\n\r\n若需使用开发中的最新功能，可直接从 GitCode 仓库安装，仅适配 OHOS 平台：\r\n\r\n```bash\r\n# 仅支持 OHOS 平台\r\nhcordova plugin add https://gitcode.com/CPF-Cordova/org.devgeeks.canvas2imageplugin.git --platform ohos\r\n\r\n# 指定标签/分支安装\r\nhcordova plugin add https://gitcode.com/CPF-Cordova/org.devgeeks.canvas2imageplugin.git@develop --platform ohos\r\n```\r\n\r\n### 离线安装（本地包）\r\n\r\n适用于无网络环境，先下载插件包到本地，再执行离线安装：\r\n\r\n```bash\r\n# 下载插件包到本地（示例路径：../Downloads/org.devgeeks.canvas2imageplugin）\r\n# 执行离线安装\r\nhcordova plugin add ../Downloads/org.devgeeks.canvas2imageplugin  --platform ohos\r\n```\r\n\r\n\r\n### 安装后验证\r\n\r\n安装完成后，可通过以下命令验证插件是否成功添加到项目中：\r\n\r\n```bash\r\n# 查看已安装的插件列表\r\n# 若输出结果包含 org.devgeeks.canvas2imageplugin 则表示插件已成功安装\r\nhcordova plugin list\r\n```\r\n\r\n### 卸载插件\r\n\r\n如需移除插件，执行以下命令即可清理相关配置与依赖，支持全平台卸载或指定 OHOS 平台卸载：\r\n\r\n```bash\r\n# 全平台卸载插件\r\nhcordova plugin rm org.devgeeks.canvas2imageplugin\r\n\r\n# 指定 OHOS 平台卸载\r\nhcordova plugin rm org.devgeeks.canvas2imageplugin --platform ohos\r\n```\r\n\r\n## 约束与限制\r\n\r\n- 平台限制：OHOS 平台仅支持 5.0 及以上版本，低于该版本的系统可能出现转码失败、图片保存异常等问题；\r\n  \r\n- 本项目依赖 [cordova-plugin-canvas2image](https://www.npmjs.com/package/cordova-plugin-canvas2image) 实现所有功能，如果您是新项目推荐使用 [cordova-plugin-canvas2image](https://www.npmjs.com/package/cordova-plugin-canvas2image) 插件，本项目的存在主要是为兼容 Android/iOS 项目的移植。\r\n\r\n- API 调用时机：所有 JavaScript API 必须在 `deviceready` 事件触发后调用，否则会出现 `window.canvas2ImagePlugin` 对象未定义、调用失败等异常；\r\n\r\n- Canvas 元素限制：需确保调用 API 时，Canvas 元素已渲染完成（避免未绘制完成就执行转码），否则会导出空白图片；\r\n\r\n- 图片大小限制：建议 Canvas 转码后的图片大小不超过 10MB，过大图片会导致转码耗时过长、保存失败或占用过多系统资源；\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## 使用示例\r\n\r\n插件通过全局对象 `window.canvas2ImagePlugin` 暴露核心 API，所有操作均为异步执行，通过回调函数处理结果。所有 API 需在 `deviceready` 事件触发后调用。以下为 OHOS 平台核心功能的完整使用示例，可直接复制到项目中使用，重点注意权限配置和沙箱路径配置。\r\n\r\n### 基础使用（保存 Canvas 到相册）\r\n\r\n将 Canvas 元素绘制完成后，调用核心 API 保存图片到系统相册，适配 OHOS 平台权限要求：\r\n\r\n```js\r\n// 等待 Cordova 环境就绪\r\ndocument.addEventListener('deviceready', function() {\r\n    // 1. 先绘制 Canvas（示例：绘制简单图形）\r\n    var canvas = document.getElementById('myCanvas');\r\n    var ctx = canvas.getContext('2d');\r\n    ctx.fillStyle = '#ff0000';\r\n    ctx.fillRect(10, 10, 100, 100); // 绘制红色矩形\r\n    ctx.fillStyle = '#000000';\r\n    ctx.font = '20px Arial';\r\n    ctx.fillText('Canvas 转图片示例', 10, 130); // 绘制文字\r\n\r\n    // 2. 保存 Canvas 到系统相册\r\n    function savePhotoCanvas() {\r\n            window.canvas2ImagePlugin.saveImageDataToLibrary(\r\n            function(msg){\r\n                document.getElementById(\"canvasInfo\").innerHTML = msg;\r\n                console.log(msg);\r\n            },\r\n            function(err){\r\n                console.log(err);\r\n            },\r\n            document.getElementById('myCanvas')\r\n        );\r\n    }\r\n\r\n    // 绑定按钮点击事件，触发保存操作\r\n    document.getElementById('saveBtn').addEventListener('click', savePhotoCanvas);\r\n}, false);\r\n```\r\n\r\n## 使用说明\r\n\r\n以下为插件使用的核心说明，包括 API 详解、参数说明、常见问题及注意事项等，帮助开发者快速上手并避免异常，重点突出 OHOS 平台特性与限制。\r\n\r\n### 1. 核心 API 说明\r\n\r\n插件仅暴露一个核心 API，挂载在全局 `window.canvas2ImagePlugin` 对象下，无需额外引入，所有操作均为异步执行，通过回调函数处理结果。所有 API 均需在 `deviceready` 事件触发后调用。\r\n\r\n#### 1.1 保存 Canvas 到相册（核心 API）\r\n\r\n功能：将 HTML5 Canvas 元素转码为指定格式（PNG/JPG），并保存到设备本地指定路径（沙箱路径或系统相册）。\r\n\r\n语法：\r\n\r\n```javascript\r\nwindow.canvas2ImagePlugin.saveImageDataToLibrary(successCallback, errorCallback, canvasElement);\r\n```\r\n\r\n参数说明：\r\n\r\n- successCallback：成功回调，可选，参数为 msg（保存成功信息，包含保存路径），触发即表示图片保存成功；\r\n\r\n- errorCallback：失败回调，可选，参数为 err（错误信息，包含错误原因），保存失败时触发；\r\n\r\n- canvasElement：目标 Canvas 元素，必填，需传入已渲染完成的 Canvas DOM 对象；\r\n\r\n### 2. 常见问题（FAQ）\r\n\r\n#### Q1: 调用 saveImageDataToLibrary 后提示权限不足，保存失败怎么办？\r\n\r\n1. 检查权限：保存相册时，系统会弹窗是否确保保存相册，由用户点击保存相册，才能正确保存。\r\n\r\n#### Q2: 保存图片后，在系统相册中找不到怎么办？\r\n\r\n1. 刷新相册：OHOS 系统可能存在相册刷新延迟，可手动刷新相册或重启应用后查看。\r\n\r\n#### Q3: 导出的图片为空白，怎么办？\r\n\r\n1. 检查 Canvas 渲染：确保调用 API 时，Canvas 元素已绘制完成，避免在绘制前执行转码；\r\n\r\n2. 检查 Canvas 尺寸：避免 Canvas 尺寸为 0（宽高均为 0），确保 Canvas 有实际绘制内容；\r\n\r\n3. 检查 API 调用时机：确保在 `deviceready` 事件触发后调用 API，避免 Canvas 元素未加载完成。\r\n\r\n#### Q4: 保存 JPG 图片时，透明背景变成白色，怎么办？\r\n\r\nJPG 格式本身不支持透明背景，这是格式特性，解决方案如下：\r\n\r\n1. 若需保留透明背景，将图片格式改为 PNG；\r\n\r\n2. 若必须使用 JPG 格式，可在绘制 Canvas 时，先绘制一个纯色背景（如白色、黑色），再绘制具体内容。\r\n\r\n### 3. 注意事项\r\n\r\n- API 调用时机：所有 JavaScript API 必须在 `deviceready` 事件触发后调用，否则会出现 `window.canvas2ImagePlugin` 对象未定义、调用失败等异常。\r\n\r\n- Canvas 渲染：调用 API 前，务必确保 Canvas 元素已渲染完成，否则会导出空白图片；避免在 Canvas 绘制过程中执行转码操作。\r\n\r\n## 目录结构\r\n\r\n```\r\norg.devgeeks.canvas2imageplugin      # [根目录] Canvas 转图片插件项目根目录\r\n├── .gitignore                       # [配置] Git 版本控制忽略文件配置\r\n├── LICENSE                          # [文本] 开源许可证文件\r\n├── OAT.xml                          # [配置] 门禁配置文件\r\n├── package.json                     # [配置] NPM 包配置文件，定义插件依赖、版本和脚本\r\n├── plugin.xml                       # [配置] Cordova 插件核心配置文件，定义插件 ID、平台映射和权限\r\n└── README.md                        # [文档] 项目说明文档，通常包含安装和使用方法\r\n```\r\n\r\n## 贡献代码\r\n\r\n使用过程中发现任何问题都可以提 [Issue](https://gitcode.com/CPF-Cordova/org.devgeeks.canvas2imageplugin/issues) ，当然也非常欢迎发 [PR](https://gitcode.com/CPF-Cordova/org.devgeeks.canvas2imageplugin/pulls) 共建。\r\n\r\n## 许可证\r\n\r\n本插件基于 **Apache License 2.0** 开源，详见 [LICENSE](LICENSE) 文件。\r\n\r\n## 官方资源\r\n\r\n- Android 和 iOS：[org.devgeeks.canvas2imageplugin 官方指南](https://www.npmjs.com/package/org.devgeeks.canvas2imageplugin)\r\n\r\n- GitCode 仓库：[https://gitcode.com/CPF-Cordova/org.devgeeks.canvas2imageplugin](https://gitcode.com/CPF-Cordova/org.devgeeks.canvas2imageplugin)\r\n","readmeFilename":"README.md"}