Add documentation for the arkts interface to call javascript.

versions/2.4/zh/SUMMARY.md

@@ -288,6 +288,7 @@
     - [动态合图](advanced-topics/dynamic-atlas.md)
     - [Java 原生反射机制](advanced-topics/java-reflection.md)
     - [Objective-C 原生反射机制](advanced-topics/oc-reflection.md)
+    - [ArkTs 原生反射机制](advanced-topics/arkts-reflection.md)
     - [如何向 Cocos 提交代码](submit-pr/submit-pr.md)
 - [SDK 集成](sdk/index.md)
     - [Facebook 直播和广告](sdk/fb-an-and-live.md)

versions/2.4/zh/advanced-topics/arkts-reflection.md

@@ -0,0 +1,178 @@
+# 基于反射机制实现 JavaScript 与 HarmonyOS Next 系统原生通信
+
+使用 Cocos Creator 2.4.14及以上 打包的鸿蒙原生应用中，我们可以通过反射机制直接在 JavaScript 中调用 ArkTs 的静态方法。它的使用方法很简单：
+
+```js
+// isSync 调用的ArkTs的方法是同步方法或异步方法，如果调用异步的ArkTs方法可能会阻塞当前线程并等待异步回调的结果。
+// clsPath 脚本路径, 例如：entry/src/main/Tests/Test
+// methodName 模块名称/静态方法名称 例如：entry/test(模块名称可省略，省略为clsPath第一个字符串)
+// paramStr 方法入参, 如果是空的，需要传入'', 如果有多个参数，可以转换成JSON字符串
+// result返回值类型只支持基础的三种类型：string，number，boolean，如果需要返回复杂的类型，可以转换为json之后返回
+var result = jsb.reflection.callStaticMethod(isSync, clsPath, methodName, paramStr);
+```
+
+在 callStaticMethod 方法中，我们通过传入 arkTs 是否同步，模块路径或者依赖包名或者远程库名，方法名，参数就可以直接调用 arkTs 的静态方法，并且可以获得 arkTs 方法的返回值。
+
+> callStaticMethod这个函数本身是同步的，但是可以调用异步的ArkTs的异步方法，但是会阻塞当前的线程，等待ArkTs调用完成，然后获取结果返回、
+
+使用场景
+| 场景 | 详细分类 | 说明 |
+| --- | --- | --- |
+| 本地工程模块 | HAP加载模块内文件路径 | 要求路径以moduleName开头 |
+| 本地工程模块 | HAP加载HAR模块名 | - |
+| 远程包 | HAP加载远程HAR模块名 | - |
+| 远程包 | HAP加载ohpm包名 | - |
+| API | HAP加载@ohos.或 @system. | - |
+| 模块Native库 | HAP加载libNativeLibrary.so | - |
+
+>本文示范了本地工程模块的两种场景，其他场景可参阅详细说明使用
+
+
+## 使用示例
+### HAP加载模块内文件路径
+1. 当加载文件中的模块时，如以下ArkTS代码：
+``` ts
+function test(param: string): string {
+  console.log("param::", param);
+  return param;
+}
+
+function syncTest(param: string, cb: Function): void {
+  console.log("param::", param);
+  setTimeout(() => {
+    cb(param);
+  }, 1000)
+}
+
+export { test, syncTest };
+```
+2. 需要在模块的build-profile.json5文件中进行以下配置
+```
+"buildOption": {
+  "arkOptions": {
+    "runtimeOnly": {
+      "sources": [
+        "./src/main/ets/test.ts"
+      ]
+    }
+  }
+}
+```
+3. 游戏中调用
+``` js
+let param = {
+    a:1,
+    b:2
+}
+let o1 = jsb.reflection.callStaticMethod(true, "entry/src/main/ets/test","entry/test",JSON.stringify(param));
+console.log("result::", o1, typeof o1, JSON.parse(o1).a);
+
+let o2 = jsb.reflection.callStaticMethod(false, "entry/src/main/ets/test","entry/syncTest",JSON.stringify(param));
+console.log("result::", o2, typeof o2, JSON.parse(o2).a);
+```
+### HAP加载HAR模块名
+1. HAR包Index.ets文件如下
+``` ts
+function test(param: string): string {
+  console.log("param::", param);
+  return param;
+}
+
+function syncTest(param: string, cb: Function): void {
+  console.log("param::", param);
+  setTimeout(() => {
+    cb(param);
+  }, 1000)
+}
+
+export { test, syncTest };
+```
+2. 在加载本地HAR包时，首先需要在oh-package.json5文件中配置dependencies项
+```
+{
+    "dependencies": {
+        "library": "file:../library"
+    }
+}
+```
+3. 其次，还需要在build-profile.json5中进行配置
+```
+"buildOption": {
+  "arkOptions": {
+    "runtimeOnly": {
+      "packages": [
+        "library"
+      ]
+    }
+  }
+}
+```
+4. 游戏中调用
+``` ts
+let param = {
+    a:1,
+    b:2
+}
+let o1 = jsb.reflection.callStaticMethod("library","entry/test",JSON.stringify(param));
+console.log("result::", o1, typeof o1, JSON.parse(o1).a);
+
+let o2 = jsb.reflection.callStaticMethod("library","entry/syncTest",JSON.stringify(param), false);
+console.log("result::", o2, typeof o2, JSON.parse(o2).a);
+```
+
+## ArkTs 调用 JavaScript
+
+使用 Cocos Creator 2.4.15及以上 打包的鸿蒙原生应用中，C++封装了evalString方法提供给开发者直接从AtkTs直接执行JavaScript代码 使用方法如下：
+
+--- 
+ ** ⚠️注意事项：**
+- 此方法只能在worker线程执行，因此如果有业务需求在主线程执行后调用的话，需要在主线程将结果发送给worker线程后再调用evalString。
+- 此方法需要在worker线程的js引擎初始化完成之后才可以调用，也就是renderContext.nativeEngineInit()执行之后
+- 此方法只能在v8和jsvm两种js引擎中有效，方舟引擎不支持。tips：方舟引擎的js交互可直接在globalThis上绑定对象后访问
+- 此方法只支持返回number，string，boolean，纯对象相较于老办法nativeSdkUtil.gameMsgHandle，性能提升约30%+，推荐使用。
+---
+
+使用示例如下：
+```
+// 游戏侧：
+window.test1 = (a,b) => {
+    return a + b;
+}
+
+window.test2 = (a,b) => {
+    if(a === b)
+        return true;
+    else
+        return false;
+}
+
+window.test3 = (a,b)=>{
+    return (a + b) + "";
+}
+
+window.person = {
+    name: "zhangSan",
+    age: 18
+}
+
+// arkts侧：
+import cocos from 'libcocos.so';
+
+let test1 = cocos.evalString("test1(1,2)");
+console.log("返回结果:", test1, typeof test1);
+
+let test2 = cocos.evalString("test2(2,3)");
+console.log("返回结果:", test2, typeof test2);
+
+let test3 = cocos.evalString("test3(3,4)");
+console.log("返回结果:", test3, typeof test3);
+
+let test4 = cocos.evalString("person");
+console.log("返回结果:", test4.name, typeof test4);
+
+打印结果：
+48604-48719   A03D00/com.coc...harmony/JSAPP  pid-48604             I     返回结果: 3 number
+48604-48719   A03D00/com.coc...harmony/JSAPP  pid-48604             I     返回结果: false boolean
+48604-48719   A03D00/com.coc...harmony/JSAPP  pid-48604             I     返回结果: 7 string
+48604-48719   A03D00/com.coc...harmony/JSAPP  pid-48604             I     返回结果: zhangSan object
+```

