@hxa-rn/react-native-gcanvas 6.0.24-beta.1

package/harmony/gcanvas/src/main/ets/GCanvasModuleTurboModule.ts

@@ -0,0 +1,448 @@
+import { UITurboModule, UITurboModuleContext } from '@rnoh/react-native-openharmony/ts';
+import { TM } from './generated/ts';
+import { image } from '@kit.ImageKit';
+import { http } from '@kit.NetworkKit';
+import util from '@ohos.util';
+import fs from '@ohos.file.fs';
+import hilog from '@ohos.hilog';
+import { GCanvasNativeEngine } from './GCanvasNativeEngine';
+
+const TAG = 'GCanvasModule';
+const DOMAIN = 0x0001;
+
+/**
+ * GCanvasModule TurboModule（鸿蒙 ArkTS 侧实现）。
+ *
+ * 本模块是 C++ OpenGL ES Canvas/WebGL 引擎（GCanvas）的鸿蒙适配：
+ *  - 同步方法（enable/extendCallNative/setContextType/toDataURL/字体等）：透传至
+ *    C++ 原生引擎 GCanvasNativeEngine（单例），由其内部 GL 线程执行命令并同步返回。
+ *    同步语义复刻 Android GCanvasJNI.render() 的 waitUtilTimeout/QueueProc。
+ *  - 异步方法（图片解码/网络下载/生命周期）：在 ArkTS 侧用 image kit / net.http 实现，
+ *    解码出的 RGBA 像素交 C++ 引擎上传纹理（对齐 Android texImage2D 命令 '102,9,...'）。
+ *
+ * 方法名、签名、返回类型与 JS 桥（packages/gcanvas/src/bridge/react-native.js）及
+ * Spec（src/specs/v1/NativeGCanvasModule.ts）完全一致。TurboModuleRegistry 名称固定 'GCanvasModule'。
+ *
+ * 错误处理约定：异步方法用 Promise.reject()；同步方法不抛异常（GL 调用失败由 C++ 内部记录），
+ * 仅在 ArkTS 入口参数非法时记录日志并返回安全默认值，避免原生崩溃导致 RN 应用闪退。
+ */
+export class GCanvasModuleTurboModule extends UITurboModule implements TM.GCanvasModule.Spec {
+  private engine: GCanvasNativeEngine = GCanvasNativeEngine.getInstance();
+  // GImage.preloadImage currently passes the legacy placeholder id 0 and assigns
+  // the real image id in JS afterwards. Android therefore resolves textures by
+  // path (fetchLoadImage(path)); keep the same source-keyed cache on Harmony.
+  private decodedImagesBySource: Map<string, RgbaPixels> = new Map();
+
+  constructor(ctx: UITurboModuleContext) {
+    super(ctx);
+  }
+
+  /**
+   * 启用画布（同步）。返回前需让 GL 表面就绪。
+   * config 是上游渲染器选项数组；尺寸和像素比分别来自 XComponent 与 setDevicePixelRatio。
+   */
+  enable(args: { componentId: string, config: number[] }): void {
+    try {
+      this.engine.enable(args.componentId, args.config);
+    } catch (e) {
+      hilogError(`enable failed: componentId=${args.componentId}`, e);
+    }
+  }
+
+  /** 禁用画布（异步）。 */
+  disable(refId: string): Promise<void> {
+    try {
+      this.engine.disable(refId);
+      return Promise.resolve();
+    } catch (e) {
+      hilogError(`disable failed: refId=${refId}`);
+      return Promise.reject(new Error(`disable failed: ${refId}`));
+    }
+  }
+
+  /**
+   * 异步执行命令字符串（type 含 32-bit 编码：2d=0x00 / webgl=0x40，async）。
+   * 命令投递到 GL 线程后立即返回，不等待结果。
+   */
+  render(canvasId: string, cmd: string, type: number): Promise<void> {
+    try {
+      this.engine.render(canvasId, cmd, type);
+      return Promise.resolve();
+    } catch (e) {
+      hilogError(`render failed: canvasId=${canvasId}`, e);
+      return Promise.reject(new Error(`render failed: ${canvasId}`));
+    }
+  }
+
+  /**
+   * 【核心】同步执行命令字符串并返回结果。
+   * 32-bit type = ContextType[31:30](0=2d/1=webgl) | MethodType[29](1=sync) | OptionType[28:0]。
+   * 命令在 GL 线程执行并阻塞等待结果，对齐 Android GCanvasJNI.render() 的同步语义。
+   */
+  extendCallNative(args: { contextId: string, args: string, type: number }): { result: string } {
+    let result: string = '';
+    try {
+      result = this.engine.extendCallNative(args.contextId, args.args, args.type);
+    } catch (e) {
+      hilogError(`extendCallNative failed: contextId=${args.contextId}`, e);
+    }
+    let ret: ExtendCallNativeResult = { result };
+    return ret;
+  }
+
+  /** 设置上下文类型（同步）。0=2d, 1=webgl。 */
+  setContextType(contextType: number, refId: string): void {
+    try {
+      this.engine.setContextType(contextType, refId);
+    } catch (e) {
+      hilogError(`setContextType failed: refId=${refId}`);
+    }
+  }
+
+  /** 设置设备像素比（同步）。 */
+  setDevicePixelRatio(refId: string, ratio: number): void {
+    try {
+      this.engine.setDevicePixelRatio(refId, ratio);
+    } catch (e) {
+      hilogError(`setDevicePixelRatio failed: refId=${refId}`);
+    }
+  }
+
+  /** 重置 GL viewport（同步）。 */
+  resetGlViewport(refId: string): void {
+    try {
+      this.engine.resetGlViewport(refId);
+    } catch (e) {
+      hilogError(`resetGlViewport failed: refId=${refId}`);
+    }
+  }
+
+  /**
+   * 同步导出画布为 data URL（glReadPixels → PNG → base64）。
+   * 返回形如 data:image/png;base64,xxxx；失败返回空字符串。
+   */
+  toDataURL(refId: string, mimeType: string, quality: number): string {
+    try {
+      return this.engine.toDataURL(refId, mimeType, quality);
+    } catch (e) {
+      hilogError(`toDataURL failed: refId=${refId}`);
+      return '';
+    }
+  }
+
+  /** 将一个画布内容绘制到另一画布（同步）。 */
+  drawCanvas2Canvas(map: DrawCanvas2CanvasMap): void {
+    try {
+      this.engine.drawCanvas2Canvas(map);
+    } catch (e) {
+      hilogError(`drawCanvas2Canvas failed: src=${map.srcComponentId} dst=${map.dstComponentId}`);
+    }
+  }
+
+  /**
+   * 图片解码后绑定纹理（异步）。src=图片路径，imageId=纹理 id。
+   * 鸿蒙用 image kit 解码为 RGBA_8888，再交 C++ 引擎上传纹理。
+   */
+  bindImageTexture(args: { src: string, imageId: number }, refId: string): Promise<void> {
+    if (this.engine.bindCachedImageTexture(refId, args.imageId)) {
+      return Promise.resolve();
+    }
+    const cached = this.decodedImagesBySource.get(args.src);
+    if (cached) {
+      this.engine.bindImageTexture(refId, args.imageId, cached.buffer, cached.width, cached.height);
+      return Promise.resolve();
+    }
+    return decodeImageToRGBA(args.src).then((rgba: RgbaPixels) => {
+      this.decodedImagesBySource.set(args.src, rgba);
+      this.engine.bindImageTexture(refId, args.imageId, rgba.buffer, rgba.width, rgba.height);
+    }).catch((e: Error) => {
+      hilogError(`bindImageTexture failed: src=${args.src} err=${e.message}`);
+      return Promise.reject(new Error(`bindImageTexture failed: ${e.message}`));
+    });
+  }
+
+  /**
+   * 预加载图片（异步）。url=图片地址，id=图片 id，返回尺寸/错误信息。
+   * 远程 URL 经 @ohos.net.http 下载为 ArrayBuffer 后再解码（image kit 不支持 http URL）。
+   */
+  preLoadImage(args: { url: string, id: number }): Promise<ImageInfo> {
+    return decodeImageToRGBA(args.url).then((rgba: RgbaPixels) => {
+      // 缓存解码结果，供后续 bindImageTexture/texImage2D 复用
+      this.decodedImagesBySource.set(args.url, rgba);
+      this.engine.cacheImage(args.id, rgba.buffer, rgba.width, rgba.height);
+      let info: ImageInfo = { width: rgba.width, height: rgba.height };
+      return info;
+    }).catch((e: Error) => {
+      hilogError(`preLoadImage failed: url=${args.url} err=${e.message}`);
+      let info: ImageInfo = { width: 0, height: 0, error: e.message };
+      return info;
+    });
+  }
+
+  /** 获取设备信息（异步）。返回 JSON 字符串。 */
+  getDeviceInfo(args: string): Promise<DeviceInfoRet> {
+    try {
+      const data = this.engine.getDeviceInfo(args);
+      let ret: DeviceInfoRet = { data };
+      return Promise.resolve(ret);
+    } catch (e) {
+      hilogError(`getDeviceInfo failed: args=${args}`);
+      let ret: DeviceInfoRet = { data: '' };
+      return Promise.resolve(ret);
+    }
+  }
+
+  /** 注册自定义字体族（同步）。fontNames 与 fontFiles 一一对应。 */
+  addFontFamily(fontNames: string[], fontFiles: string[]): void {
+    try {
+      this.engine.addFontFamily(fontNames, fontFiles);
+    } catch (e) {
+      hilogError('addFontFamily failed');
+    }
+  }
+
+  /** 枚举系统字体族名（同步）。 */
+  getFontNames(): string[] {
+    try {
+      return this.engine.getFontNames();
+    } catch (e) {
+      hilogError('getFontNames failed');
+      return [];
+    }
+  }
+
+  /** 设置额外字体目录（同步）。 */
+  setExtraFontLocation(location: string): void {
+    try {
+      this.engine.setExtraFontLocation(location);
+    } catch (e) {
+      hilogError(`setExtraFontLocation failed: location=${location}`);
+    }
+  }
+
+  /** 设置日志级别（异步）。 */
+  setLogLevel(level: number): Promise<void> {
+    try {
+      this.engine.setLogLevel(level);
+      return Promise.resolve();
+    } catch (e) {
+      hilogError(`setLogLevel failed: level=${level}`);
+      return Promise.reject(new Error('setLogLevel failed'));
+    }
+  }
+
+  /** 重置组件（异步）。 */
+  resetComponent(refId: string): Promise<void> {
+    try {
+      this.engine.resetComponent(refId);
+      return Promise.resolve();
+    } catch (e) {
+      hilogError(`resetComponent failed: refId=${refId}`);
+      return Promise.reject(new Error(`resetComponent failed: ${refId}`));
+    }
+  }
+
+  /** WebGL 纹理上传（同步）。图片须先由 GImage/preLoadImage 解码并按 src 缓存。 */
+  texImage2D(refId: string, target: number, level: number, internalformat: number, format: number,
+    type: number, src: string): void {
+    try {
+      const rgba = this.decodedImagesBySource.get(src);
+      if (!rgba) {
+        hilogError(`texImage2D image is not preloaded: src=${src}`);
+        return;
+      }
+      this.engine.texImage2D(refId, target, level, internalformat, format, type,
+        rgba.buffer, rgba.width, rgba.height);
+    } catch (e) {
+      hilogError(`texImage2D failed: refId=${refId}`);
+    }
+  }
+
+  /** WebGL 纹理子图上传（同步，鸿蒙新增分支）。命令 '105,9,...'。 */
+  texSubImage2D(refId: string, target: number, level: number, xoffset: number, yoffset: number,
+    format: number, type: number, src: string): void {
+    try {
+      const rgba = this.decodedImagesBySource.get(src);
+      if (!rgba) {
+        hilogError(`texSubImage2D image is not preloaded: src=${src}`);
+        return;
+      }
+      this.engine.texSubImage2D(refId, target, level, xoffset, yoffset, format, type,
+        rgba.buffer, rgba.width, rgba.height);
+    } catch (e) {
+      hilogError(`texSubImage2D failed: refId=${refId}`);
+    }
+  }
+
+  /** 设置组件 alpha（异步，原实现为空壳，鸿蒙同样空实现）。 */
+  setAlpha(refId: string, alpha: number): Promise<void> {
+    // 原生 Android/iOS 端 setAlpha 即为空实现，鸿蒙保持一致。
+    return Promise.resolve();
+  }
+}
+
+/**
+ * 解码图片为 RGBA 像素缓冲。
+ * 支持：沙箱/资源/$rawfile 路径、http(s) 远程 URL、data: URL。
+ * 远程 URL 先经 @ohos.net.http 下载为 ArrayBuffer（image.createImageSource 不支持 http）。
+ */
+async function decodeImageToRGBA(src: string): Promise<RgbaPixels> {
+  let buf: ArrayBuffer;
+  if (src.startsWith('http://') || src.startsWith('https://')) {
+    buf = await downloadToBuffer(src);
+  } else if (src.startsWith('data:')) {
+    buf = dataUrlToBuffer(src);
+  } else {
+    buf = await readLocalToBuffer(src);
+  }
+  let imageSource: image.ImageSource | null = null;
+  let pixelMap: image.PixelMap | null = null;
+  try {
+    imageSource = image.createImageSource(buf);
+    pixelMap = await imageSource.createPixelMap({ desiredPixelFormat: image.PixelMapFormat.RGBA_8888 });
+    const info = await pixelMap.getImageInfo();
+    const width: number = info.size.width;
+    const height: number = info.size.height;
+    const byteCount: number = pixelMap.getPixelBytesNumber();
+    const pixels: ArrayBuffer = new ArrayBuffer(byteCount);
+    await pixelMap.readPixelsToBuffer(pixels);
+    let ret: RgbaPixels = { buffer: pixels, width, height };
+    return ret;
+  } catch (e) {
+    hilog.error(DOMAIN, TAG, `decodeImageToRGBA failed: src=${src} err=${(e as Error).message}`);
+    throw e instanceof Error ? e : new Error(String(e));
+  } finally {
+    releaseDecodedImage(pixelMap, imageSource);
+  }
+}
+
+function releaseDecodedImage(pixelMap: image.PixelMap | null, imageSource: image.ImageSource | null): void {
+  if (pixelMap) {
+    try {
+      pixelMap.release();
+    } catch (e) {
+      hilog.error(DOMAIN, TAG, `release PixelMap failed: ${(e as Error).message}`);
+    }
+  }
+  if (imageSource) {
+    try {
+      imageSource.release();
+    } catch (e) {
+      hilog.error(DOMAIN, TAG, `release ImageSource failed: ${(e as Error).message}`);
+    }
+  }
+}
+
+/** 远程图片下载为 ArrayBuffer。 */
+async function downloadToBuffer(url: string): Promise<ArrayBuffer> {
+  let httpReq: http.HttpRequest | null = null;
+  try {
+    httpReq = http.createHttp();
+    const resp = await httpReq.request(url, {
+      method: http.RequestMethod.GET,
+      expectDataType: http.HttpDataType.ARRAY_BUFFER,
+    });
+    httpReq.destroy();
+    return resp.result as ArrayBuffer;
+  } catch (e) {
+    if (httpReq) {
+      httpReq.destroy();
+    }
+    hilog.error(DOMAIN, TAG, `downloadToBuffer failed: url=${url} err=${(e as Error).message}`);
+    throw e instanceof Error ? e : new Error(String(e));
+  }
+}
+
+/** data URL（base64）转 ArrayBuffer。 */
+function dataUrlToBuffer(dataUrl: string): ArrayBuffer {
+  try {
+    const base64Helper = new util.Base64Helper();
+    const commaIdx = dataUrl.indexOf(',');
+    const base64 = commaIdx >= 0 ? dataUrl.substring(commaIdx + 1) : dataUrl;
+    const bytes = base64Helper.decodeSync(base64);
+    return bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength) as ArrayBuffer;
+  } catch (e) {
+    hilog.error(DOMAIN, TAG, `dataUrlToBuffer failed: err=${(e as Error).message}`);
+    throw e instanceof Error ? e : new Error(String(e));
+  }
+}
+
+/** 本地/资源文件读取为 ArrayBuffer。 */
+async function readLocalToBuffer(path: string): Promise<ArrayBuffer> {
+  let file: fs.File | null = null;
+  try {
+    file = fs.openSync(path, fs.OpenMode.READ_ONLY);
+    const stat = fs.statSync(path);
+    const buf: ArrayBuffer = new ArrayBuffer(stat.size);
+    await fs.read(file.fd, buf);
+    fs.closeSync(file);
+    return buf;
+  } catch (e) {
+    // 关闭文件也可能抛异常，且门禁要求 @kit 调用必须在 try/catch 内并用 hilog 记录。
+    if (file) {
+      try {
+        fs.closeSync(file);
+      } catch (ce) {
+        hilog.error(DOMAIN, TAG, `readLocalToBuffer close failed: path=${path} err=${(ce as Error).message}`);
+      }
+    }
+    hilog.error(DOMAIN, TAG, `readLocalToBuffer failed: path=${path} err=${(e as Error).message}`);
+    throw e instanceof Error ? e : new Error(String(e));
+  }
+}
+
+function errorMessage(e: Object): string {
+  try {
+    return e instanceof Error ? e.message : String(e);
+  } catch (_ignored) {
+    return 'unknown';
+  }
+}
+
+function hilogError(msg: string, e?: Object): void {
+  if (e === undefined) {
+    hilog.error(DOMAIN, TAG, msg);
+    return;
+  }
+  hilog.error(DOMAIN, TAG, `${msg} err=${errorMessage(e)}`);
+}
+
+/** extendCallNative 同步返回值。 */
+interface ExtendCallNativeResult {
+  result: string;
+}
+
+/** drawCanvas2Canvas 参数。 */
+interface DrawCanvas2CanvasMap {
+  srcComponentId: string;
+  dstComponentId: string;
+  tw: number;
+  th: number;
+  sx: number;
+  sy: number;
+  sw: number;
+  sh: number;
+  dx: number;
+  dy: number;
+  dw: number;
+  dh: number;
+}
+
+/** RGBA 像素解码结果。 */
+interface RgbaPixels {
+  buffer: ArrayBuffer;
+  width: number;
+  height: number;
+}
+
+/** preLoadImage 返回的图片信息。 */
+interface ImageInfo {
+  width: number;
+  height: number;
+  error?: string;
+}
+
+/** getDeviceInfo 返回。 */
+interface DeviceInfoRet {
+  data: string;
+}

