docs: 更新uts插件文档支持鸿蒙开发

docs/plugin/_sidebar.md

@@ -7,5 +7,6 @@
   * [uts中使用uni api](uts-uni-api.md)
   * [Android平台uts开发指南](uts-for-android.md)
   * [iOS平台uts开发指南](uts-for-ios.md)
+  * [harmonyOS平台uts开发指南](uts-for-harmony.md)
   * [使用CocoaPods依赖](uts-ios-cocoapods.md)
 * [插件作者专区](https://uniapp.dcloud.net.cn/plugin/publish.html)

docs/plugin/uts-for-harmony.md

+## uts for harmonyOS
+
+本文旨在帮助 harmonyOS 开发者，快速上手 UTS。注意目前编译到鸿蒙时uts仅能编写uts api，uni-app-x项目不支持编译到harmonyOS。
+
+## 1 了解 UTS 插件是什么
+
+UTS 插件是 uni-app 新型插件形式 [详情](/plugin/uts-plugin)
+
+uts插件在编译到harmonyOS端时会被编译成ArkTs代码。因此编写代码时应注意遵循uts规范+ets规范。
+
+## 2 掌握UTS语法及ArkTs语法
+
+无论是uts还是arkTs都是在ts的语法基础上进行扩展来的。建议先阅读如下文档
+
+- [typescript官方文档](https://www.typescriptlang.org/zh/docs/)
+- [uts语法](https://doc.dcloud.net.cn/uni-app-x/uts/)
+- [AtkTs约束](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/typescript-to-arkts-migration-guide-0000001820879565)
+
+## 3 harmonyOS 原生环境配置
+
+- 参考：[uni-app 开发鸿蒙应用](https://uniapp.dcloud.net.cn/tutorial/harmony/dev.html)
+
+## 4 ArkTs 与 UTS 差异重点介绍 (持续更新)
+
+### 类型差异
+
+#### any类型
+
+ArkTs内不能使用any类型，但是uts内any用处比较多，因此在编译为ArkTs时，any类型被转为了ESObject这个ArkTs特有的类型。
+
+#### 对象字面量
+
+ArkTs不允许无类型的对象字面量，编写代码时应注意为对象字面量指定类型
+
+```ts
+// 错误用法
+const obj = {
+  a: 1
+}
+
+// 正确用法
+interface Obj {
+  a: number
+}
+const obj: Obj = {
+  a: 1
+}
+const obj = {
+  a: 1
+} as Obj
+```
+
+## 5 常见问题
+
+### context的获取
+
+很多鸿蒙原生接口需要传入context作为参数。多数情况下可以直接调用鸿蒙全局方法`getContext()`获取。例如：
+
+```ts
+import settings from '@ohos.settings';
+const context: Context =  getContext();
+settings.getValue(context, settings.display.SCREEN_BRIGHTNESS_STATUS, (err, value) => {
+  if (err) {
+    console.error(`Failed to get the setting. ${err.message} `);
+    return;
+  }
+  console.log(`SCREEN_BRIGHTNESS_STATUS: ${JSON.stringify(value)}`)
+});
+```
\ No newline at end of file

docs/plugin/uts-plugin.md

@@ -16,6 +16,7 @@ uts，全称 uni type script，统一、强类型、脚本语言。
 - web平台，编译为JavaScript
 - Android平台，编译为Kotlin
 - iOS平台，编译为Swift（HX 3.6.7+ 版本支持）
+- 鸿蒙OS平台，编译为ets（HX 4.22+ 版本支持）在现有架构下，ets文件和js文件在同一环境下执行，不涉及类型、通讯等问题。
 
 uts 采用了与 ts 基本一致的语法规范，支持绝大部分 ES6 API。
 
@@ -452,6 +453,13 @@ uts插件在iOS平台的其它原生配置文件，可以在其中配置依赖
 - dependencies-pods：插件需要依赖的 pod 库,  HBuilderX3.8.5+ 版本新增支持
 	+ 有关 dependencies-pods 配置和 CocoaPods 使用的更多细节[详见](https://uniapp.dcloud.net.cn/plugin/uts-ios-cocoapods.html)
 
+#### 鸿蒙原生配置
+
+app-harmony文件夹存放uts插件编译到鸿蒙时的代码逻辑，目前仅支持uts文件。
+
+|目录名/文件名	|用途																				|
+|:---					|:---																				|
+|index.uts		|主入口，interface.uts声明的能力在iOS平台下的实现	|
 
 ## 开发uts插件
 
@@ -569,7 +577,7 @@ export const UTSApiUniErrors : Map<MyApiErrorCode, string> = new Map([
  * 使用时只需要传入特定的错误码即可完成创建。
  */
 export class MyApiFailImpl extends UniError implements MyApiFail {
-
+  override errCode: MyApiErrorCode
   /**
    * 错误对象构造函数
    */
@@ -577,7 +585,7 @@ export class MyApiFailImpl extends UniError implements MyApiFail {
     super();
     this.errSubject = UniErrorSubject;
     this.errCode = errCode;
-    this.errMsg = UTSApiUniErrors[errCode] ?? "";
+    this.errMsg = UTSApiUniErrors.get(errCode) ?? "";
   }
 }
 
@@ -777,6 +785,82 @@ export const myApiSync : MyApiSync = function (paramA : boolean) : MyApiResult {
 }
 ```
 
+> harmonyOS
+
+```ts
+
+/**
+ * 引用鸿蒙系统库，示例如下：
+ * import deviceInfo from "@ohos.deviceInfo";
+ * [可选实现，按需引入]
+ */
+
+/* 引入 interface.uts 文件中定义的变量 */
+import { MyApiOptions, MyApiResult, MyApi, MyApiSync } from '../interface.uts';
+
+/* 引入 unierror.uts 文件中定义的变量 */
+import { MyApiFailImpl } from '../unierror';
+
+/**
+ * 引入三方库
+ * 暂不支持，请留意后续更新
+ */
+
+/**
+ * 异步方法
+ *
+ * uni-app项目中（vue/nvue）调用示例：
+ * 1、引入方法声明 import { myApi } from "@/uni_modules/uts-api"
+ * 2、方法调用
+ * myApi({
+ *   paramA: false,
+ *   complete: (res) => {
+ *      console.log(res)
+ *   }
+ * });
+ *
+ */
+export const myApi : MyApi = function (options : MyApiOptions) {
+
+  if (options.paramA == true) {
+    // 返回数据
+    const res : MyApiResult = {
+      fieldA: 85,
+      fieldB: true,
+      fieldC: 'some message'
+    };
+    options.success?.(res);
+    options.complete?.(res);
+
+  } else {
+    // 返回错误
+    let failResult = new MyApiFailImpl(9010001);
+    options.fail?.(failResult)
+    options.complete?.(failResult)
+  }
+
+}
+
+/**
+ * 同步方法
+ *
+ * uni-app项目中（vue/nvue）调用示例：
+ * 1、引入方法声明 import { myApiSync } from "@/uni_modules/uts-api"
+ * 2、方法调用
+ * myApiSync(true);
+ *
+ */
+export const myApiSync : MyApiSync = function (paramA : boolean) : MyApiResult {
+  // 返回数据，根据插件功能获取实际的返回值
+  const res : MyApiResult = {
+    fieldA: 85,
+    fieldB: paramA,
+    fieldC: 'some message'
+  };
+  return res;
+}
+```
+
 :::
 
 
@@ -997,6 +1081,42 @@ export default function getBatteryLevel():number {
 
 至此，我们已经完成一个 iOS 平台上获取电量的原生能力封装。
 
+#### harmonyOS平台
+
+在utssdk目录下创建harmonyOS平台目录app-harmony
+
+在harmonyOS平台目录下，编辑index.uts，键入以下内容，即可完成harmonyOS平台获取电量能力。
+
+```ts
+import batteryInfo from '@ohos.batteryInfo';
+import { GetBatteryInfo, GetBatteryInfoOptions, GetBatteryInfoSuccess, GetBatteryInfoResult, GetBatteryInfoSync } from '../interface.uts';
+
+export const getBatteryInfoSync : GetBatteryInfoSync = function () : GetBatteryInfoResult {
+  return {
+    level: batteryInfo.batterySOC,
+    isCharging: batteryInfo.chargingStatus === batteryInfo.BatteryChargeState.ENABLE || batteryInfo.chargingStatus === batteryInfo.BatteryChargeState.FULL,
+  };
+}
+
+export const getBatteryInfo : GetBatteryInfo = function (options : GetBatteryInfoOptions) {
+  const batteryInfoResult : GetBatteryInfoSuccess = {
+    errMsg: "getBatteryInfo:ok",
+    level: batteryInfo.batterySOC,
+    isCharging: batteryInfo.chargingStatus === batteryInfo.BatteryChargeState.ENABLE || batteryInfo.chargingStatus === batteryInfo.BatteryChargeState.FULL,
+  }
+  try {
+    options.success && options.success(batteryInfoResult)
+  } catch (e) {
+    console.error(e)
+  }
+  try {
+    options.complete && options.complete(batteryInfoResult)
+  } catch (e) {
+    console.error(e)
+  }
+}
+```
+
 
 ### 应用程序生命周期函数监听@hooksClass
 
@@ -1137,11 +1257,15 @@ HelloUTS nativepage 插件增加了UTSAndroidHookProxy [源码示例](https://gi
 + onCreate回调后应尽可能的判断隐私合规是否同意再初始化，否则影响app上架
 + Android平台添加或修改UTSAndroidHookProxy实现代码需要重新提交云端打包才能生效
 
+#### harmonyOS平台
 
+暂不支持此能力
 
 
 ### `uts`与`uni-app`环境数据交互说明
 
+> harmonyOS目前的架构为ets和js在同一环境下运行，不涉及此章节内容
+
 
 UTS向uni-app传值，支持下列类型：
 
@@ -1359,6 +1483,11 @@ getBatteryCapacity()
 - HBuilderX 3.6.9以下版本，uts插件不支持热刷新，真机需提交云端打包生成[自定义基座](https://uniapp.dcloud.net.cn/tutorial/run/run-app.html#customplayground)
 - HBuilderX 3.6.9+，uts插件，支持本地编译和真机运行 [详情](https://uniapp.dcloud.net.cn/tutorial/run/uts-development-ios.html)
 
+#### harmonyOS平台
+
+- uni-app-x项目暂不支持运行到harmonyOS平台
+- 目前运行到真机或者模拟的需要在鸿蒙DevEco-studio内手动操作
+
 ### 自定义基座
 
 自定义基座支持uts插件。
@@ -1381,6 +1510,7 @@ uts插件支持debug断点调试。可以在uts插件代码中打断点、查看
 
 - [Android debug教程](https://uniapp.dcloud.net.cn/tutorial/debug/uni-uts-debug.html)
 - [iOS debug教程](https://uniapp.dcloud.net.cn/tutorial/debug/uni-uts-debug-ios.html)
+- [ArkTs debug教程](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides-V5/ide-debug-arkts-breakpoint-0000001807387305-V5)
 
 #### Bug&Tips
 - Android平台不支持跨进程调试/日志打印，即 console.log 目前只能在当前进程生效，开发多进程应用时，暂时无法打印日志到控制台