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

package/CHANGELOG.md

@@ -2,9 +2,9 @@
 
 ## 鸿蒙化Log
 
-## 6.0.24-beta.1 - 2026-09-21
+## 6.0.26 - 2026-09-21
 
-release @hxa-rn/react-native-gcanvas@6.0.24-beta.1
+release @hxa-rn/react-native-gcanvas@6.0.26
 
 ### Added
 

package/LICENSE

@@ -1,21 +1,203 @@
-MIT License
-
-Copyright (c) 2026 hxa-rn
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+Modifications Copyright (c) 2026 HarmonyOS X-platform Alliance
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,207 +1,207 @@
-# react-native-gcanvas
-
-本项目基于 [@flyskywhy/react-native-gcanvas](https://github.com/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.24-beta.1`。
-
-## 集成指南
-
-```bash
-npm install @hxa-rn/react-native-gcanvas
-```
-
-本包声明：
-
-```json
-{
-  "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` 解析后，业务代码仍从原包名导入：
-
-```ts
-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 依赖。
-
-## 使用说明
-
-```tsx
-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. 克隆仓库**
-
-```bash
-git clone https://gitcode.com/hxa-rn/react-native-gcanvas.git
-cd react-native-gcanvas
-git checkout br_rnoh0.72
-```
-
-**2. 安装仓库开发依赖**
-
-```bash
-npm install --legacy-peer-deps
-```
-
-Example 已改为从 npm 公仓安装 `@hxa-rn/react-native-gcanvas@6.0.24-beta.1`，不再使用本地 `file:../xxx.tgz`，运行 Example 不必再执行 `npm pack`。
-
-**3. 进入 example 目录，安装依赖**
-
-```bash
-cd example
-npm install --legacy-peer-deps
-```
-
-**4. 生成 JS Bundle**
-
-```bash
-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](./LICENSE) 文件。
-
-## 问题反馈渠道
-
-欢迎在 AtomGit 提交 Issue。也可在 GitCode 仓库反馈：
-
-https://gitcode.com/hxa-rn/react-native-gcanvas
-
-https://gitcode.com/hxa-rn/react-native-gcanvas/issues
+# react-native-gcanvas
+
+本项目基于 [@flyskywhy/react-native-gcanvas](https://github.com/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.26`。
+
+## 集成指南
+
+```bash
+npm install @hxa-rn/react-native-gcanvas
+```
+
+本包声明：
+
+```json
+{
+  "name": "@hxa-rn/react-native-gcanvas",
+  "version": "6.0.26",
+  "peerDependencies": {
+    "react-native": ">=0.72"
+  },
+  "harmony": {
+    "alias": "@flyskywhy/react-native-gcanvas"
+  }
+}
+```
+
+工程按 `harmony.alias` 解析后，业务代码仍从原包名导入：
+
+```ts
+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 依赖。
+
+## 使用说明
+
+```tsx
+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. 克隆仓库**
+
+```bash
+git clone https://gitcode.com/hxa-rn/react-native-gcanvas.git
+cd react-native-gcanvas
+git checkout main
+```
+
+**2. 安装仓库开发依赖**
+
+```bash
+npm install --legacy-peer-deps
+```
+
+Example 已改为从 npm 公仓安装 `@hxa-rn/react-native-gcanvas@6.0.26`，不再使用本地 `file:../xxx.tgz`，运行 Example 不必再执行 `npm pack`。
+
+**3. 进入 example 目录，安装依赖**
+
+```bash
+cd example
+npm install --legacy-peer-deps
+```
+
+**4. 生成 JS Bundle**
+
+```bash
+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
+
+本项目基于 Apache-2.0 协议，详见 [LICENSE](./LICENSE) 文件。
+
+## 问题反馈渠道
+
+欢迎在 AtomGit 提交 Issue。也可在 GitCode 仓库反馈：
+
+https://gitcode.com/hxa-rn/react-native-gcanvas
+
+https://gitcode.com/hxa-rn/react-native-gcanvas/issues