package/harmony/gcanvas/src/main/ets/GCanvasNativeEngine.ts

@@ -0,0 +1,206 @@
+import hilog from '@ohos.hilog';
+import nativeModule from 'libgcanvas.so';
+
+const TAG = 'GCanvasNativeEngine';
+const DOMAIN = 0x0001;
+
+/**
+ * GCanvas 原生引擎的 ArkTS 门面（单例）。
+ *
+ * 所有 GCanvasModuleTurboModule 的同步/绘制方法都经此转发到 C++ 原生引擎
+ * （libgcanvas.so，由 NAPI 暴露），由 C++ 内部独立 GL 线程执行命令。
+ *
+ * 该门面职责单一：
+ *  1. 维护 nativeModule 单例（懒加载，避免 HAR 加载期即初始化 .so）；
+ *  2. 将 ArkTS 参数透传给 C++，统一日志与异常隔离（不向 TurboModule 抛异常）。
+ *
+ * 真正的 OpenGL ES / EGL / XComponent / 字体 / 命令解析逻辑全部在 C++ 侧（复用 core/src）。
+ */
+export class GCanvasNativeEngine {
+  private static instance: GCanvasNativeEngine;
+  private native: GCanvasNativeAPI | null = null;
+
+  private constructor() {
+  }
+
+  public static getInstance(): GCanvasNativeEngine {
+    if (!GCanvasNativeEngine.instance) {
+      GCanvasNativeEngine.instance = new GCanvasNativeEngine();
+    }
+    return GCanvasNativeEngine.instance;
+  }
+
+  private api(): GCanvasNativeAPI {
+    if (this.native === null) {
+      const loaded = nativeModule as GCanvasNativeAPI;
+      if (typeof loaded.enable !== 'function' || typeof loaded.render !== 'function' ||
+        typeof loaded.extendCallNative !== 'function') {
+        throw new Error('libgcanvas.so is missing enable/render/extendCallNative');
+      }
+      this.native = loaded;
+    }
+    return this.native;
+  }
+
+  /** 注册 XComponent 与 GL 表面（由 Fabric 组件创建后调用，绑定 componentId↔window）。 */
+  public bindSurface(componentId: string, window: number, width: number, height: number): void {
+    this.api().bindSurface(componentId, window, width, height);
+  }
+
+  /** surface 尺寸变化。 */
+  public surfaceChanged(componentId: string, width: number, height: number): void {
+    this.api().surfaceChanged(componentId, width, height);
+  }
+
+  /** surface 销毁。 */
+  public surfaceDestroyed(componentId: string): void {
+    this.api().surfaceDestroyed(componentId);
+  }
+
+  /** Apply native-only view options that are not part of the JS command protocol. */
+  public configureView(componentId: string, enableFboMsaa: boolean): void {
+    this.api().configureView(componentId, enableFboMsaa);
+  }
+
+  /** 启用画布（同步）。config 同 Android enable() 的 configArray。 */
+  public enable(componentId: string, config: number[]): void {
+    this.api().enable(componentId, config);
+  }
+
+  /** 禁用画布。 */
+  public disable(refId: string): void {
+    this.api().disable(refId);
+  }
+
+  /** 异步执行命令字符串（投递到 GL 线程后立即返回）。 */
+  public render(canvasId: string, cmd: string, type: number): void {
+    this.api().render(canvasId, cmd, type);
+  }
+
+  /** 同步执行命令字符串并返回结果（GL 线程阻塞等待）。 */
+  public extendCallNative(contextId: string, args: string, type: number): string {
+    return this.api().extendCallNative(contextId, args, type);
+  }
+
+  /** 设置上下文类型：0=2d, 1=webgl。 */
+  public setContextType(contextType: number, refId: string): void {
+    this.api().setContextType(contextType, refId);
+  }
+
+  public setDevicePixelRatio(refId: string, ratio: number): void {
+    this.api().setDevicePixelRatio(refId, ratio);
+  }
+
+  public resetGlViewport(refId: string): void {
+    this.api().resetGlViewport(refId);
+  }
+
+  /** 同步导出画布为 data URL。 */
+  public toDataURL(refId: string, mimeType: string, quality: number): string {
+    return this.api().toDataURL(refId, mimeType, quality);
+  }
+
+  public drawCanvas2Canvas(map: DrawCanvas2CanvasMap): void {
+    this.api().drawCanvas2Canvas(map);
+  }
+
+  /** 绑定已解码的 RGBA 像素到纹理。 */
+  public bindImageTexture(refId: string, imageId: number, pixels: ArrayBuffer,
+    width: number, height: number): void {
+    this.api().bindImageTexture(refId, imageId, pixels, width, height);
+  }
+
+  /** Rebind a preloaded native image without decoding it a second time. */
+  public bindCachedImageTexture(refId: string, imageId: number): boolean {
+    return this.api().bindCachedImageTexture(refId, imageId);
+  }
+
+  /** 缓存解码后的图片，供后续纹理上传复用。 */
+  public cacheImage(id: number, pixels: ArrayBuffer, width: number, height: number): void {
+    this.api().cacheImage(id, pixels, width, height);
+  }
+
+  public getDeviceInfo(args: string): string {
+    return this.api().getDeviceInfo(args);
+  }
+
+  public addFontFamily(fontNames: string[], fontFiles: string[]): void {
+    this.api().addFontFamily(fontNames, fontFiles);
+  }
+
+  public getFontNames(): string[] {
+    return this.api().getFontNames();
+  }
+
+  public setExtraFontLocation(location: string): void {
+    this.api().setExtraFontLocation(location);
+  }
+
+  public setLogLevel(level: number): void {
+    this.api().setLogLevel(level);
+  }
+
+  public resetComponent(refId: string): void {
+    this.api().resetComponent(refId);
+  }
+
+  public texImage2D(refId: string, target: number, level: number, internalformat: number,
+    format: number, type: number, pixels: ArrayBuffer, width: number, height: number): void {
+    this.api().texImage2D(refId, target, level, internalformat, format, type, pixels, width, height);
+  }
+
+  public texSubImage2D(refId: string, target: number, level: number, xoffset: number, yoffset: number,
+    format: number, type: number, pixels: ArrayBuffer, width: number, height: number): void {
+    this.api().texSubImage2D(refId, target, level, xoffset, yoffset, format, type, pixels, width, height);
+  }
+}
+
+/**
+ * C++ 原生引擎（libgcanvas.so）经 NAPI 暴露的接口契约。
+ * C++ 侧（GCanvasNapi.cpp）须实现下列全部方法。
+ */
+interface GCanvasNativeAPI {
+  bindSurface(componentId: string, window: number, width: number, height: number): void;
+  surfaceChanged(componentId: string, width: number, height: number): void;
+  surfaceDestroyed(componentId: string): void;
+  configureView(componentId: string, enableFboMsaa: boolean): void;
+  enable(componentId: string, config: number[]): void;
+  disable(refId: string): void;
+  render(canvasId: string, cmd: string, type: number): void;
+  extendCallNative(contextId: string, args: string, type: number): string;
+  setContextType(contextType: number, refId: string): void;
+  setDevicePixelRatio(refId: string, ratio: number): void;
+  resetGlViewport(refId: string): void;
+  toDataURL(refId: string, mimeType: string, quality: number): string;
+  drawCanvas2Canvas(map: DrawCanvas2CanvasMap): void;
+  bindImageTexture(refId: string, imageId: number, pixels: ArrayBuffer,
+    width: number, height: number): void;
+  bindCachedImageTexture(refId: string, imageId: number): boolean;
+  cacheImage(id: number, pixels: ArrayBuffer, width: number, height: number): void;
+  getDeviceInfo(args: string): string;
+  addFontFamily(fontNames: string[], fontFiles: string[]): void;
+  getFontNames(): string[];
+  setExtraFontLocation(location: string): void;
+  setLogLevel(level: number): void;
+  resetComponent(refId: string): void;
+  texImage2D(refId: string, target: number, level: number, internalformat: number,
+    format: number, type: number, pixels: ArrayBuffer, width: number, height: number): void;
+  texSubImage2D(refId: string, target: number, level: number, xoffset: number, yoffset: number,
+    format: number, type: number, pixels: ArrayBuffer, width: number, height: number): void;
+}
+
+/** drawCanvas2Canvas 参数（与 GCanvasModuleTurboModule 一致）。 */
+interface DrawCanvas2CanvasMap {
+  srcComponentId: string;
+  dstComponentId: string;
+  tw: number;
+  th: number;
+  sx: number;
+  sy: number;
+  sw: number;
+  sh: number;
+  dx: number;
+  dy: number;
+  dw: number;
+  dh: number;
+}

