@cordova-ohos/org.devgeeks.canvas2imageplugin

v1.0.2

Published

23 days ago

Cordova canvas2image Plugin

0High
0Medium
0Low

cordova canvas2image ecosystem:cordova cordova-openharmony

org.devgeeks.canvas2imageplugin

本项目基于 [email protected] 开发，本文档重点阐述其在 OpenHarmony（OHOS）系统中的具体应用，本项目依赖于 cordova-plugin-canvas2image 项目，并无功能的改进和升级，只为 Android/iOS 项目移植到 OHOS 平台，提供接口的一致性。

org.devgeeks.canvas2imageplugin

简介

org.devgeeks.canvas2imageplugin 是一款高效、跨平台的 Canvas 转图片解决方案，专为 Cordova/PhoneGap 应用设计，核心功能是将 HTML5 Canvas 元素导出为 PNG/JPG 格式图片，并保存到设备相册，适配移动端各类图片处理场景（如截图保存、画布内容导出、自定义图片生成等）。本文档仅介绍该插件在 OHOS 系统中的应用、安装、配置、使用方法及注意事项，帮助开发者快速集成 Canvas 转图片功能，重点突出 OHOS 平台的适配特性与使用规范。

功能特性

高效转码：快速将 HTML5 Canvas 元素转为 PNG/JPG 格式，转码速度快、画质无损，适配移动端性能需求
跨平台兼容：完美支持 Android、iOS、OHOS 三大主流移动平台，适配各系统最新版本，重点适配 OHOS 5.0+ 系统
简洁易用：提供极简 API 接口，仅需一行代码即可完成 Canvas 转图片及保存操作，降低集成难度
完整回调支持：提供成功、失败回调函数，可实时获取操作结果，便于异常处理和用户反馈
轻量无依赖：插件体积小巧，无额外第三方依赖，不占用过多应用内存，不影响应用运行性能

支持平台

OHOS（5.0+，适配系统沙箱机制，支持 Canvas 转 PNG/JPG、本地保存，需申请相册写入和文件访问权限，兼容 DevEco Studio 5.0+）
Android（适配主流版本，支持全量功能，可保存到相册或自定义路径，无特殊权限限制）
iOS（适配主流版本，支持全量功能，遵循 iOS 沙箱机制，保存到系统相册需申请权限）

前置准备

在集成插件前，需确保开发环境满足基础要求，完成必要的前置配置，具体步骤如下：

已安装 Node.js（v14.0.0 及以上）和 npm（v6.0.0 及以上），可通过 node -v 和 npm -v 命令验证版本；
已创建 Cordova 项目（若尚未创建，可通过 cordova create canvas2ImageApp com.example.canvas2imageapp Canvas2ImageApp 命令快速创建）；
确保项目适配 OHOS 5.0 及以上版本，DevEco Studio 版本为 5.0+，SDK 为 API12+，避免因版本过低导致插件功能异常；

下载安装

通过 HCordova CLI 即可快速安装插件，支持全平台安装或指定 OHOS 平台安装，安装流程简洁高效，安装后可通过命令验证安装结果。

前提条件

安装插件前，需先安装 HCordova CLI，执行以下命令安装：

npm install -g hcordova

基础安装（推荐，从 npm 仓库）

在 Cordova 项目根目录执行以下命令，插件会自动处理各平台依赖与基础配置，默认安装最新稳定版本，支持全平台或指定 OHOS 平台安装：

# 安装最新稳定版（全平台）
hcordova plugin add org.devgeeks.canvas2imageplugin

# 指定 OHOS 平台安装（推荐，仅适配 OHOS 系统）
hcordova plugin add org.devgeeks.canvas2imageplugin --platform ohos

指定版本安装

若需使用特定版本插件，可指定版本号安装，仅适配 OHOS 平台：

# 安装特定版本（示例：1.0.0 版本，仅 OHOS 平台）
hcordova plugin add [email protected] --platform ohos

从 GitCode 安装（开发版）

若需使用开发中的最新功能，可直接从 GitCode 仓库安装，仅适配 OHOS 平台：

# 仅支持 OHOS 平台
hcordova plugin add https://gitcode.com/CPF-Cordova/org.devgeeks.canvas2imageplugin.git --platform ohos

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

离线安装（本地包）

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

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

安装后验证

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

# 查看已安装的插件列表
# 若输出结果包含 org.devgeeks.canvas2imageplugin 则表示插件已成功安装
hcordova plugin list

卸载插件

如需移除插件，执行以下命令即可清理相关配置与依赖，支持全平台卸载或指定 OHOS 平台卸载：

# 全平台卸载插件
hcordova plugin rm org.devgeeks.canvas2imageplugin

# 指定 OHOS 平台卸载
hcordova plugin rm org.devgeeks.canvas2imageplugin --platform ohos

约束与限制

平台限制：OHOS 平台仅支持 5.0 及以上版本，低于该版本的系统可能出现转码失败、图片保存异常等问题；
本项目依赖 cordova-plugin-canvas2image 实现所有功能，如果您是新项目推荐使用 cordova-plugin-canvas2image 插件，本项目的存在主要是为兼容 Android/iOS 项目的移植。
API 调用时机：所有 JavaScript API 必须在 deviceready 事件触发后调用，否则会出现 window.canvas2ImagePlugin 对象未定义、调用失败等异常；
Canvas 元素限制：需确保调用 API 时，Canvas 元素已渲染完成（避免未绘制完成就执行转码），否则会导出空白图片；
图片大小限制：建议 Canvas 转码后的图片大小不超过 10MB，过大图片会导致转码耗时过长、保存失败或占用过多系统资源；

