uts doc update

1e56bce7 · 杜庆泉 · 0b8bb376 · 0b8bb376 · 1e56bce7 · 0b8bb376
9 changed file
--- a/doc/new_uts_plugin.jpg
+++ b/doc/new_uts_plugin.jpg
--- a/doc/new_uts_plugin3.jpg
+++ b/doc/new_uts_plugin3.jpg
--- a/doc/uni_modules.jpg
+++ b/doc/uni_modules.jpg
--- a/doc/uts_osapi_demo.jpg
+++ b/doc/uts_osapi_demo.jpg
--- a/doc/uts插件开发文档.md
+++ b/doc/uts插件开发文档.md
-## 1 前置条件
-+ 1 HX 3.5.6 之后版本
-## 2 uts原生插件介绍
-### 2.1 什么是uts原生插件
-UTS= Uni Type Script.
-UTS 插件是在uni原生插件的基础上，改用UTS作为插件开发语言。
-进一步降低插件开发门槛，平台差异，执行效率的新型插件形式
-![uts插件结构](./UTS结构示意图1.png)
-### 2.2 uts原生插件与uni原生插件的区别
-|-|传统原生插件|uts原生插件|
-|-|-------|--------|
-|开发语言|java/oc|uts|
-|开发环境|Android studio/XCode|HBuilderX|
-|打包方式|外挂aar 等产出物|编译时生成原生代码|
-优点：
-1  减少原生环境搭建环节，降低插件开发难度
-2  进一步降低平台差异，一种语言开发两个平台插件
-2  编译时生成原生代码，提高代码执行效率
-## 3 UTS语法介绍
-## 4 开发UTS插件
-### 4.1  uni_modules
-确保项目根目录存在uni_modules文件夹
-![插件目录](./uni_modules.jpg)
-`uni_modules`类似 NPM中的`node_modules`.是用来存放插件依赖的文件夹。
-如果项目中已存在此目录，则跳过。如果不存在，在需要手动创建一个。
-### 4.2 新建UTS插件
-选中uni_modules文件夹 -->  右键新建插件
-![新建插件1](./new_uts_plugin.jpg)
-选择UTS原生插件
-![新建插件2](./new_uts_plugin2.jpg)
-插件目录结构
-![新建插件3](./new_uts_plugin3.jpg)
-### 4.3 清单文件package.json
-package.json为插件的清单文件，里面说明了整个UTS插件的配置信息，下面是一个完整的示例
-```
-{
-  "id": "uts-helloworld",
-  "displayName": "uts-helloworld",
-  "version": "1.0.0",
-  "description": "uts-helloworld",
-  "keywords": [
-    "uts-helloworld"
-],
-  "repository": "",
-  "engines": {
-    "HBuilderX": "^3.1.0"
-  },
-  "dcloudext": {
-    "type": "native-uts",
-    "sale": {
-      "regular": {
-        "price": "0.00"
-      },
-      "sourcecode": {
-        "price": "0.00"
-      }
-    },
-    "contact": {
-      "qq": ""
-    },
-    "declaration": {
-      "ads": "",
-      "data": "",
-      "permissions": ""
-    },
-    "npmurl": ""
-  },
-  "uni_modules": {
-    "dependencies": [],
-    "encrypt": [],
-    "platforms": {
-      "cloud": {
-        "tcb": "u",
-        "aliyun": "u"
-      },
-      "client": {
-        "Vue": {
-          "vue2": "u",
-          "vue3": "u"
-        },
-        "App": {
-          "app-vue": "u",
-          "app-nvue": "u"
-        },
-        "H5-mobile": {
-          "Safari": "u",
-          "Android Browser": "u",
-          "微信浏览器(Android)": "u",
-          "QQ浏览器(Android)": "u"
-        },
-        "H5-pc": {
-          "Chrome": "u",
-          "IE": "u",
-          "Edge": "u",
-          "Firefox": "u",
-          "Safari": "u"
-        },
-        "小程序": {
-          "微信": "u",
-          "阿里": "u",
-          "百度": "u",
-          "字节跳动": "u",
-          "QQ": "u",
-          "钉钉": "u",
-          "快手": "u",
-          "飞书": "u",
-          "京东": "u"
-        },
-        "快应用": {
-          "华为": "u",
-          "联盟": "u"
-        }
-      }
-    },
-    "type": "uts",
-    "uts": {
-        "android": {
-            "libs": [],
-            "dependencies": []
-        },
-        "ios": {
-            "libs": []
-        }
-    }
-  }
-}
-```
-## 5 使用插件
-### 5.1 引用UTS插件
-uts插件import有两种方式
-import {a,b} from 'xxx'
-```
-import {
-  callWithoutParam,
-  callWithStringParam,
-  callWithJSONParam
-} from "../../../uni_modules/uts-helloworld";
-```
-import X from 'XXX'
-### 5.2 用法
-延迟操作
-```
-//执行延迟操作
-var timer = setTimeout(function, 1000);
-//取消延迟操作
-clearTimeout(timer);
-```
-定时操作
-```
-//执行定时操作
-var timer = setInterval(function, 1000);
-//取消定时操作
-clearInterval(timer);
-```
-## 6 测试
-### 5.1 真机运行
-直接运行
-### 5.2 云端打包
-### 5.3 示例项目
-### 一个简单的示例
-### 插件目录结构
-### 插件使用方法
-完整的示例项目地址：
--- a/pages/SystemAPI/battery/battery.vue
+++ b/pages/SystemAPI/battery/battery.vue
-<template>
-    <view>当前电量：{{ capacity }}</view>
-</template>
-<script lang="ts" setup>
-import { ref } from 'vue';
-import { getBatteryCapacity } from '../../uni_modules/test-uts-battery'
-const capacity = ref(getBatteryCapacity())
-</script>
\ No newline at end of file
--- a/pages/tabBar/Primer/Primer.vue
+++ b/pages/tabBar/Primer/Primer.vue
@@ -10,11 +10,12 @@
 	</view>
 </template>
 <script>
