## uts for Android 本文旨在帮助Android开发者快速上手UTS。 需要阅读者具备Android原生应用开发经验。 ## 1 了解UTS插件是什么 `UTS插件`是`uni-app`新型插件形式,拥有跨平台,高效率,易调试等优点。[详情](/plugin/uts-plugin) 对于Android开发者来说,我们需要了解的是: 1. 编译时:当我们在保存`UTS`源码文件时,IDE会同步将其编译为对应的Kotlin代码。 2. 运行时:在真机运行/云打包时,这些编译后的kotlin源码也会成为apk的一部分 ## 2 掌握UTS语法 ### 2.1 对于掌握kotlin语言者 因为UTS语法与kotlin很类似,建议快速阅读后,在实践中掌握这UTS语法。[uts语法介绍](/uts/)。 ### 2.2 对于仅掌握java语言者 与js相比,uts的语法和java更加类似。但是依然存在较大的差异,需要详细阅读2.3语法部分。 尽管开发UTS插件,并不要求一定掌握kotlin,但是鉴于`UTS`目前在android平台上,会编译为kotlin源码。学会kotlin语言,方便排查问题和复杂功能实现。 因此建议学习一下kotlin语法。 + kotlin [https://kotlinlang.org/](https://kotlinlang.org/) + kotlin for android [https://developer.android.com/kotlin](https://developer.android.com/kotlin) ### 2.3 数据类型差异 虽然 UTS 和 koltin 在数据类型上基本保持了一致,但是在部分场景下,还是会有差异,在此特别说明 原则上: **数据类型以UTS 内置的类型为准, 各原生平台都会对其自动适配。** **但是 UTS本身是跨平台语言,当具体平台的api 有明确要求时,需要以对方明确要求的数据类型为准。** ------------------------- #### 举例一: Int 和Number 默认情况下`UTS` 开发者可以使用 `Number` 覆盖`android` 平台上使用 `Int`的场景。 但是当开发者重写 `Service` 组件`onStartCommand` 方法时,`Android` API要求 明确要求后两个参数 必须为Int 原生开发环境中,应该这样写: ```kotlin override fun onStartCommand(intent: Intent, flags: Int, startId: Int): Int { return super.onStartCommand(intent, flags, startId); } ``` 标准的TS环境中,只有`Number`类型而没有`Int`类型 为了适应这种情况,UTS 允许开发者使用原生平台的数据类型Int,来满足原生API对数据类型的要求: ```ts override onStartCommand(intent:Intent ,flags:Int ,startId:Int):Int { return super.onStartCommand(intent, flags, startId); } ``` #### 举例二:`MutableList` `MutableList`是`android`平台 特有的数据类型,一般场景下,可以使用UTS中内置类型 `Array` 替代 但是在 调用`onAppActivityRequestPermissionsResult` 函数监听权限申请结果时,明确要求使用此类型的参数 在原生环境中,应该这样写: ```kotlin onAppActivityRequestPermissionsResult(fun(requestCode: Number, permissions: MutableList, grantResults: MutableList){ }); ``` 标准的TS环境中,没有`MutableList`类型,与之相近的数据类型是 `Array` 为了适应这种情况,UTS 允许开发者使用原生平台的数据类型`MutableList`,来满足原生平台API对数据类型的要求: ```ts onAppActivityRequestPermissionsResult((requestCode: number,permissions: MutableList,grantResults: MutableList) => { }); ``` #### 举例三:`String[]` 部分三方sdk 使用java开发,要求继承/实现的方法参数为 string[]类型,这种情况比较特殊,需要将kotlin.Array先进行别名声明,再继续使用 ```ts import KotlinArray from 'kotlin.Array'; class XXX{ override onCaptureFinish(p0: KotlinArray){ // do sth }; } ``` ### 2.4 线程环境差异 @thread-environment UTS语言本身没有线程的概念。 但在具体的运行平台上会有线程环境差异: + uni-app 平台:默认代码执行在 `WeexJSBridgeThread` + uni-app x 平台:默认代码执行在 `main`线程 `Android`系统对线程操作存在较多的限制, UTS内置了[UTSAndroid.getDispatcher方法](https://doc.dcloud.net.cn/uni-app-x/uts/utsandroid.html#getdispatcher) 用来屏蔽大多数底层细节,一般来说开发者只需要关心两种特殊情况: 如果需要执行耗时任务: ```ts UTSAndroid.getDispatcher("io").async(function(_){ // 执行耗时任务 },null) ``` 如果需要操作UI: ```ts UTSAndroid.getDispatcher("main").async(function(_){ // 执行界面修改,包括view添加移除等 },null) ``` ## 3 Android原生环境配置 对于Android项目来说,除了源码之外,还会涉及依赖,资源,配置等常见问题 本章节将会介绍,UTS插件开发环境中如何配置这些属性 **注意**: + 1 本章节内的实例代码均取自Hello UTS [项目地址](https://gitcode.net/dcloud/hello-uts) + 2 本章节涉及的配置,均需自定义基座后才能生效 ### 3.1 配置AndroidManifest.xml 以hello UTS中的native-page插件中的配置文件为例: 文件位置: ~\uni_modules\uts-nativepage\utssdk\app-android\AndroidManifest.xml AndroidManifest.xml示例: ```xml // 配置权限 // 配置service / activity ``` UTS插件中的 `AndroidManifest.xml` 与 `android` 中的 `AndroidManifest.xml` 规则完全一致。 **特别提示**: 每一个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资源 ![](https://native-res.dcloud.net.cn/images/uts/forAndroid/uts_android_res_folder.jpg) 示例文件在hello uts中的位置: ~\uni_modules\uts-nativepage\utssdk\app-android\res 除了这里列出的layout、values目录外,还支持anim等所有android标准资源目录 **需要注意的是:如果res资源中使用了 android appcompat库内置的资源,需要在config.json中添加下面的配置:** ```json { "dependencies": [ "androidx.appcompat:appcompat:1.0.0" ] } ``` ### 3.3 配置asset资源 以hello UTS中的uts-advance插件为例。 ![目录结构](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中的位置: ~\uni_modules\uts-advance\utssdk\app-android\assets ### 3.4 增加libs依赖资源 #### 远程依赖 远端插件可以通过配置 `config.json`添加依赖 ,下面是一个`config.json`示例 ```json { "dependencies": [ "androidx.recyclerview:recyclerview:1.0.0" ] } ``` ------ 截止 HBuilder X 4.23 版本内置了以下依赖 开发者在使用列表中的依赖时,需要注意两点: + 真机运行时,不需要添加列表中的依赖,即可直接引用相关类 + 请勿通过 手动添加jar/aar 等方式引入相同的依赖,否则会因依赖冲突导致云打包失败。 ##### uni-app x ```gradle implementation 'androidx.core:core-ktx:1.10.1' implementation 'androidx.recyclerview:recyclerview:1.3.2' implementation 'androidx.appcompat:appcompat:1.0.0' implementation 'androidx.exifinterface:exifinterface:1.3.6' implementation 'androidx.localbroadcastmanager:localbroadcastmanager:1.0.0@aar' implementation 'androidx.constraintlayout:constraintlayout:2.1.4' implementation 'com.google.android.material:material:1.4.0' implementation 'androidx.viewpager2:viewpager2:1.1.0-beta02' implementation 'com.alibaba:fastjson:1.2.83' implementation 'com.facebook.fresco:fresco:3.1.3' implementation 'com.facebook.fresco:middleware:3.1.3' implementation 'com.facebook.fresco:animated-gif:3.1.3' implementation 'com.facebook.fresco:webpsupport:3.1.3' implementation 'com.facebook.fresco:animated-webp:3.1.3' implementation 'com.github.bumptech.glide:glide:4.9.0' implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-core:1.6.4' implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-android:1.6.4' implementation 'org.jetbrains.kotlin:kotlin-stdlib:1.8.10' implementation 'org.jetbrains.kotlin:kotlin-reflect:1.8.10' implementation 'org.jetbrains.kotlinx:kotlinx-serialization-json:1.4.1' implementation 'com.squareup.okhttp3:okhttp:3.12.12' implementation 'com.github.getActivity:XXPermissions:18.0' implementation 'androidx.recyclerview:recyclerview:1.0.0' ``` ##### uni-app ```gradle implementation 'com.github.bumptech.glide:glide:4.9.0' implementation 'androidx.localbroadcastmanager:localbroadcastmanager:1.0.0' implementation 'androidx.core:core:1.1.0' implementation 'androidx.fragment:fragment:1.1.0' implementation 'androidx.recyclerview:recyclerview:1.1.0' implementation 'androidx.appcompat:appcompat:1.1.0' implementation 'com.alibaba:fastjson:1.2.83' implementation 'androidx.webkit:webkit:1.3.0' implementation 'com.squareup.okhttp3:okhttp:3.12.12' implementation 'androidx.core:core-ktx:1.6.0' implementation 'org.jetbrains.kotlin:kotlin-stdlib:1.8.10' implementation 'org.jetbrains.kotlin:kotlin-reflect:1.6.0' implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-core:1.3.8' implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-android:1.3.8' implementation 'com.github.getActivity:XXPermissions:18.0' implementation 'com.facebook.fresco:fresco:2.5.0' implementation 'com.facebook.fresco:animated-gif:2.5.0' implementation 'com.facebook.fresco:webpsupport:2.5.0' implementation 'com.facebook.fresco:animated-webp:2.5.0' implementation 'androidx.recyclerview:recyclerview:1.0.0' implementation 'androidx.appcompat:appcompat:1.0.0' ``` 关于 `config.json` 的更多写法,可以参考[文档](https://nativesupport.dcloud.net.cn/NativePlugin/course/package.html#dependencies) #### 本地依赖 jar/aar文件: 参考 [hello uts](https://gitcode.net/dcloud/hello-uts/-/tree/master/uni_modules/uts-nativepage/utssdk/app-android/libs) 将jar/aar 添加到 `utssdk/app-android/libs` 目录下即可使用 so文件: 目前暂不支持so文件直接本地调试,所以在HBuilderX 4.26版本支持 [混编](https://doc.dcloud.net.cn/uni-app-x/plugin/uts-plugin-hybrid.html) 之前,推荐开发者将so 封装为AAR,或者分别集成 so和jar文件,自定义基座后再进行调试 HBuilderX 4.26版本之后,开发者可以使用混编kotlin代码的方式,直接集成so文件。参考[hello uts](https://gitcode.net/dcloud/hello-uts/-/tree/master/uni_modules/uts-nativepage/utssdk/app-android/libs) ### 3.5 其他配置文件 uni-app x / uni-app 均支持打包时手动指定资源位置 [说明文档](https://uniapp.dcloud.net.cn/tutorial/app-nativeresource-android.html#nativeresources) 例如 接入`Firebase` 时需要将`google-services.json`文件放在 `app` 目录下,则可以通过如下的配置来实现:
	
