基于 OpenGL/GLSL 的原生 Canvas 2D/WebGL 组件，提供高性能绘图能力

react-native-gcanvas

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

项目介绍

@hxa-rn/react-native-gcanvas 是 @flyskywhy/react-native-gcanvas@6.0.24 的鸿蒙适配包，提供基于 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.28。

集成指南

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

本包声明：

{
  "name": "@hxa-rn/react-native-gcanvas",
  "version": "6.0.28",
  "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 main

2. 安装仓库开发依赖

npm install --legacy-peer-deps

Example 已改为从 npm 公仓安装 @hxa-rn/react-native-gcanvas@6.0.28，不再使用本地 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 实际画面、字形与远程图片效果需在设备上确认。