-	import {
+	// import {
-	  callWithoutParam,
+	//   callWithoutParam,
-	  callWithStringParam,
+	//   callWithStringParam,
-	  callWithJSONParam
+	//   callWithJSONParam
-	} from "../../../uni_modules/uts-helloworld";
+	// } from "../../../uni_modules/uts-helloworld";
+	import * as UTSHello from "../../../uni_modules/uts-helloworld";
 	export default {
 		data() {
@@ -27,7 +28,7 @@
 		},
 		methods: {
 			testDoSthWithCallback: function () {
-				callWithoutParam({
+				UTSHello.callWithoutParam({
 					success:function(){
 						uni.showToast({
 							title:'成功调用uts插件uts-helloworld的callWithoutParam',
@@ -37,7 +38,7 @@
 				});
 			},
 			testDoSthWithString: function () {
-				callWithStringParam(
+				UTSHello.callWithStringParam(
 					this.stringParam,
 					function(response){
 						uni.showToast({
@@ -53,7 +54,7 @@
 					inputText:this.stringParam
 				}
-				callWithJSONParam({
+				UTSHello.callWithJSONParam({
 					input:inputObject,
 					success:function(response){
 						console.log(response);

--- a/readme.md
+++ b/readme.md
-## 1 前置条件
+## 1 UTS原生插件介绍
-+ 1 HX 3.5.6 之后版本
+### 1.1 什么是uts原生插件
-## 2 uts原生插件介绍
+UTS原生插件 是用UTS作为插件开发语言的一种新型插件形式。
-### 2.1 什么是uts原生插件
-UTS= Uni Type Script.
-UTS 插件是在uni原生插件的基础上，改用UTS作为插件开发语言。
-进一步降低插件开发门槛，平台差异，执行效率的新型插件形式
 ![uts插件结构](./doc/UTS结构示意图1.png)
-### 2.2 uts原生插件与uni原生插件的区别
+### 1.2 uts原生插件与uni原生插件的区别
 |-|传统原生插件|uts原生插件|
 |-|-------|--------|
@@ -32,97 +24,156 @@ UTS 插件是在uni原生插件的基础上，改用UTS作为插件开发语言
 2  编译时生成原生代码，提高代码执行效率
-## 3 UTS语法介绍
+## 2 创建UTS插件
-## 4 开发UTS插件
+### 2.1 UTS插件目录结构
-### 4.1  uni_modules
+首先确保项目根目录存在uni_modules文件夹
-确保项目根目录存在uni_modules文件夹
 ![插件目录](./doc/uni_modules.jpg)
-`uni_modules`类似 NPM中的`node_modules`.是用来存放插件依赖的文件夹。
+如果不存在，需要手动创建一个。
-如果项目中已存在此目录，则跳过。如果不存在，在需要手动创建一个。
+[关于uni_modules的详细说明](https://uniapp.dcloud.net.cn/plugin/uni_modules.html#%E4%BB%80%E4%B9%88%E6%98%AF-uni-modules)
-### 4.2 新建UTS插件
+### 2.2 新建步骤拆解
-选中uni_modules文件夹 -->  右键新建插件
+选中**uni_modules**目录 -- 右键 -- 新建插件
 ![新建插件1](./doc/new_uts_plugin.jpg)
-选择UTS原生插件
+选择 **UTS原生插件**
 ![新建插件2](./doc/new_uts_plugin2.jpg)
-插件目录结构
+UTS插件目录结构
 ![新建插件3](./doc/new_uts_plugin3.jpg)
-### 4.3 清单文件package.json
+### 2.3 清单文件package.json
-package.json为插件的清单文件，里面说明了整个UTS插件的配置信息，下面是一个完整的示例
+package.json为插件的清单文件，这里集成了整个UTS插件的配置信息，下面是一个完整的示例
 ```
 {
  "id": "uts-helloworld",
-  "displayName": "uts-helloworld",
+  "displayName": "UTS插件示例",
-  "version": "1.0.0",
+  "version": "0.1",
-  "description": "uts-helloworld",
+  "description": "UTS插件示例",
-  "keywords": [
+  "uni_modules": {
-    "uts-helloworld"
+    "type": "uts",
-],
+    "uts": {
+      "android": {
+        "libs": [
+          "xxx.aar"
+        ],
+        "dependencies": [{
+          "id": "com.xxx.richtext:richtext",
+          "source": "implementation 'com.xxx.richtext:richtext:3.0.7'"
+        }],
+        "minSdkVersion": 21
+      },
+      "ios": {
+        "libs": [
+          "xxx.a"
+        ]
+      },
+      "dependencies": [
+        "xxx.uts"
+      ]
+    }
+  }
 }
 ```
-## 5 使用插件
-### 5.1 引用UTS插件
-uts插件import有两种方式
+## 3 开发UTS原生插件
-import {a,b} from 'xxx'
+以android平台获取电量为例，介绍UTS原生插件开发步骤
+第一步 在android平台目录下，编辑index.uts,键入以下内容
+![OSAPI示例](./doc/uts_osapi_demo.jpg)
+index.uts
 ```
-import {
+// 引用android api
-  callWithoutParam,
+import Context from "android.content.Context";
-  callWithStringParam,
+import BatteryManager from "android.os.BatteryManager";
-  callWithJSONParam
+// 引用uts环境 api
-} from "../../../uni_modules/uts-helloworld";
+import { getAppContext } from "io.dcloud.uts.android";
+export function getBatteryCapacity(): string {
+	// 获取android系统 application上下文
+    const context = getAppContext();
+    if (context != null) {
+        const manager = context.getSystemService(
+            Context.BATTERY_SERVICE
+        ) as BatteryManager;
+        const currentLevel: number = manager.getIntProperty(
+            BatteryManager.BATTERY_PROPERTY_CAPACITY
+        );
+        return '' + currentLevel + '%';
+    }
+    return "0%";
+}
 ```
-import X from 'XXX'
+保存时，触发自动编译。
+至此，我们已经完成一个android平台上获取电量的原生能力封装。
-### 5.2 用法
+在引用了此插件的项目中，我们可以像使用普通js函数一样，使用getBatteryCapacity函数来获取设备电量
+## 4 使用插件
+### 4.1 引用UTS插件
+uts插件的引入 遵循ES6的import语法
+下面介绍两种常见的引入方式
+1 显性的引用
-延迟操作
 ```
-//执行延迟操作
+//引用
-var timer = setTimeout(function, 1000);
+import {
-//取消延迟操作
+  getBatteryCapacity,
-clearTimeout(timer);
+} from "../../../uni_modules/uts-helloworld";
+// 使用代码
+getBatteryCapacity()
 ```
-定时操作
+2 泛型引用
 ```
-//执行定时操作
+// 引用
-var timer = setInterval(function, 1000);
+import * as UTSHello from "../../../uni_modules/uts-helloworld";
-//取消定时操作
+// 使用代码
-clearInterval(timer);
+UTSHello.getBatteryCapacity()
 ```
-## 6 测试
+## 5 测试
 ### 5.1 真机运行
-直接运行
+UTS原生插件与运行调试没有差异，可以直接运行测试。
+需要注意的是，如果是涉及自定义信息，需要选择自定义基座运行
 ### 5.2 云端打包
@@ -130,10 +181,6 @@ clearInterval(timer);
 ### 5.3 示例项目
-### 一个简单的示例
-### 插件目录结构
-### 插件使用方法
 完整的示例项目地址：
--- a/uni_modules/uts-helloworld/app-android/index.uts
+++ b/uni_modules/uts-helloworld/app-android/index.uts
@@ -11,7 +11,6 @@ type StringParamOptions = {
  complete: (res: string) => void;
 };
 type inputJSON = {
 	inputText:string,
 	errCode:number
@@ -29,32 +28,23 @@ type JsonParamOptions = {
 * @param opts
 */
 export function callWithoutParam(opts: NoParamOptions) {
-	setTimeout(function() {
+  opts.success();
-		opts.success();
-	}, 500);
  return { name: "doSthWithCallback" };
 }
 export function callWithStringParam(input:string,success: (res: string) => void) {
+  success(input);
-	setTimeout(function() {
-		success(input);
-	}, 500);
  return { name: "doSthWithCallback" };
 }
 export function callWithJSONParam(opts: JsonParamOptions) {
 	opts.input.errCode = 10;
-	setTimeout(function() {
+	opts.success(opts.input);
-		opts.success(opts.input);
-	}, 500);
  return { name: "doSthWithCallback" };
 }