react-native-gcanvas

本项目基于 @flyskywhy/react-native-gcanvas开发。如果在使用过程中有任何问题，欢迎在AtomGit提交Issue，会及时跟进。

项目介绍

@hxa-rn/react-native-gcanvas 是 @flyskywhy/[email protected] 的鸿蒙适配包，提供基于 C++ GCanvas（OpenGL ES）引擎的 Canvas 2D / WebGL 原生视图。业务侧通过 harmony.alias 继续 import ... from '@flyskywhy/react-native-gcanvas'。

本包含原生实现：C++ TurboModule GCanvasModule（20 个方法）+ Fabric 组件 GCanvasView（XComponent SURFACE + EGL）。JS 层复用上游命令字符串桥，鸿蒙侧补齐 texImage2D / texSubImage2D、registerFont / getFontNames 与远程图片下载。

当前版本：6.0.24-beta.1。

集成指南

npm install @hxa-rn/react-native-gcanvas

本包声明：

{
  "name": "@hxa-rn/react-native-gcanvas",
  "version": "6.0.24-beta.1",
  "peerDependencies": {
    "react-native": ">=0.72"
  },
  "harmony": {
    "alias": "@flyskywhy/react-native-gcanvas"
  }
}

工程按 harmony.alias 解析后，业务代码仍从原包名导入：

import {GCanvasView, GImage, createCanvas, getFontNames, registerFont} from '@flyskywhy/react-native-gcanvas';

peerDependencies 为 react-native >= 0.72。本模块含 C++ TurboModule 与 Fabric 组件。Autolinking 可用时跳过手动注册；手动接入时需同时注册 C++ GcanvasPackage 与 ETS GcanvasPackage，并把 harmony/gcanvas.har 加入 entry 依赖。

使用说明

import React from 'react';
import {StyleSheet, View} from 'react-native';
import {GCanvasView} from '@flyskywhy/react-native-gcanvas';

export default function App() {
  return (
    <View style={styles.container}>
      <GCanvasView
        style={styles.canvas}
        onCanvasCreate={(canvas) => {
          const ctx = canvas.getContext('2d');
          ctx.fillStyle = '#FF5722';
          ctx.fillRect(10, 10, 100, 100);
          ctx.font = '24px';
          ctx.fillStyle = '#222222';
          ctx.fillText('Hello GCanvas', 10, 160);
        }}
        onIsReady={(value) => {
          console.log('canvas ready:', value);
        }}
      />
    </View>
  );
}

const styles = StyleSheet.create({
  container: {flex: 1},
  canvas: {width: 300, height: 200},
});

onCanvasCreate 拿到 canvas 后即可 getContext('2d'|'webgl')。toDataURL 同步返回 data:image/png;base64,...。registerFont(src, fontFace?) 在鸿蒙已开通，随后可用 getFontNames() 查看枚举结果。加载远程图片时须在 module.json5 声明 ohos.permission.INTERNET。

接口文档

导出

| 名称 | 类型 | 说明 | |------|------|------| | GCanvasView | React 组件 | Canvas 2D / WebGL 原生视图 | | GImage | 类 | 图片对象，走 preLoadImage | | createCanvas(width, height) | 函数 | 创建离屏 Canvas | | getFontNames() | 函数 | 返回系统可用字体名数组 | | registerFont(src, fontFace?) | 函数 | 注册自定义字体（鸿蒙已开通） |

<GCanvasView> Props / 事件

| 名称 | 类型 | 说明 | |------|------|------| | isGestureResponsible | boolean | 是否响应画布内手势，默认 true | | isAutoClearRectBeforePutImageData | boolean | putImageData 前是否先 clear，仅 2D | | isResetGlViewportAfterSetWidthOrHeight | boolean | 宽高变化后是否重置 viewport | | devicePixelRatio | number | 未传时使用 PixelRatio.get() | | offscreenCanvas | boolean | 是否可作为 document.createElement('canvas') 离屏画布 | | disableAutoSwap | boolean | 关闭 WebGL 自动 swap | | onCanvasCreate | (canvas) => void | 画布对象就绪 | | onCanvasResize | ({width, height, canvas}) => void | 视图尺寸变化 | | onIsReady | (value) => void | GL surface 就绪 / 销毁 | | onMouseDown / onMouseMove / onMouseUp | (e) => void | 触摸转 PointerEvent |