versions/2.4/zh/advanced-topics/index.md

@@ -14,6 +14,7 @@
 - [渲染流](render-flow.md)
 - [Java 原生反射机制](java-reflection.md)
 - [Objective-c 原生反射机制](oc-reflection.md)
+- [ArkTs 原生反射机制](arkts-reflection.md)
 - [BMFont 与 UI 自动批处理](ui-auto-batch.md)
 - [动态合图](dynamic-atlas.md)
 - [如何向 Cocos 提交代码](submit-pr/submit-pr.md)

versions/2.4/zh/summary.json

@@ -1222,6 +1222,10 @@
                         "text": "Objective-C 原生反射机制",
                         "link": "advanced-topics/oc-reflection.md"
                     },
+                    {
+                        "text": "ArkTs 原生反射机制",
+                        "link": "advanced-topics/arkts-reflection.md"
+                    },
                     {
                         "text": "如何向 Cocos 提交代码",
                         "link": "submit-pr/submit-pr.md"

versions/3.8/zh/SUMMARY.md

@@ -470,6 +470,7 @@
     - [原生平台二次开发指南](advanced-topics/native-secondary-development.md)
     - [Java 原生反射机制](advanced-topics/java-reflection.md)
     - [Objective-C 原生反射机制](advanced-topics/oc-reflection.md)
+    - [ArkTS 原生反射机制](advanced-topics/arkts-reflection.md)
     - [JsbBridge JS 与 JAVA 通信](advanced-topics/js-java-bridge.md)
     - [JsbBridge JS 与 Objective-C 通信](advanced-topics/js-oc-bridge.md)
     - [JsbBridgeWrapper 基于原生反射机制的事件处理](advanced-topics/jsb-bridge-wrapper.md)

versions/3.8/zh/advanced-topics/arkts-reflection.md

@@ -3,17 +3,17 @@
 使用 Cocos Creator 3.8.5及以上 打包的鸿蒙原生应用中，我们可以通过反射机制直接在 JavaScript 中调用 ArkTs 的静态方法。它的使用方法很简单：
 
 ```js
-// className 脚本路径, 例如：entry/src/main/Tests/Test
-// methodName 模块名称/静态方法名称 例如：entry/test(模块名称可省略，省略为className第一个字符串)
+// clsPath 脚本路径, 例如：entry/src/main/Tests/Test
+// methodName 模块名称/静态方法名称 例如：entry/test(模块名称可省略，省略为clsPath第一个字符串)
 // paramStr 方法入参, 如果是空的，需要传入'', 如果有多个参数，可以转换成JSON字符串
 // isSync 调用的ArkTs的方法是同步方法或异步方法，如果调用异步的ArkTs方法可能会阻塞当前线程并等待异步回调的结果。
 // result返回值类型只支持基础的三种类型：string，number，boolean，如果需要返回复杂的类型，可以转换为json之后返回
-var result = native.reflection.callStaticMethod(className, methodName, paramStr, isSync);
+var result = native.reflection.callStaticMethod(clsPath, methodName, paramStr, isSync);
 ```
 
 在 callStaticMethod 方法中，我们通过传入 arkTs 是否同步，模块路径或者依赖包名或者远程库名，方法名，参数就可以直接调用 arkTs 的静态方法，并且可以获得 arkTs 方法的返回值。
 
-> callStaticMethod这个函数本身是同步的，但是可以调用异步的ArkTs的异步方法，但是会阻塞当前的线程，等待ArkTs调用完成，然后获取结果返回、
+> callStaticMethod这个函数本身是同步的，但是可以调用异步的ArkTs的异步方法，但是会阻塞当前的线程，等待ArkTs调用完成，然后获取结果返回。
 
 使用场景
 | 场景 | 详细分类 | 说明 |
@@ -37,11 +37,6 @@ function test(param: string): string {
   return param;
 }
 
-function test(param: string): string {
-  console.log("param::", param);
-  return param;
-}
-
 function syncTest(param: string, cb: Function): void {
   console.log("param::", param);
   setTimeout(() => {
@@ -123,4 +118,61 @@ console.log("result::", o1, typeof o1, JSON.parse(o1).a);
 
 let o2 = native.reflection.callStaticMethod("library","entry/syncTest",JSON.stringify(param), false);
 console.log("result::", o2, typeof o2, JSON.parse(o2).a);
+```
+
+## ArkTs 调用 JavaScript
+
+使用 Cocos Creator 3.8.6及以上 打包的鸿蒙原生应用中，C++封装了evalString方法提供给开发者直接从AtkTs直接执行JavaScript代码 使用方法如下：
+
+--- 
+ ** ⚠️注意事项：**
+- 此方法只能在worker线程执行，因此如果有业务需求在主线程执行后调用的话，需要在主线程将结果发送给worker线程后再调用evalString。
+- 此方法需要在worker线程的js引擎初始化完成之后才可以调用，也就是renderContext.nativeEngineInit()执行之后
+- 此方法只能在v8和jsvm两种js引擎中有效，方舟引擎不支持。tips：方舟引擎的js交互可直接在globalThis上绑定对象后访问
+- 此方法只支持返回number，string，boolean，纯对象相较于老办法nativeSdkUtil.gameMsgHandle，性能提升约30%+，推荐使用。
+---
+
+使用示例如下：
+```
+// 游戏侧：
+window.test1 = (a,b) => {
+    return a + b;
+}
+
+window.test2 = (a,b) => {
+    if(a === b)
+        return true;
+    else
+        return false;
+}
+
+window.test3 = (a,b)=>{
+    return (a + b) + "";
+}
+
+window.person = {
+    name: "zhangSan",
+    age: 18
+}
+
+// arkts侧：
+import cocos from 'libcocos.so';
+
+let test1 = cocos.evalString("test1(1,2)");
+console.log("返回结果:", test1, typeof test1);
+
+let test2 = cocos.evalString("test2(2,3)");
+console.log("返回结果:", test2, typeof test2);
+
+let test3 = cocos.evalString("test3(3,4)");
+console.log("返回结果:", test3, typeof test3);
+
+let test4 = cocos.evalString("person");
+console.log("返回结果:", test4.name, typeof test4);
+
+打印结果：
+48604-48719   A03D00/com.coc...harmony/JSAPP  pid-48604             I     返回结果: 3 number
+48604-48719   A03D00/com.coc...harmony/JSAPP  pid-48604             I     返回结果: false boolean
+48604-48719   A03D00/com.coc...harmony/JSAPP  pid-48604             I     返回结果: 7 string
+48604-48719   A03D00/com.coc...harmony/JSAPP  pid-48604             I     返回结果: zhangSan object
 ```

versions/3.8/zh/native/overview.md

@@ -9,6 +9,7 @@ Cocos Creator 支持发布为移动端原生应用、移动端网页、移动端
 - [原生平台二次开发指南](../advanced-topics/native-secondary-development.md)
 - [Java 原生反射机制](../advanced-topics/java-reflection.md)
 - [Objective-C 原生反射机制](../advanced-topics/oc-reflection.md)
+- [ArkTS 原生反射机制](../advanced-topics/arkts-reflection.md)
 - [JsbBridge JS 与 JAVA 通信](../advanced-topics/js-java-bridge.md)
 - [JsbBridge JS 与 Objective-C 通信](../advanced-topics/js-oc-bridge.md)
 - [JsbBridgeWrapper 基于原生反射机制的事件处理](../advanced-topics/jsb-bridge-wrapper.md)

versions/3.8/zh/summary.json

@@ -2004,6 +2004,10 @@
                         "text": "Objective-C 原生反射机制",
                         "link": "advanced-topics/oc-reflection.md"
                     },
+                    {
+                        "text": "ArkTs 原生反射机制",
+                        "link": "advanced-topics/arkts-reflection.md"
+                    },
                     {
                         "text": "JsbBridge JS 与 JAVA 通信",
                         "link": "advanced-topics/js-java-bridge.md"