package/harmony/gcanvas/src/main/ets/GcanvasTurboModulesFactory.ets

@@ -0,0 +1,42 @@
+import { RNOHPackage } from '@rnoh/react-native-openharmony/ets';
+import type {
+  UITurboModule,
+  UITurboModuleContext,
+  DescriptorWrapperFactoryByDescriptorTypeCtx,
+  DescriptorWrapperFactoryByDescriptorType,
+} from '@rnoh/react-native-openharmony/ts';
+import { GCanvasModuleTurboModule } from './GCanvasModuleTurboModule';
+import { TM } from './generated/ts';
+import { GCanvasView as GCanvasViewSpec } from './generated/components/GCanvasView';
+
+/**
+ * GcanvasPackage — RNOHPackage，同时注册 TurboModule 与 Fabric 组件。
+ *
+ * 1. getUITurboModuleFactoryByNameMap：注册 GCanvasModule TurboModule（20 方法）。
+ * 2. createDescriptorWrapperFactoryByDescriptorType：注册 GCanvasView Fabric 组件的
+ *    DescriptorWrapper。缺此项 = Fabric 组件运行时完全不可用（且无报错）。
+ */
+export class GcanvasPackage extends RNOHPackage {
+  getUITurboModuleFactoryByNameMap(): Map<string, (ctx: UITurboModuleContext) => UITurboModule | null> {
+    const map = new Map<string, (ctx: UITurboModuleContext) => UITurboModule | null>();
+    map.set(TM.GCanvasModule.NAME, (ctx: UITurboModuleContext) => new GCanvasModuleTurboModule(ctx));
+    return map;
+  }
+
+  override async createEagerUITurboModuleByNameMap(ctx: UITurboModuleContext): Promise<Map<string, UITurboModule>> {
+    const module = new GCanvasModuleTurboModule(ctx);
+    return new Map()
+      .set(TM.GCanvasModule.NAME, module);
+  }
+
+  override createDescriptorWrapperFactoryByDescriptorType(
+    _ctx: DescriptorWrapperFactoryByDescriptorTypeCtx
+  ): DescriptorWrapperFactoryByDescriptorType {
+    // ArkTS 禁止计算属性名（[NAME] 触发 arkts-identifiers-as-prop-names）。
+    // 需用标识符字面量键（与 RNOH Package.ets 的 { View: ... } 写法一致）。
+    // 键名 'GCanvasView' 必须与 GCanvasView.NAME / codegenNativeComponent('GCanvasView') 一致。
+    return {
+      GCanvasView: (ctx) => new GCanvasViewSpec.DescriptorWrapper(ctx.descriptor),
+    };
+  }
+}