Canvas / 上下文

| API | 说明 | |-----|------| | canvas.getContext('2d' \| 'webgl') | 取得 2D 或 WebGL 上下文 | | canvas.toDataURL(mimeType, quality) | 同步导出 Base64 | | canvas.reset() | 调用原生 resetComponent | | 2D：fillRect / strokeRect / clearRect / fill / stroke / arc | 矩形与路径 | | 2D：fillText / strokeText / measureText | 文本 | | 2D：createLinearGradient / createRadialGradient / createPattern | 渐变与图案 | | 2D：scale / rotate / translate / save / restore | 变换 | | 2D：drawImage / getImageData / putImageData | 图片与像素 | | WebGL：createShader / compileShader / texImage2D / drawArrays 等 | WebGL 1.0 |

TurboModule GCanvasModule（经 JS 桥内部调用）

| 方法 | 同步 | 说明 | |------|------|------| | enable / disable / resetComponent | 混合同步 | 画布生命周期 | | extendCallNative | 同步 | 命令字符串执行并返回结果 | | render | 异步 | 命令字符串投递后立即返回 | | setContextType / setDevicePixelRatio / resetGlViewport | 同步 | 上下文与视口 | | toDataURL | 同步 | glReadPixels → PNG → base64 | | preLoadImage / bindImageTexture | 异步 | 图片解码与纹理绑定 | | texImage2D / texSubImage2D | 同步 | WebGL 纹理上传 | | getFontNames / addFontFamily / setExtraFontLocation | 同步 | 字体 | | setAlpha | 异步 | 空壳，对齐 Android/iOS，不产生实际透明度 |

快速验证（运行 Example）

前置条件

| 依赖 | 版本要求 | |------|----------| | Node.js | >= 18 | | DevEco Studio | 5.0+ / 6.0+ | | HarmonyOS SDK | API 12+ |

运行步骤

1. 克隆仓库

git clone https://gitcode.com/hxa-rn/react-native-gcanvas.git
cd react-native-gcanvas
git checkout br_rnoh0.72

2. 安装仓库开发依赖

npm install --legacy-peer-deps

Example 已改为从 npm 公仓安装 @hxa-rn/[email protected]，不再使用本地 file:../xxx.tgz，运行 Example 不必再执行 npm pack。

3. 进入 example 目录，安装依赖

cd example
npm install --legacy-peer-deps

4. 生成 JS Bundle

npm run dev

产物：harmony/entry/src/main/resources/rawfile/bundle.harmony.js

5. 用 DevEco Studio 打开鸿蒙工程

• 打开 DevEco Studio
• 选择 example/harmony 目录
• 等待 Sync 完成

6. 编译并运行 HAP

在 DevEco Studio 中点击运行按钮，将 HAP 安装到设备/模拟器。

注意：Example 中已预置插件依赖和 Package 注册，无需手动配置 Link。

约束与限制

• 兼容性：Demo compatibleSdkVersion 为 5.0.1(13)；react-native >= 0.72；RNOH 0.72+；HarmonyOS API 12+（适配构建环境为 API 13）。
• 权限：加载远程 http(s) 图片时需在应用 module.json5 声明 ohos.permission.INTERNET。库模块本身无额外系统权限。
• 远程图片：鸿蒙 image.createImageSource 不接受 http URL，须先经 @ohos.net.http 下载。
• setAlpha：空实现，对齐 Android/iOS 原空壳语义。
• getImageData / measureText：走 execWithoutDisplay，读完后需再绘制才能上屏。
• 真机渲染：2D / WebGL 实际画面、字形与远程图片效果需在设备上确认。

开源license

本项目基于 MIT 协议，详见 LICENSE 文件。

问题反馈渠道

欢迎在 AtomGit 提交 Issue。也可在 GitCode 仓库反馈：

https://gitcode.com/hxa-rn/react-native-gcanvas

https://gitcode.com/hxa-rn/react-native-gcanvas/issues