uts-for-android.md 11.5 KB
Newer Older
杜庆泉's avatar
杜庆泉 已提交
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49
## 写在最前

本文旨在 引导Android开发者,快速上手UTS插件开发

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


## 1 了解UTS插件是什么


`UTS插件`是最新发布的`uni-app`新型插件形式,拥有跨平台,高效率,易调试等优点

[更多介绍看这里](https://uniapp.dcloud.net.cn/plugin/uts-plugin.html#)



对于Android开发者来说,我们需要了解的是

1 编译时:当我们在保存`UTS`源码文件时,IDE会同步将其编译为对应的Kotlin代码。

2 运行时:在真机运行/云打包时,这些编译后的kotlin源码也会成为apk的一部分



## 2 掌握UTS语法


开发UTS插件的第一步是掌握UTS语法


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

因为UTS语法与kotlin很类似,可以从2.4 章节 开始阅读。

建议快速阅读后,在实践中掌握这UTS语法。


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


与js相比,uts的语法和java更加类似。

但是依然存在较大的差异,需要详细阅读2.3语法部分。


尽管开发UTS插件,并不要求一定掌握kotlin,但是鉴于`UTS`目前在android平台上,会编译为kotlin源码。

学习kotlin语言,方便排查问题和复杂功能实现

杜庆泉's avatar
杜庆泉 已提交
50
因此建议学习一下2.3 章节 kotlin语法
杜庆泉's avatar
杜庆泉 已提交
51 52 53 54 55 56 57



### 2.3 kotlin 语法部分

建议掌握kotlin语法,可以参考下面的文档

杜庆泉's avatar
杜庆泉 已提交
58
+ kotlin [文档](https://kotlinlang.org/)
杜庆泉's avatar
杜庆泉 已提交
59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81

+ kotlin for android[文档](https://developer.android.com/kotlin)


### 2.4 UTS语法部分

uts,全称 uni type script,是一门跨平台的、高性能的、强类型的现代编程语言。


> 它可以被编译为不同平台的编程语言,如:
> 
> web平台,编译为JavaScript
> 
> Android平台,编译为Kotlin
> 
> iOS平台,编译Swift(暂未发布)
> 
> uts 采用了与 ts 基本一致的语法规范,支持绝大部分 ES6 API。


uts语法详细介绍:[uts语法介绍](https://uniapp.dcloud.net.cn/tutorial/syntax-uts)


82

杜庆泉's avatar
杜庆泉 已提交
83 84 85 86 87 88 89 90 91 92
## 3 Android原生环境配置 (目前版本暂不支持)


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

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


注意:

93
+ 1 本章节内的实例代码均取自Hello UTS [项目地址](https://gitcode.net/dcloud/hello-uts)
杜庆泉's avatar
杜庆泉 已提交
94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153
+ 2 本章节设计的配置,均需自定义基座后才能生效



### 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
杜庆泉 已提交
154
![](https://native-res.dcloud.net.cn/images/uts/forAndroid/uts_android_res_folder.jpg)
杜庆泉's avatar
杜庆泉 已提交
155 156 157 158 159 160 161 162 163 164 165 166 167 168


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

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


除了这里列出的layout,values目录外,还支持anim等所有android标准资源目录


### 3.3 配置asset资源

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

169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187

![目录结构](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
杜庆泉 已提交
188 189 190

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

191 192 193 194




杜庆泉's avatar
杜庆泉 已提交
195 196 197 198 199

### 3.4 增加libs依赖资源

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

杜庆泉's avatar
杜庆泉 已提交
200
![](https://native-res.dcloud.net.cn/images/uts/forAndroid/uts_android_libs_folder.jpg)
杜庆泉's avatar
杜庆泉 已提交
201 202 203 204 205 206


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

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

207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265
------

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
+--- 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
杜庆泉 已提交
266 267


268
## 4 Kotlin与UTS差异重点介绍 (持续更新)
杜庆泉's avatar
杜庆泉 已提交
269 270 271 272 273

通过上面的章节的阅读。

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

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

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

277
### 4.1 语法差异
杜庆泉's avatar
杜庆泉 已提交
278

279 280 281
-------------------------------

#### 4.1.1 可为空的语法标识
杜庆泉's avatar
杜庆泉 已提交
282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300

kotlin中可为空的语法统一为类型后加`?`,已下面的代码为例

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

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

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

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

301
#### 4.1.2  let和var
杜庆泉's avatar
杜庆泉 已提交
302 303 304 305 306 307 308 309

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

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

推荐使用`let` 因为只会在作用域内生效,需要慎用`var`,因为它具备有更大的作用范围


310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336
#### 4.1.3 方法定义

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

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

```ts
 // 成员方法
 startListener():void{
	 
 }
```
 
```uts
 // 全局方法方法
 function startListener():void{
	 
 }
```


#### 4.1.4 extends
杜庆泉's avatar
杜庆泉 已提交
337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356

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

|语法|kotlin|uts|
|---|-------|---|
|继承类|:|extends|
|实现接口|:|extends|


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


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

357 358 359 360



#### 4.1.5 非空断言
杜庆泉's avatar
杜庆泉 已提交
361 362 363 364 365 366 367 368 369 370 371 372

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

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

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


373
#### 4.1.6 快速调用父类实现
杜庆泉's avatar
杜庆泉 已提交
374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390


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

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


391
#### 4.1.7 匿名内部类
杜庆泉's avatar
杜庆泉 已提交
392

杜庆泉's avatar
杜庆泉 已提交
393
`kotlin`中可以使用匿名内部类
杜庆泉's avatar
杜庆泉 已提交
394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415

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



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

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

416 417 418
---------------------------------

### 4.2 警告优化
杜庆泉's avatar
杜庆泉 已提交
419

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

#### 4.2.1 java lang包的引入问题
杜庆泉's avatar
杜庆泉 已提交
423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442

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

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


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

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

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


443
#### 4.2.2 `UTS` 不建议使用 快捷构造
杜庆泉's avatar
杜庆泉 已提交
444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466

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

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


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

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

}
```

467
#### 4.2.3 `UTS` 中下划线前缀的变量,有屏蔽未使用警告的含义
杜庆泉's avatar
杜庆泉 已提交
468 469 470 471 472 473 474 475 476 477 478 479 480 481

```uts
// IDE会提示 name,status,desc 变量未使用
onStatusUpdate(name:string, status:Int, desc:string){
	
}


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

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

483 484


杜庆泉's avatar
杜庆泉 已提交
485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501
## 5  常见问题(持续更新)

### 5.1 如何在UTS环境中,新建一个`activity`?

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

路径:
> ~\uni_modules\uts-nativepage


### 5.2 如何在UTS环境中,新建一个`service`?

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

路径:
> ~\uni_modules\uts-nativepage