uts-for-android.md 24.8 KB
Newer Older
W
wanganxp 已提交
1
## uts for Android
杜庆泉's avatar
杜庆泉 已提交
2

W
wanganxp 已提交
3
本文旨在帮助Android开发者,快速上手UTS。
杜庆泉's avatar
杜庆泉 已提交
4 5 6 7 8 9

需要阅读者具备Android原生应用开发经验。


## 1 了解UTS插件是什么

W
wanganxp 已提交
10
`UTS插件``uni-app`新型插件形式,拥有跨平台,高效率,易调试等优点。[详情](https://uniapp.dcloud.net.cn/plugin/uts-plugin.html#)
杜庆泉's avatar
杜庆泉 已提交
11

W
wanganxp 已提交
12
对于Android开发者来说,我们需要了解的是:
杜庆泉's avatar
杜庆泉 已提交
13

W
wanganxp 已提交
14 15
1. 编译时:当我们在保存`UTS`源码文件时,IDE会同步将其编译为对应的Kotlin代码。
2. 运行时:在真机运行/云打包时,这些编译后的kotlin源码也会成为apk的一部分
杜庆泉's avatar
杜庆泉 已提交
16 17 18 19 20

## 2 掌握UTS语法

### 2.1  对于掌握kotlin语言者

W
wanganxp 已提交
21
因为UTS语法与kotlin很类似,建议快速阅读后,在实践中掌握这UTS语法。[uts语法介绍](https://uniapp.dcloud.net.cn/tutorial/syntax-uts)
杜庆泉's avatar
杜庆泉 已提交
22 23 24

### 2.2  对于仅掌握java语言者

W
wanganxp 已提交
25
与js相比,uts的语法和java更加类似。但是依然存在较大的差异,需要详细阅读2.3语法部分。
杜庆泉's avatar
杜庆泉 已提交
26

W
wanganxp 已提交
27
尽管开发UTS插件,并不要求一定掌握kotlin,但是鉴于`UTS`目前在android平台上,会编译为kotlin源码。学会kotlin语言,方便排查问题和复杂功能实现。
杜庆泉's avatar
杜庆泉 已提交
28

W
wanganxp 已提交
29
因此建议学习一下kotlin语法。
杜庆泉's avatar
杜庆泉 已提交
30

W
wanganxp 已提交
31
+ kotlin [https://kotlinlang.org/](https://kotlinlang.org/)
杜庆泉's avatar
杜庆泉 已提交
32

W
wanganxp 已提交
33
+ kotlin for android [https://developer.android.com/kotlin](https://developer.android.com/kotlin)
杜庆泉's avatar
杜庆泉 已提交
34

W
wanganxp 已提交
35
### 2.3 数据类型差异
36 37 38 39 40 41 42

虽然 UTS 和 koltin 在数据类型上基本保持了一致,但是在部分场景下,还是会有差异,在此特别说明

原则上:  

**数据类型以UTS 内置的类型为准, 各原生平台都会对其自动适配。**

杜庆泉's avatar
杜庆泉 已提交
43
**但是 UTS本身是跨平台语言,当具体平台的api 有明确要求时,需要以对方明确要求的数据类型为准。**
44

杜庆泉's avatar
杜庆泉 已提交
45
-------------------------
46

杜庆泉's avatar
杜庆泉 已提交
47 48

#### 举例一: Int 和Number
49

杜庆泉's avatar
杜庆泉 已提交
50
默认情况下`UTS` 开发者可以使用 `Number` 覆盖`android` 平台上使用 `Int`的场景。
51

杜庆泉's avatar
杜庆泉 已提交
52
但是当开发者重写  `Service` 组件`onStartCommand` 方法时,`Android` API要求 明确要求后两个参数 必须为Int
53 54

 
杜庆泉's avatar
杜庆泉 已提交
55
原生开发环境中,应该这样写:
杜庆泉's avatar
杜庆泉 已提交
56

杜庆泉's avatar
杜庆泉 已提交
57 58
 ```kotlin
 override fun onStartCommand(intent: Intent, flags: Int, startId: Int): Int {
杜庆泉's avatar
杜庆泉 已提交
59
	return super.onStartCommand(intent, flags, startId);
杜庆泉's avatar
杜庆泉 已提交
60
 }
杜庆泉's avatar
杜庆泉 已提交
61
 ```
杜庆泉's avatar
杜庆泉 已提交
62 63


杜庆泉's avatar
杜庆泉 已提交
64
 标准的TS环境中,只有`Number`类型而没有`Int`类型
65

杜庆泉's avatar
杜庆泉 已提交
66
 为了适应这种情况,UTS 允许开发者使用原生平台的数据类型Int,来满足原生API对数据类型的要求:
杜庆泉's avatar
杜庆泉 已提交
67 68

```ts
杜庆泉's avatar
杜庆泉 已提交
69
 override onStartCommand(intent:Intent ,flags:Int ,startId:Int):Int {
杜庆泉's avatar
杜庆泉 已提交
70
	return super.onStartCommand(intent, flags, startId);
杜庆泉's avatar
杜庆泉 已提交
71
 }
杜庆泉's avatar
杜庆泉 已提交
72 73 74
```


杜庆泉's avatar
杜庆泉 已提交
75

杜庆泉's avatar
杜庆泉 已提交
76

杜庆泉's avatar
杜庆泉 已提交
77
#### 举例二:`MutableList`
78 79 80
 
`MutableList``android`平台 特有的数据类型,一般场景下,可以使用UTS中内置类型 `Array` 替代

杜庆泉's avatar
杜庆泉 已提交
81
但是在 调用`onAppActivityRequestPermissionsResult` 函数监听权限申请结果时,明确要求使用此类型的参数
杜庆泉's avatar
杜庆泉 已提交
82

杜庆泉's avatar
杜庆泉 已提交
83
在原生环境中,应该这样写:
杜庆泉's avatar
杜庆泉 已提交
84 85

```kotlin
杜庆泉's avatar
杜庆泉 已提交
86

杜庆泉's avatar
杜庆泉 已提交
87 88 89
onAppActivityRequestPermissionsResult(fun(requestCode: Number, permissions: MutableList<String>, grantResults: MutableList<Number>){
      
});
杜庆泉's avatar
杜庆泉 已提交
90 91
```

杜庆泉's avatar
杜庆泉 已提交
92

杜庆泉's avatar
杜庆泉 已提交
93
标准的TS环境中,没有`MutableList`类型,与之相近的数据类型是 `Array`
杜庆泉's avatar
杜庆泉 已提交
94

杜庆泉's avatar
杜庆泉 已提交
95
为了适应这种情况,UTS 允许开发者使用原生平台的数据类型`MutableList`,来满足原生平台API对数据类型的要求:
杜庆泉's avatar
杜庆泉 已提交
96

97 98
```ts
onAppActivityRequestPermissionsResult((requestCode: number,permissions: MutableList<string>,grantResults: MutableList<number>) => {
杜庆泉's avatar
杜庆泉 已提交
99
	
100 101 102 103
});

```

杜庆泉's avatar
杜庆泉 已提交
104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120
### 2.4 线程环境差异

UTS环境中,默认是没有线程概念的。 代码默认执行在uts 单独的线程池中。

如果需要执行异步任务,建议通过内置函数`setTimeOut`执行

```uts
console.log("这里是UTS默认线程 :"  + Thread.currentThread().getName())
setTimeOut(function(){
	console.log("这里是异步任务线程 :"  + Thread.currentThread().getName())
},1000)
```

如果是android原生api 需要部分代码必须执行在UI线程,则需要通过原生api进行操作:

```uts
class AddUIRunnable extends Runnable {
杜庆泉's avatar
杜庆泉 已提交
121
	override run():void {
杜庆泉's avatar
杜庆泉 已提交
122 123 124 125 126 127 128 129 130
		// do something
		console.log("这里是android平台主线程 :"  + Thread.currentThread().getName())
    }
};
let uiRunable = new AddUIRunnable();
getUniActivity()!.runOnUiThread(uiRunable)
```


W
wanganxp 已提交
131
## 3 Android原生环境配置
杜庆泉's avatar
杜庆泉 已提交
132 133 134 135 136 137 138

对于Android项目来说,除了源码之外,还会涉及依赖,资源,配置等常见问题

本章节将会介绍,UTS插件开发环境中如何配置这些属性

注意:

139
+ 1 本章节内的实例代码均取自Hello UTS [项目地址](https://gitcode.net/dcloud/hello-uts)
杜庆泉's avatar
杜庆泉 已提交
140
+ 2 本章节设计的配置,均需自定义基座后才能生效
杜庆泉's avatar
杜庆泉 已提交
141
+ 3 R文件的自动生成,已经在HBuilder X 3.6.9 版本支持,请使用最新版本开发
杜庆泉's avatar
杜庆泉 已提交
142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196

### 3.1 配置AndroidManifest.xml

以hello UTS中的native-page插件中的配置文件为例:

示例文件在hello uts中的位置:

~\uni_modules\uts-nativepage\utssdk\app-android\AndroidManifest.xml

AndroidManifest.xml示例:

```xml
<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android" xmlns:tools="http://schemas.android.com/tools" 
  // 配置包名
  package="io.dcloud.uni_modules.uts_nativepage">
   // 配置权限
   <!--创建前台服务权限-->
   <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />

    <application>
	   // 配置service / activity
	   <service android:name="uts.sdk.modules.utsNativepage.ForeService"  />
       <activity android:name="uts.sdk.modules.utsNativepage.DemoActivity"></activity>
    </application>
</manifest>

```


AndroidManifest.xml配置规则与android中的规则是一致的。


特别提示:

每一个UTS插件对应android项目中的一个 lib module.

与你在android studio中手动输入包名不同的是,如果你没有手动包名,HX会按照下面的规则默认生成一个:

```
uts插件默认包名规则:

如果是根目录utssdk下的uts插件
	包名:uts.sdk.(插件ID转驼峰)
如果是uni_modules目录下的uts插件
	包名:uts.sdk.modules.(插件ID转驼峰)


举例:
uni-getbatteryinfo -> uts.sdk.modules.uniGetbatteryinfo;
uts-nativepage  ->  uts.sdk.modules.utsNativepage
```

### 3.2 配置res资源

杜庆泉's avatar
杜庆泉 已提交
197
![](https://native-res.dcloud.net.cn/images/uts/forAndroid/uts_android_res_folder.jpg)
杜庆泉's avatar
杜庆泉 已提交
198 199 200 201 202

示例文件在hello uts中的位置:

~\uni_modules\uts-nativepage\utssdk\app-android\res 

W
wanganxp 已提交
203
除了这里列出的layout、values目录外,还支持anim等所有android标准资源目录
杜庆泉's avatar
杜庆泉 已提交
204 205 206 207 208

### 3.3 配置asset资源

以hello UTS中的uts-advance插件为例。

209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225
![目录结构](https://native-res.dcloud.net.cn/images/uts/forAndroid/uts_android_assets_folder.jpg)

关键代码:

```ts
// 获取asset管理器
let assetManager = getAppContext()!.getAssets();
// 加载free.mp3 资源
let afd = assetManager.openFd("free.mp3");
// 使用android 自带的媒体组件进行播放
let mediaPlayer = new MediaPlayer();
mediaPlayer.setDataSource(afd.getFileDescriptor(),afd.getStartOffset(), afd.getLength());
mediaPlayer.prepare();
mediaPlayer.start();
```

完整的代码在hello uts中的位置:
杜庆泉's avatar
杜庆泉 已提交
226 227 228 229 230 231 232

~\uni_modules\uts-advance\utssdk\app-android\assets

### 3.4 增加libs依赖资源

以Hello UTS项目下的uts-tencentgeolocation 插件为例

杜庆泉's avatar
杜庆泉 已提交
233
![](https://native-res.dcloud.net.cn/images/uts/forAndroid/uts_android_libs_folder.jpg)
杜庆泉's avatar
杜庆泉 已提交
234 235 236 237 238 239


示例文件在hello uts中的位置:

~\uni_modules\uts-tencentgeolocation\utssdk\app-android\libs 

240 241 242 243 244 245 246 247 248 249 250 251 252 253
------

HX3.6.7 版本内置了以下依赖

开发者在使用列表中的依赖时,需要注意两点:

+  真机运行时,不需要添加列表中的依赖,即可直接引用相关类
+  请勿通过 手动添加jar/aar 等方式引入相同的依赖,否则会因依赖冲突导致云打包失败。

```gradle
+--- my-imageloader.jar
+--- my-nineoldandroids-2.4.0.jar
+--- zip4j-2.8.0.jar
+--- uts-runtime-jvm-1.0.jar
杜庆泉's avatar
杜庆泉 已提交
254
+--- com.google.code.gson:gson@2.8.9.jar
255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299
+--- android-gif-drawable-release@1.2.23.aar
+--- msa_mdid_1.0.13.aar
+--- breakpad-build-release.aar
+--- androidx.multidex:multidex:2.0.0@aar
+--- androidx.recyclerview:recyclerview:1.0.0@aar
+--- androidx.legacy:legacy-support-v4:1.0.0@aar
+--- androidx.appcompat:appcompat:1.0.0@aar
+--- com.github.bumptech.glide:glide:4.9.0@aar
+--- com.alibaba:fastjson:1.1.46.android@jar
+--- androidx.fragment:fragment:1.0.0@aar
+--- androidx.vectordrawable:vectordrawable-animated:1.0.0@aar
+--- androidx.legacy:legacy-support-core-ui:1.0.0@aar
+--- androidx.media:media:1.0.0@aar
+--- androidx.legacy:legacy-support-core-utils:1.0.0@aar
+--- androidx.vectordrawable:vectordrawable:1.0.0@aar
+--- androidx.viewpager:viewpager:1.0.0@aar
+--- androidx.coordinatorlayout:coordinatorlayout:1.0.0@aar
+--- androidx.drawerlayout:drawerlayout:1.0.0@aar
+--- androidx.slidingpanelayout:slidingpanelayout:1.0.0@aar
+--- androidx.customview:customview:1.0.0@aar
+--- androidx.swiperefreshlayout:swiperefreshlayout:1.0.0@aar
+--- androidx.asynclayoutinflater:asynclayoutinflater:1.0.0@aar
+--- androidx.loader:loader:1.0.0@aar
+--- androidx.core:core:1.0.0@aar
+--- androidx.versionedparcelable:versionedparcelable:1.0.0@aar
+--- androidx.collection:collection:1.0.0@jar
+--- androidx.cursoradapter:cursoradapter:1.0.0@aar
+--- com.github.bumptech.glide:gifdecoder:4.9.0@aar
+--- androidx.lifecycle:lifecycle-runtime:2.0.0@aar
+--- androidx.interpolator:interpolator:1.0.0@aar
+--- androidx.documentfile:documentfile:1.0.0@aar
+--- androidx.localbroadcastmanager:localbroadcastmanager:1.0.0@aar
+--- androidx.print:print:1.0.0@aar
+--- androidx.lifecycle:lifecycle-viewmodel:2.0.0@aar
+--- androidx.lifecycle:lifecycle-livedata:2.0.0@aar
+--- androidx.lifecycle:lifecycle-livedata-core:2.0.0@aar
+--- androidx.lifecycle:lifecycle-common:2.0.0@jar
+--- androidx.arch.core:core-runtime:2.0.0@aar
+--- androidx.arch.core:core-common:2.0.0@jar
+--- androidx.annotation:annotation:1.0.0@jar
+--- com.github.bumptech.glide:disklrucache:4.9.0@jar
\--- com.github.bumptech.glide:annotations:4.9.0@jar


```
杜庆泉's avatar
杜庆泉 已提交
300 301


杜庆泉's avatar
杜庆泉 已提交
302 303 304 305 306 307
## 4 Android内置库@iodcloudutsandroid

在uts里,Android的所有api都可以访问。

但Android开发中经常要复写application和activity,uni-app主引擎已经复写了相关类。所以想要操作application和activity,需要调用uni-app引擎封装的API。

杜庆泉's avatar
杜庆泉 已提交
308
这些api在`io.dcloud.uts`库下 UTSAndroid对象,具体见下。
杜庆泉's avatar
杜庆泉 已提交
309 310 311 312 313 314 315 316 317

### 4.1 application 上下文相关

#### 4.1.1 getAppContext

> HBuilderX 3.6.3+


```ts
杜庆泉's avatar
杜庆泉 已提交
318
import { UTSAndroid } from "io.dcloud.uts";
杜庆泉's avatar
杜庆泉 已提交
319 320 321 322 323 324 325 326 327
```

用法说明:获取当前应用Application上下文,对应android平台 Context.getApplicationContext 函数实现

Android开发场景中,调用应用级别的资源/能力,需要使用此上下文。更多用法,参考[Android官方文档](https://developer.android.google.cn/docs)


```ts
// [示例]获取asset下的音频,并且播放
杜庆泉's avatar
杜庆泉 已提交
328
let assetManager = UTSAndroid.getAppContext()!.getAssets();
杜庆泉's avatar
杜庆泉 已提交
329 330 331 332 333 334 335 336 337 338 339 340 341 342
let afd = assetManager.openFd("free.mp3");
let mediaPlayer = new MediaPlayer();
mediaPlayer.setDataSource(afd.getFileDescriptor(),afd.getStartOffset(), afd.getLength());
mediaPlayer.prepare();
mediaPlayer.start();
```


#### 4.1.2 getResourcePath(resourceName:String)

> HBuilderX 3.6.3+


```ts
杜庆泉's avatar
杜庆泉 已提交
343
import { UTSAndroid } from "io.dcloud.uts";
杜庆泉's avatar
杜庆泉 已提交
344 345 346 347 348 349 350
```

获取指定插件资源的运行期绝对路径
 
```ts
// [示例]获取指定资源路径
// 得到文件运行时路径: `/storage/emulated/0/Android/data/io.dcloud.HBuilder/apps/__UNI__3732623/www/uni_modules/test-uts-static/static/logo.png`
杜庆泉's avatar
杜庆泉 已提交
351
UTSAndroid.getResourcePath("uni_modules/test-uts-static/static/logo.png")
杜庆泉's avatar
杜庆泉 已提交
352 353 354 355 356 357 358

```

#### 4.1.3 onAppTrimMemory / offAppTrimMemory

##### onAppTrimMemory

杜庆泉's avatar
杜庆泉 已提交
359
> HBuilderX 3.6.11+
杜庆泉's avatar
杜庆泉 已提交
360 361 362 363 364


App 内存不足时,系统回调函数 对应原生的API: onTrimMemory

```ts
杜庆泉's avatar
杜庆泉 已提交
365
UTSAndroid.onAppTrimMemory((level:Number) => {
杜庆泉's avatar
杜庆泉 已提交
366 367 368 369 370 371 372
	let eventName = "onAppTrimMemory - " + level;
	console.log(eventName);
});
```

##### offAppTrimMemory

杜庆泉's avatar
杜庆泉 已提交
373
> HBuilderX 3.6.11+
杜庆泉's avatar
杜庆泉 已提交
374 375 376 377 378 379 380 381


onAppTrimMemory 对应的反注册函数

如果传入的函数可为空,如果为空,则视为移除所有监听

```ts
// 移除所有监听
杜庆泉's avatar
杜庆泉 已提交
382
UTSAndroid.offAppTrimMemory()
杜庆泉's avatar
杜庆泉 已提交
383
// 移除指定监听
杜庆泉's avatar
杜庆泉 已提交
384
UTSAndroid.offAppTrimMemory((level:Number) => {
杜庆泉's avatar
杜庆泉 已提交
385 386 387 388 389 390 391 392 393
	
});
```


#### 4.1.4 onAppConfigChange / offAppConfigChange

##### onAppConfigChange

杜庆泉's avatar
杜庆泉 已提交
394
> HBuilderX 3.6.1+
杜庆泉's avatar
杜庆泉 已提交
395 396 397 398 399


App 配置发生变化时触发,比如横竖屏切换 对应原生的API: onConfigurationChanged

```ts
杜庆泉's avatar
杜庆泉 已提交
400
UTSAndroid.onAppConfigChange((ret:UTSJSONObject) => {
杜庆泉's avatar
杜庆泉 已提交
401 402 403 404 405 406 407 408 409 410 411 412 413 414
	let eventName = "onAppConfigChange - " + JSON.stringify(ret);
	console.log(eventName);
});
```

##### offAppConfigChange


与onAppConfigChange 对应的反注册函数

如果传入的函数可为空,如果为空,则视为移除所有监听

```ts
// 移除所有监听
杜庆泉's avatar
杜庆泉 已提交
415
UTSAndroid.offAppConfigChange();
杜庆泉's avatar
杜庆泉 已提交
416
// 移除指定监听
杜庆泉's avatar
杜庆泉 已提交
417
UTSAndroid.offAppConfigChange(function(ret){
杜庆泉's avatar
杜庆泉 已提交
418 419 420 421 422 423 424 425 426 427 428 429 430

});
```


--------------------------------


特别说明:除了本章节列出的函数外,android环境下 application 其他上下文方法都可以通过 getAppContext()!.xxx()的方式实现

比如获取app缓存目录:

```
杜庆泉's avatar
杜庆泉 已提交
431
UTSAndroid.getAppContext()!.getExternalCacheDir()!.getPath()
杜庆泉's avatar
杜庆泉 已提交
432 433 434 435 436 437 438
```


### 4.2 Activity 上下文

#### 4.2.1 getUniActivity

杜庆泉's avatar
杜庆泉 已提交
439
> HBuilderX 3.6.11+
杜庆泉's avatar
杜庆泉 已提交
440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460


获取当前插件所属的activity实例,对应android平台 getActivity 函数实现

Android开发场景中,调用活动的级别的资源/能力,需要使用此上下文。更多用法,参考[Android官方文档](https://developer.android.google.cn/docs)

```ts
// [示例]获取当前activity顶层容器
let frameContent = decorView.findViewById<FrameLayout>(android.R.id.content)
```

#### 4.2.2 onAppActivityPause / offAppActivityPause

##### onAppActivityPause

> HBuilderX 3.6.3+


App的activity onPause时触发

```ts
杜庆泉's avatar
杜庆泉 已提交
461
UTSAndroid.onAppActivityPause(() => {
杜庆泉's avatar
杜庆泉 已提交
462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477
    let eventName = "onAppActivityPause - " + Date.now();
    console.log(eventName);
});
```

##### offAppActivityPause

> HBuilderX 3.6.9+

onAppActivityPause 对应的反注册函数

如果传入的函数可为空,如果为空,则视为移除所有监听


```ts
// 移除全部监听
杜庆泉's avatar
杜庆泉 已提交
478
UTSAndroid.offAppActivityPause();
杜庆泉's avatar
杜庆泉 已提交
479
// 移除指定监听
杜庆泉's avatar
杜庆泉 已提交
480
UTSAndroid.offAppActivityPause(() => {
杜庆泉's avatar
杜庆泉 已提交
481 482 483 484 485 486 487 488 489 490 491
});
```



#### 4.2.3 onAppActivityResume / offAppActivityResume

##### onAppActivityResume

> HBuilderX 3.6.3+

杜庆泉's avatar
杜庆泉 已提交
492

杜庆泉's avatar
杜庆泉 已提交
493 494 495 496

App的activity onResume时触发

```ts
杜庆泉's avatar
杜庆泉 已提交
497
UTSAndroid.onAppActivityResume(() => {
杜庆泉's avatar
杜庆泉 已提交
498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513
     let eventName = "onAppActivityResume - " + Date.now();
     console.log(eventName);
});
```

##### offAppActivityResume

> HBuilderX 3.6.9+

onAppActivityResume 对应的反注册函数

如果传入的函数可为空,如果为空,则视为移除所有监听


```ts
// 移除全部监听
杜庆泉's avatar
杜庆泉 已提交
514
UTSAndroid.onAppActivityResume();
杜庆泉's avatar
杜庆泉 已提交
515
// 移除指定监听
杜庆泉's avatar
杜庆泉 已提交
516
UTSAndroid.onAppActivityResume(() => {
杜庆泉's avatar
杜庆泉 已提交
517 518 519 520 521 522 523 524 525 526 527 528 529 530 531
});
```



#### 4.2.4 onAppActivityDestroy / offAppActivityDestroy

##### onAppActivityDestroy

> HBuilderX 3.6.3+


App 的 activity onDestroy时触发

```ts
杜庆泉's avatar
杜庆泉 已提交
532
UTSAndroid.onAppActivityDestroy(() => {
杜庆泉's avatar
杜庆泉 已提交
533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548
     let eventName = "onAppActivityDestroy- " + Date.now();
     console.log(eventName);
});
```

##### offAppActivityDestroy

> HBuilderX 3.6.9+

onAppActivityDestroy 对应的反注册函数

如果传入的函数可为空,如果为空,则视为移除所有监听


```ts
// 移除全部监听
杜庆泉's avatar
杜庆泉 已提交
549
UTSAndroid.offAppActivityDestroy();
杜庆泉's avatar
杜庆泉 已提交
550
// 移除指定监听
杜庆泉's avatar
杜庆泉 已提交
551
UTSAndroid.offAppActivityDestroy(() => {
杜庆泉's avatar
杜庆泉 已提交
552 553 554 555 556 557 558 559 560 561 562 563 564 565 566
});
```



#### 4.2.5 onAppActivityBack / offAppActivityBack

##### onAppActivityBack

> HBuilderX 3.6.3+


App 的 activity 回退物理按键点击时触发

```ts
杜庆泉's avatar
杜庆泉 已提交
567
UTSAndroid.onAppActivityBack(() => {
杜庆泉's avatar
杜庆泉 已提交
568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584
     let eventName = "onAppActivityBack- " + Date.now();
     console.log(eventName);
});

```

##### offAppActivityBack

> HBuilderX 3.6.9+

onAppActivityBack 对应的反注册函数

如果传入的函数可为空,如果为空,则视为移除所有监听


```ts
// 移除全部监听
杜庆泉's avatar
杜庆泉 已提交
585
UTSAndroid.offAppActivityBack();
杜庆泉's avatar
杜庆泉 已提交
586
// 移除指定监听
杜庆泉's avatar
杜庆泉 已提交
587
UTSAndroid.offAppActivityBack(() => {
杜庆泉's avatar
杜庆泉 已提交
588 589 590 591 592 593 594 595 596 597 598 599 600 601
});
```



#### 4.2.6 onAppActivityResult / offAppActivityResult

##### onAppActivityResult

> HBuilderX 3.6.8+

App 的 activity 启动其他activity的回调结果监听 对应原生的 onActivityResult

```ts
杜庆泉's avatar
杜庆泉 已提交
602
UTSAndroid.onAppActivityResult((requestCode: Int, resultCode: Int, data?: Intent) => {
杜庆泉's avatar
杜庆泉 已提交
603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618
	let eventName = "onAppActivityResult  -  requestCode:" + requestCode + " -resultCode:"+resultCode + " -data:"+JSON.stringify(data);
    console.log(eventName);
});
```

##### offAppActivityResult

> HBuilderX 3.6.9+

onAppActivityResult 对应的反注册函数

如果传入的函数可为空,如果为空,则视为移除所有监听


```ts
// 移除全部监听
杜庆泉's avatar
杜庆泉 已提交
619
UTSAndroid.offAppActivityResult();
杜庆泉's avatar
杜庆泉 已提交
620
// 移除指定监听
杜庆泉's avatar
杜庆泉 已提交
621
UTSAndroid.offAppActivityResult(() => {
杜庆泉's avatar
杜庆泉 已提交
622 623 624 625 626 627 628 629 630 631 632 633 634 635
});
```


#### 4.2.7 onAppActivityRequestPermissionsResult / offAppActivityRequestPermissionsResult

##### onAppActivityRequestPermissionsResult

> HBuilderX 3.6.3+


App 的 activity 获得权限请求结果的回调

```ts
杜庆泉's avatar
杜庆泉 已提交
636
UTSAndroid.onAppActivityRequestPermissionsResult((requestCode: number,
杜庆泉's avatar
杜庆泉 已提交
637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661
                                                     permissions: MutableList<string>,
                                                     grantResults: MutableList<number>) => {
		
		console.log(grantResults);
		console.log(permissions);   
		console.log(requestCode);
	});

//发起定位权限申请
ActivityCompat.requestPermissions(getUniActivity()!,
	    arrayOf(Manifest.permission.ACCESS_COARSE_LOCATION), 1001);

```

##### offAppActivityRequestPermissionsResult

> HBuilderX 3.6.9+

onAppActivityRequestPermissionsResult 对应的反注册函数

如果传入的函数可为空,如果为空,则视为移除所有监听


```ts
// 移除全部监听
杜庆泉's avatar
杜庆泉 已提交
662
UTSAndroid.offAppActivityRequestPermissionsResult();
杜庆泉's avatar
杜庆泉 已提交
663
// 移除指定监听
杜庆泉's avatar
杜庆泉 已提交
664
UTSAndroid.offAppActivityRequestPermissionsResult(() => {
杜庆泉's avatar
杜庆泉 已提交
665 666 667 668 669 670 671 672 673 674
});

-----------------------------


特别说明除了本章节列出的函数外android环境下 activity 其他上下文方法都可以通过 getUniActivity()!.xxx()的方式实现

比如获取当前activity的顶层View容器

```ts
杜庆泉's avatar
杜庆泉 已提交
675
UTSAndroid.getUniActivity()!.getWindow().getDecorView();
杜庆泉's avatar
杜庆泉 已提交
676 677 678 679 680 681
```




## 5 Kotlin与UTS差异重点介绍 (持续更新)
杜庆泉's avatar
杜庆泉 已提交
682 683 684 685 686

通过上面的章节的阅读。

至此我们认为你已经掌握了UTS语法,掌握了基本的Kotlin语法,掌握了UTS对于android资源的支持。

W
wanganxp 已提交
687
但是对于一个熟悉android开发的kotlin语言者来说,有很多常用的习惯发生了改变,我们会在这个章节特别指出,便于开发者加深认识。
688

杜庆泉's avatar
杜庆泉 已提交
689

杜庆泉's avatar
杜庆泉 已提交
690
### 5.1 语法差异
杜庆泉's avatar
杜庆泉 已提交
691

692 693
-------------------------------

杜庆泉's avatar
杜庆泉 已提交
694
#### 5.1.1 可为空的语法标识
杜庆泉's avatar
杜庆泉 已提交
695

W
wanganxp 已提交
696
kotlin中可为空的语法统一为类型后加`?`,以下面的代码为例
杜庆泉's avatar
杜庆泉 已提交
697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713

```ts
// 一个可为空的字符串变量,变量名为user
var user:String? = null
```

但是ts中分两种情况,如果是全局变量,可为空,需要这样写

```ts
let user:string | null
```

如果是成员变量,与kotlin类似,但是区别在于?写在变量后,而非类型后
```ts
let user?:string
```

杜庆泉's avatar
杜庆泉 已提交
714
#### 5.1.2  let和var
杜庆泉's avatar
杜庆泉 已提交
715 716 717 718 719

`kotlin`中 可变变量修饰为 `var`、`val`。 区别在于 val 不可变,var可变。

`uts`中对应`var`的变量类型为 `var/let`

W
wanganxp 已提交
720
推荐使用`let` 因为只会在作用域内生效,需要慎用`var`,因为它具备有更大的作用范围
杜庆泉's avatar
杜庆泉 已提交
721 722


杜庆泉's avatar
杜庆泉 已提交
723
#### 5.1.3 方法定义
724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740

方法定义 `kotlin`里的方法只有一种定义方式

```kotlin
 fun startListener():void{
	 
 }
```
uts中,需要区分全局方法、成员方法

```ts
 // 成员方法
 startListener():void{
	 
 }
```
 
W
wanganxp 已提交
741 742
```ts
 // 全局方法
743 744 745 746 747
 function startListener():void{
	 
 }
```

杜庆泉's avatar
杜庆泉 已提交
748
#### 5.1.4 extends
杜庆泉's avatar
杜庆泉 已提交
749 750 751 752 753 754

`kotlin`中的: 继承操作符,需要用`extends`取代

|语法|kotlin|uts|
|---|-------|---|
|继承类|:|extends|
杜庆泉's avatar
杜庆泉 已提交
755
|实现type接口|:|extends|
杜庆泉's avatar
杜庆泉 已提交
756
|实现接口|:|implements|
杜庆泉's avatar
杜庆泉 已提交
757 758 759 760 761 762 763 764 765 766 767 768 769


```kotlin
class MediaContentObserver : ContentObserver {
}
```


```ts
class MediaContentObserver extends ContentObserver {
}
```

杜庆泉's avatar
杜庆泉 已提交
770
#### 5.1.5 非空断言
杜庆泉's avatar
杜庆泉 已提交
771 772 773 774 775 776 777 778 779 780 781 782

kotlin中的非空断言是`!!`,ts中是一个`!`

```ts
user!.sayHello();
```

```kotlin
user!!.sayHello();
```


杜庆泉's avatar
杜庆泉 已提交
783
#### 5.1.6 快速调用父类实现
杜庆泉's avatar
杜庆泉 已提交
784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800


```ts
//ts 中快速实现super
constructor() : super() {
}
	
```

```kotlin
//kotlin 中快速实现super
constructor (){
	super();
}
```


杜庆泉's avatar
杜庆泉 已提交
801
#### 5.1.7 匿名内部类
杜庆泉's avatar
杜庆泉 已提交
802

杜庆泉's avatar
杜庆泉 已提交
803
`kotlin`中可以使用匿名内部类
杜庆泉's avatar
杜庆泉 已提交
804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823

```kotlin
// kotlin 新建事件监听
user.setListener(Listener(){
	//todo
});
```

目前版本UTS还不支持匿名内部类,需要显性的声明再新建

```ts
// 声明一个新的类,实现Listener
class MyListener extends Listener{
	// todo
}
// 新建实例
let myListener = new MyListener();
user.setListener(myListener);
```

杜庆泉's avatar
杜庆泉 已提交
824
#### 5.1.8 可为空函数调用
杜庆泉's avatar
杜庆泉 已提交
825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846


有一种特殊场景,我们需要定义一些可为空的函数变量,比如下面的 success,fail:

```ts
type Option = {
	success?: (res: object) => void;
	fail?: (res: object) => void;
};

```


这个时候我们需要这样调用

```ts
options.success?.(res)
```

这样的调用方式在kotlin中是非法的,属于TS中的特有语法,需要特别注意。


杜庆泉's avatar
杜庆泉 已提交
847
#### 5.1.9 一个类只能有一个构造函数
杜庆泉's avatar
杜庆泉 已提交
848

杜庆泉's avatar
杜庆泉 已提交
849
在`Kotlin`/`java`中允许一个函数有多个构造器,但是UTS中是不被允许的
杜庆泉's avatar
杜庆泉 已提交
850

杜庆泉's avatar
杜庆泉 已提交
851 852


杜庆泉's avatar
杜庆泉 已提交
853
#### 5.1.10 界面跳转写法
杜庆泉's avatar
杜庆泉 已提交
854 855 856 857 858 859 860 861

android开发中场景的 intent跳转需要传入 目标界面的class对象,目前UTS中仅支持一种写法

```uts
let intent = new Intent(getUniActivity(),DemoActivity().javaClass);
getUniActivity()!.startActivity(intent);
```

杜庆泉's avatar
杜庆泉 已提交
862
#### 5.1.11 指定double数据类型
杜庆泉's avatar
杜庆泉 已提交
863 864 865

某些场景下开发者需要获得 指定double数据类型的数据

杜庆泉's avatar
杜庆泉 已提交
866
开发者下意识的写法可能是:
W
wanganxp 已提交
867
```ts
杜庆泉's avatar
杜庆泉 已提交
868
// 这样是错误的
杜庆泉's avatar
杜庆泉 已提交
869 870 871 872 873 874 875
let a:Int =3
let b:Int =4
let c:Double  = a/b
```

但是Android原生环境中,数据类型的精度是向下兼容的,如果想要获得一个double类型,必须要有一个double类型参与运算:

W
wanganxp 已提交
876
```ts
杜庆泉's avatar
杜庆泉 已提交
877
// 这样才是正确的
杜庆泉's avatar
杜庆泉 已提交
878 879 880 881 882
let a:Int =3
let b:Int =4
let c:Double  = a * 1.0 / b
```

杜庆泉's avatar
杜庆泉 已提交
883

884 885
---------------------------------

杜庆泉's avatar
杜庆泉 已提交
886
### 5.2 警告优化
杜庆泉's avatar
杜庆泉 已提交
887

888 889
下面的内容不会影响功能使用,但是在UTS环境中,有合适的解决办法

杜庆泉's avatar
杜庆泉 已提交
890
#### 5.2.1 java lang包的引入问题
杜庆泉's avatar
杜庆泉 已提交
891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910

`kotlin` 或者`java` 中java.lang.*是被特殊处理的,可以直接使用而不需要引入。

```kotlin
// 获取当前时间戳
System.currentTimeMillis()
```


UTS环境中,lang包没有被特殊对待,需要手动引入。

```ts
// 手动引入lang包下的类
import System from 'java.lang.System';

// 获取当前时间戳
System.currentTimeMillis()
```


杜庆泉's avatar
杜庆泉 已提交
911
#### 5.2.2 `UTS` 不建议使用 快捷构造
杜庆泉's avatar
杜庆泉 已提交
912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934

`kotlin`  中 支持通过()的方式,快速实现无参构造器的声明

```kotlin
// 获取当前时间戳
class ScreenReceiver extends BroadcastReceiver(){
  
}
```


UTS环境中,不建议这样做(虽然目前这样做不会影响编译),建议使用手动声明无参构造

```ts
class ScreenReceiver extends BroadcastReceiver{
	
	constructor (){
		super();
	}

}
```

杜庆泉's avatar
杜庆泉 已提交
935
#### 5.2.3 `UTS` 中下划线前缀的变量,有屏蔽未使用警告的含义
杜庆泉's avatar
杜庆泉 已提交
936

W
wanganxp 已提交
937
```ts
杜庆泉's avatar
杜庆泉 已提交
938 939 940 941 942 943 944 945 946 947 948
// IDE会提示 name,status,desc 变量未使用
onStatusUpdate(name:string, status:Int, desc:string){
	
}

// 不会警告变量未使用
onStatusUpdate(_name:string, _status:Int, _desc:string){
	
}
```

杜庆泉's avatar
杜庆泉 已提交
949

杜庆泉's avatar
杜庆泉 已提交
950
## 6  常见问题(持续更新)
杜庆泉's avatar
杜庆泉 已提交
951

杜庆泉's avatar
杜庆泉 已提交
952
### 6.1 如何在UTS环境中,新建一个`activity`?
杜庆泉's avatar
杜庆泉 已提交
953 954 955 956 957 958 959

参考Hello UTS项目中的uts-nativepage插件

路径:
> ~\uni_modules\uts-nativepage


杜庆泉's avatar
杜庆泉 已提交
960
### 6.2 如何在UTS环境中,新建一个`service`?
杜庆泉's avatar
杜庆泉 已提交
961 962 963 964 965 966

参考Hello UTS项目中的uts-nativepage插件

路径:
> ~\uni_modules\uts-nativepage

杜庆泉's avatar
杜庆泉 已提交
967 968 969 970 971 972
### 6.3 如何在UTS环境中,新建一个`Thread`?

简单示例
```uts
class CustomThread extends Thread{
	
杜庆泉's avatar
杜庆泉 已提交
973
	constructor(){
杜庆泉's avatar
杜庆泉 已提交
974 975 976 977
		super();
	}
	
	override run(){
杜庆泉's avatar
杜庆泉 已提交
978 979
		Thread.sleep(1000)
		console.log("CustomThread = " + Thread.currentThread().getName())
杜庆泉's avatar
杜庆泉 已提交
980 981 982 983 984 985 986 987
	}
}
```

完整示例参考Hello UTS项目中的uts-nativepage插件

路径:
> ~\uni_modules\uts-nativepage
杜庆泉's avatar
杜庆泉 已提交
988 989


杜庆泉's avatar
杜庆泉 已提交
990 991 992 993 994 995
### 6.4 如果我要实现一个官方已有的三方SDK功能,比如微信支付,如何处理?

因为android中,每个UTS插件都对应一个gradle 子项目,所以类似的情况不能简单复用 自定义基座中的官方依赖。

需要:  **不要勾选官方的依赖,然后在uts插件中,按照文档配置依赖**

杜庆泉's avatar
杜庆泉 已提交
996 997 998 999 1000 1001
### 6.5 UTSCallback 和 UTSJSONObject 是什么?

UTSCallback 和 UTSJSONObject 是UTS内置专门用于UTS环境和前端交互的特定类型。

uni环境与UTS环境交互时,除了基本数据类型之外,涉及function的需要使用UTSCallback替代,涉及复杂对象object需要用UTSJSONObject 替代

杜庆泉's avatar
杜庆泉 已提交
1002

杜庆泉's avatar
杜庆泉 已提交
1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021
### 6.6 如何生成android平台Array对象

UTS环境中,默认的数组写法[] / Array()  对应到 android平台的数据结构是 `MutableList`

理论上来说 `MutableList`确实更加灵活强大,但是部分android 平台api 明确要求了 Array格式的数据(比如请求权限)

类似场景下,我们就要使用 toTypedArray() 函数进行转换

```typescript

// 得到一个MutableList
let permissionArray :String[] = []
// 得到一个Array
console.log(permissionArray.toTypedArray())

```



杜庆泉's avatar
杜庆泉 已提交
1022 1023 1024 1025
## 7  已知待解决问题(持续更新)

### 7.1 结构入参 boolean 参数默认为true

W
wanganxp 已提交
1026
当以type 结构体为参数时,其内部boolean字段 默认值为false,不支持指定。