┌─pages                         //页面目录
│  └─[具体内容]                   
├─nativeResources               //配置文件目录
│  └─android
│  		└─google-services.json
└─App.vue 
	
具体的打包示例,参考 [Hello UTS](https://gitcode.net/dcloud/hello-uts) ### 3.6 远程依赖仓库说明 目前云打包机支持下面的仓库: ```gradle jcenter() google() // huawei maven {url 'https://developer.huawei.com/repo/'} // jitpack 远程仓库:https://jitpack.io maven { url 'https://jitpack.io' } ``` 部分场景下,开发者可能需要将本地依赖,上传到远程仓库,避免wgt提交资源过大超出打包限制。 这种情况,推荐开发者上传到 jitpack.io 这也是目前android 原生开发主流的远程仓库。 [使用文档](https://docs.jitpack.io/) ### 3.7 Android 编译SDK版本说明 截止 HBuilderX 4.15 版本: + uni-app x 项目: 本地Android sdk 版本为34 + uni-app 项目: 本地Android sdk 版本为31 开发者在使用系统api时,需要注意版本兼容性 ## 4 Android内置库@iodcloudutsandroid **在UTS语言中,所有的Android原生API都可以调用** 对于Android开发中高频使用的`application`/`activity`等系统能力、`uni-app`/`uni-app x` 运行时框架信息等,UTS通过内置对象`UTSAndroid` 进行了封装,以便开发者调用 下面列出了常见API的使用示例,完整的 `UTSAndroid` API文档参考:https://doc.dcloud.net.cn/uni-app-x/uts/utsandroid.html #### getAppContext ```ts import { UTSAndroid } from "io.dcloud.uts"; ``` 用法说明:获取当前应用Application上下文,对应android平台 Context.getApplicationContext 函数实现 Android开发场景中,调用应用级别的资源/能力,需要使用此上下文。更多用法,参考[Android官方文档](https://developer.android.google.cn/docs) ```ts // [示例]获取asset下的音频,并且播放 let assetManager = UTSAndroid.getAppContext()!.getAssets(); let afd = assetManager.openFd("free.mp3"); let mediaPlayer = new MediaPlayer(); mediaPlayer.setDataSource(afd.getFileDescriptor(),afd.getStartOffset(), afd.getLength()); mediaPlayer.prepare(); mediaPlayer.start(); ``` ** 与Application的转换 ** UTSAndroid.getAppContext() 默认返回的是 实现了 `Context`抽象类的`Application` 对象 部分场景,明确需要 `Application` 对象,那么直接强制类型转换即可 ```ts import Application from 'android.app.Application' let app = UTSAndroid.getAppContext() as Application console.log(app) ``` #### getUniActivity 获取当前插件所属的activity实例,对应android平台 getActivity 函数实现 Android开发场景中,调用活动的级别的资源/能力,需要使用此上下文。更多用法,参考[Android官方文档](https://developer.android.google.cn/docs) ```ts // [示例]获取当前activity顶层容器 let decorView = UTSAndroid.getUniActivity()!.window.decorView; let frameContent = decorView.findViewById(android.R.id.content) ``` #### onAppActivityDestroy 即使在android原生开发中,应用的生命周期管理也是十分重要的。 [android生命周期](https://developer.android.com/guide/components/activities/activity-lifecycle?hl=zh_cn) UTS环境中对原生的生命周期进行了封装和简化,大多数情况下,开发者只需要了解本章节中列出的 activity相关生命周期即可。 其中最为常见的场景,要数`onAppActivityDestroy`中释放系统资源: 举个例子,以Hello UTS [用户截屏插件](https://ext.dcloud.net.cn/plugin?id=9897)为例。 在注册监听回调时,添加了下列代码。 ```ts UTSAndroid.onAppActivityDestroy(function(){ screenOB?.stopWatching() screenOB = null }) ``` 这段代码的意思是当宿主activity被销毁时,主动回收屏幕监听的FileObserver 这是因为除了正常的用户注册/注册 之外,还存在一种情况:用户没有反注册,便关闭了应用。 此时FileObserver 并没有被反注册回收。就会导致应用关闭后继续持有上一个uni-app js引擎实例的引用,从而导致下一次启动时出现引擎回调找不到的情况。 开发者在开发UTS插件时,如果遇到了类似使用系统组件的情况,也需要特别关注资源释放情况。 #### requestSystemPermission HBuilder X 3.8.2版本之后支持 系统权限管理使用了 https://github.com/getActivity/XXPermissions 工具库 如果开发者使用了相同依赖,可能打包冲突。需要修改为 complileOnly 或者 修改为本章节内置API 请求系统权限,对应的两个参数: 1 请求的权限列表 2 请求结果回调 ```ts let permission = ["android.permission.ACCESS_FINE_LOCATION","android.permission.ACCESS_FINE_LOCATION"] UTSAndroid.requestSystemPermission(UTSAndroid.getUniActivity()!,permission,function(allRight:boolean,grantedList:string[]){ if(allRight){ // 用户同意了全部权限 }else{ // 用户仅同意了 grantedList中的权限 } },function(doNotAskAgain:boolean,grantedList:string[]){ // 用户拒绝了部分权限,仅允许了grantedList中的权限 if(doNotAskAgain){ // 用户拒绝了权限,并且选择不再询问 } }) ``` -------------------------------- 特别说明: 除了本章节列出的函数外,android环境下 application 其他上下文方法都可以通过 getAppContext()!.xxx()的方式实现 比如获取app缓存目录: ```ts UTSAndroid.getAppContext()!.getExternalCacheDir()!.getPath() ``` activity 其他上下文方法都可以通过 getUniActivity()!.xxx()的方式实现 比如获取当前activity的顶层View容器 ```ts UTSAndroid.getUniActivity()!.getWindow().getDecorView(); ``` ## 5 Kotlin与UTS差异重点介绍 (持续更新) 通过上面的章节的阅读,至此我们认为你已经掌握了UTS语法,掌握了基本的Kotlin语法,掌握了UTS对于android资源的支持。 但是对于一个熟悉android开发的kotlin语言者来说,有很多常用的习惯发生了改变,我们会在这个章节特别指出,便于开发者加深认识。 ### 语法差异 ------------------------------- #### let和var `kotlin`中 可变变量修饰为 `var`、`val`。 区别在于 val 不可变,var可变。 `uts`中对应`var`的变量类型为 `var/let` 推荐使用`let` 因为只会在作用域内生效,需要慎用`var`,因为它具备有更大的作用范围 #### 方法定义 方法定义 `kotlin`里的方法只有一种定义方式 ```kotlin fun startListener():void{ } ``` uts中,需要区分全局方法、成员方法 ```ts // 成员方法 startListener():void{ } ``` ```ts // 全局方法 function startListener():void{ } ``` #### extends `kotlin`中的: 继承操作符,需要用`extends`取代 |语法|kotlin|uts| |---|-------|---| |继承类|:|extends| |实现type接口|:|extends| |实现接口|:|implements| ```ts // 使用UTS 实现 OnClickListener接口 class StartServiceListener extends OnClickListener{ override onClick(v?: View):void{ // 执行点击逻辑 } } ``` #### 非空断言 kotlin中的非空断言是`!!`,ts中是一个`!` ```ts user!.sayHello(); ``` ```kotlin user!!.sayHello(); ``` #### 快速调用父类实现 ```kotlin //kotlin 中快速实现super constructor() : super() { } ``` ```ts //uts 中快速实现super constructor (){ super(); } ``` #### 匿名内部类 `kotlin`中可以使用匿名内部类 ```kotlin // kotlin 新建事件监听 user.setListener(Listener(){ //todo }); ``` 在UTS中这样使用: ```ts const myListener = new (class implements Listener { //todo }) user.setListener(myListener); ``` #### 可为空函数调用 有一种特殊场景,我们需要定义一些可为空的函数变量,比如下面的 success,fail: ```ts type Option = { success?: (res: object) => void; fail?: (res: object) => void; }; ``` 这个时候我们需要这样调用 ```ts options.success?.(res) ``` 这样的调用方式在kotlin中是非法的,属于TS中的特有语法,需要特别注意。 #### 一个类只能有一个构造函数 在`Kotlin`/`java`中允许一个函数有多个构造器,但是UTS中是不被允许的 #### 界面跳转写法 android开发中场景的 intent跳转需要传入 目标界面的class对象,目前UTS中仅支持一种写法 ```ts let intent = new Intent(getUniActivity(),DemoActivity().javaClass); getUniActivity()!.startActivity(intent); ``` #### 指定double数据类型 某些场景下开发者需要获得 指定double数据类型的数据 开发者下意识的写法可能是: ```ts // 这样是错误的 let a:Int =3 let b:Int =4 let c:Double = a/b ``` 但是Android原生环境中,数据类型的精度是向下兼容的,如果想要获得一个double类型,必须要有一个double类型参与运算: ```ts // 这样才是正确的 let a:Int =3 let b:Int =4 let c:Double = a * 1.0 / b ``` --------------------------------- ### 警告优化 下面的内容不会影响功能使用,但是在UTS环境中,有合适的解决办法 #### java lang包的引入问题 `kotlin` 或者`java` 中java.lang.*是被特殊处理的,可以直接使用而不需要引入。 ```kotlin // 获取当前时间戳 System.currentTimeMillis() ``` UTS环境中,lang包没有被特殊对待,需要手动引入。 ```ts // 手动引入lang包下的类 import System from 'java.lang.System'; // 获取当前时间戳 System.currentTimeMillis() ``` #### `UTS` 不建议使用 快捷构造 `kotlin` 中 支持通过()的方式,快速实现无参构造器的声明 ```kotlin // 获取当前时间戳 class ScreenReceiver extends BroadcastReceiver(){ } ``` UTS环境中,不建议这样做(虽然目前这样做不会影响编译),建议使用手动声明无参构造 ```ts class ScreenReceiver extends BroadcastReceiver{ constructor (){ super(); } } ``` ## 6 常见问题(持续更新) ### 6.1 如何在UTS环境中,新建一个`activity`? 参考Hello UTS项目中的uts-nativepage插件 ### 6.2 如何在UTS环境中,新建一个`service`? 参考Hello UTS项目中的uts-nativepage插件 ### 6.3 如何在UTS环境中,新建一个`Thread`? 简单示例 ```ts class CustomThread extends Thread{ constructor(){ super(); } override run(){ Thread.sleep(1000) console.log("CustomThread = " + Thread.currentThread().getName()) } } ``` 完整示例参考Hello UTS项目中的uts-nativepage插件 如果只是想要简单的开启一个异步任务,建议使用: ```ts UTSAndroid.getDispatcher("io").async(function(_){ }) ``` [详细用法](https://doc.dcloud.net.cn/uni-app-x/uts/utsandroid.html#getdispatcher) ### 如何生成byte[]对象 在java平台中,二进制操作一般采用字节数组实现。 UTS在android平台编译后的语言为Kotlin,对应的语法对象是ByteArray. 使用这个类不需要额外引入包,直接运行即可 下面是一个简单的示例 ```ts let byteTest = new ByteArray(5) console.log(byteTest) ``` ### 编译报错:unresolved reference R (R资源无法识别) UTS插件支持使用android的原生资源,比如动画,布局,字符串等。 [详细说明](https://uniapp.dcloud.net.cn/plugin/uts-for-android.html#_3-1-%E9%85%8D%E7%BD%AEandroidmanifest-xml) 如果提示 R资源无法找到:unresolved reference R 1 需要排查资源是否符合android原生格式 2 检查R资源引入的包名是否正确,参考hello uts nativepage插件 ```ts import R from 'io.dcloud.uni_modules.uts_nativepage.R'; ``` ### 6.4 如何实现一个接口 以HelloUTS nativepage插件 部分代码为例: ```ts import OnClickListener from 'android.view.View.OnClickListener'; // 实现 OnClickListener 接口 class User { name:string = "name" } class StartBroadcastListener extends User implements OnClickListener{ override onClick(v?: View):void{ let myReceiver = new ScreenReceiver(); let filter = new IntentFilter(); filter.addAction(Intent.ACTION_SCREEN_OFF); filter.addAction(Intent.ACTION_SCREEN_ON); UTSAndroid.getUniActivity()!.registerReceiver(myReceiver, filter); // 提示屏幕状态监听已经注册 Toast.makeText(UTSAndroid.getAppContext(),"屏幕状态监听已注册,注意观察控制台日志",Toast.LENGTH_LONG).show(); } } // 使用 let btn_start_screen_listen = this.findViewById