兼容性

支持：

| 项目 | 版本/信息 | |-----|--------| | 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.canvas2ImagePlugin 暴露核心 API，所有操作均为异步执行，通过回调函数处理结果。所有 API 需在 deviceready 事件触发后调用。以下为 OHOS 平台核心功能的完整使用示例，可直接复制到项目中使用，重点注意权限配置和沙箱路径配置。

基础使用（保存 Canvas 到相册）

将 Canvas 元素绘制完成后，调用核心 API 保存图片到系统相册，适配 OHOS 平台权限要求：

// 等待 Cordova 环境就绪
document.addEventListener('deviceready', function() {
    // 1. 先绘制 Canvas（示例：绘制简单图形）
    var canvas = document.getElementById('myCanvas');
    var ctx = canvas.getContext('2d');
    ctx.fillStyle = '#ff0000';
    ctx.fillRect(10, 10, 100, 100); // 绘制红色矩形
    ctx.fillStyle = '#000000';
    ctx.font = '20px Arial';
    ctx.fillText('Canvas 转图片示例', 10, 130); // 绘制文字

    // 2. 保存 Canvas 到系统相册
    function savePhotoCanvas() {
            window.canvas2ImagePlugin.saveImageDataToLibrary(
            function(msg){
                document.getElementById("canvasInfo").innerHTML = msg;
                console.log(msg);
            },
            function(err){
                console.log(err);
            },
            document.getElementById('myCanvas')
        );
    }

    // 绑定按钮点击事件，触发保存操作
    document.getElementById('saveBtn').addEventListener('click', savePhotoCanvas);
}, false);

使用说明

以下为插件使用的核心说明，包括 API 详解、参数说明、常见问题及注意事项等，帮助开发者快速上手并避免异常，重点突出 OHOS 平台特性与限制。

1. 核心 API 说明

插件仅暴露一个核心 API，挂载在全局 window.canvas2ImagePlugin 对象下，无需额外引入，所有操作均为异步执行，通过回调函数处理结果。所有 API 均需在 deviceready 事件触发后调用。

1.1 保存 Canvas 到相册（核心 API）

功能：将 HTML5 Canvas 元素转码为指定格式（PNG/JPG），并保存到设备本地指定路径（沙箱路径或系统相册）。

语法：

window.canvas2ImagePlugin.saveImageDataToLibrary(successCallback, errorCallback, canvasElement);

参数说明：

successCallback：成功回调，可选，参数为 msg（保存成功信息，包含保存路径），触发即表示图片保存成功；
errorCallback：失败回调，可选，参数为 err（错误信息，包含错误原因），保存失败时触发；
canvasElement：目标 Canvas 元素，必填，需传入已渲染完成的 Canvas DOM 对象；

2. 常见问题（FAQ）

Q1: 调用 saveImageDataToLibrary 后提示权限不足，保存失败怎么办？

检查权限：保存相册时，系统会弹窗是否确保保存相册，由用户点击保存相册，才能正确保存。

Q2: 保存图片后，在系统相册中找不到怎么办？

刷新相册：OHOS 系统可能存在相册刷新延迟，可手动刷新相册或重启应用后查看。

Q3: 导出的图片为空白，怎么办？

检查 Canvas 渲染：确保调用 API 时，Canvas 元素已绘制完成，避免在绘制前执行转码；
检查 Canvas 尺寸：避免 Canvas 尺寸为 0（宽高均为 0），确保 Canvas 有实际绘制内容；
检查 API 调用时机：确保在 deviceready 事件触发后调用 API，避免 Canvas 元素未加载完成。

Q4: 保存 JPG 图片时，透明背景变成白色，怎么办？

JPG 格式本身不支持透明背景，这是格式特性，解决方案如下：

若需保留透明背景，将图片格式改为 PNG；
若必须使用 JPG 格式，可在绘制 Canvas 时，先绘制一个纯色背景（如白色、黑色），再绘制具体内容。

3. 注意事项

API 调用时机：所有 JavaScript API 必须在 deviceready 事件触发后调用，否则会出现 window.canvas2ImagePlugin 对象未定义、调用失败等异常。
Canvas 渲染：调用 API 前，务必确保 Canvas 元素已渲染完成，否则会导出空白图片；避免在 Canvas 绘制过程中执行转码操作。

目录结构

org.devgeeks.canvas2imageplugin      # [根目录] Canvas 转图片插件项目根目录
├── .gitignore                       # [配置] Git 版本控制忽略文件配置
├── LICENSE                          # [文本] 开源许可证文件
├── OAT.xml                          # [配置] 门禁配置文件
├── package.json                     # [配置] NPM 包配置文件，定义插件依赖、版本和脚本
├── plugin.xml                       # [配置] Cordova 插件核心配置文件，定义插件 ID、平台映射和权限
└── README.md                        # [文档] 项目说明文档，通常包含安装和使用方法

贡献代码

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

许可证

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

官方资源

Android 和 iOS：org.devgeeks.canvas2imageplugin 官方指南
GitCode 仓库：https://gitcode.com/CPF-Cordova/org.devgeeks.canvas2imageplugin