HBuilderX 3.6+ 支持uts插件

HBuilderX 3.6+ 支持uts插件
#1 uts插件介绍
#什么是uts
uts，全称 uni type script，是一门跨平台的、高性能的、强类型的现代编程语言。
它可以被编译为不同平台的编程语言，如：
web平台，编译为JavaScript
Android平台，编译为Kotlin
iOS平台，编译Swift（暂未发布）
uts 采用了与 ts 基本一致的语法规范，支持绝大部分 ES6 API。
如需详细了解uts语法，另见uts语法介绍
#什么是uts插件
现有的uni-app，仍以js引擎为主。但从HBuilderX 3.6.0开始，uni-app支持uts插件（暂时仅支持vue3编译器，后续补充vue2）。
也就是uts的第一步不是完整开发一个独立的app，而是作为uni-app的插件。后续uts会持续迭代，达到完整开发app的水平。
uts插件编译到app平台时，在功能上相当于uni-app之前的app原生插件，也就是kotlin和swift开发的插件。
开发uts插件不需要熟悉kotlin和swift的语法，因为使用的是基于ts的语法。但需要熟悉Android和iOS的系统API，否则无法调用原生能力。

#uts插件与uni原生语言插件的区别
在HBuilderX 3.6以前，uni-app在App侧只有一种原生插件，即用java或object-c开发的插件。
在uts推出后，原来的“App原生插件”，更名为“App原生语言插件”。
不同的名字，代表它们需要开发者编写语言不同。但殊途同归，最后都编译为原生的二进制代码。

• 原生语言插件 uts插件
  开发语言 java/oc uts
  开发环境 Android Studio/XCode HBuilderX
  打包方式 外挂aar 等产出物 编译时生成原生代码
  js层调用方式 uni.requireNativePlugin() 普通的js函数/对象，可以直接import
  相当于原生语言插件，uts插件的优势：
  统一了编程语言（uts），一种语言开发所有平台，真正大前端。
  统一了开发工具（HBuilderX），免除搭建复杂的原生开发环境。
  插件封装中要理解的概念更少。 传统原生语言插件需要在js和原生层处理通信，使用各种特殊转换，使用特殊语法导入，注意事项很多。uts统一为纯前端概念，简单清晰。
  uts下前端和原生可以统一在HBuilderX中联调。而传统原生语言插件需要在多个开发工具间切换，联调复杂。
  但当前的uts插件的完善度还没有达到原生语言插件的水平，虽然会陆续升级解决，但明示如下：
  uts插件只支持vue3编译器，还不支持vue2
  uts插件还不支持iOS
  uts插件无法封装nvue页面组件
  uts插件还无法在插件市场计费销售
  #uts插件和Native.js的区别
  Native.js运行在js上，通过反射调用os api。功能和性能都不及真正的原生
  uts在app上不运行在js引擎里，是真正的原生。
  #2 创建uts插件
  #uts插件目录结构
  在uni-app的项目工程下，提供了独立的目录utssdk，来存放uts插件。
  当然官方更推荐使用uni_modules方式，这是更好的包管理方案。
  首先确保项目根目录存在uni_modules文件夹，如果不存在，需要手动创建一个。

#新建步骤拆解
右键点击uni_modules目录 -> 新建插件

选择类型 uts原生插件

为了避免和插件市场的其他插件冲突，建议起一个自己的插件前缀名称。
uts插件目录结构

#package.json
package.json为uni_modules插件配置清单文件，负责描述插件的基本配置。
{
“id”: “uts-helloworld”,
“displayName”: “uts插件示例”,
“version”: “0.1”,
“description”: “uts插件示例”,
“uni_modules”: {

}}
复制代码
上面是一个默认的清单文件示例,关于package.json更多描述详见
#插件的目录结构

┌─common // 可跨端公用的uts代码。推荐，不强制
├─static // 静态资源
├─utssdk
│ ├─app-android //Android平台目录
│ │ ├─assets //Android原生assets资源目录，可选
│ │ ├─libs //Android原生库目录，可选
│ │ ├─res //Android原生res资源目录，可选
│ │ ├─AndroidManifest.xml //Android原生应用清单文件，可选
│ │ ├─config.json //Android原生配置文件
│ │ └─index.uts
│ ├─app-ios //ios平台目录
│ │ ├─config.json //ios原生配置文件
│ │ └─index.uts
│ ├─web //web平台目录
│ │ └─index.uts
│ └─mp-xxx // 其他平台目录
├─package.json // 插件清单文件
├─index.d.ts // 插件能力声明，可选
└─index.uts // 插件能力实现
index.uts文件是程序主入口。如果插件根目录下没有index.uts，则会在编译到不同平台时，寻找分平台的目录下的index.uts文件。
比如编译到app-android平台时，如果uts插件根目录没有index.uts，会寻找utssdk/app-android/index.uts。如果也没有找到，会报错。
当同时存在分平台目录的index.uts和根目录index.uts时，会优先获取具体的分平台目录。
开发者有多种组织自己代码的方式：
在插件根目录的index.uts中写条件编译代码。简单的业务一个文件搞定
在插件根目录index.uts中写条件编译，import分平台的文件
不写根目录的index.uts，直接在分平台目录写index.uts。不跨端时，比如只做一个Android插件，这样写比较简单
index.d.ts文件是对当前插件能力的声明，用于语法提示。它不是必写项。
因为uts写好后，HBuilderX可以自动识别uts api并进行语法提示。它更多的用于后续uts插件加密时给予语法提示。
如果不熟悉d.ts，可以自行网上搜索，它属于ts标准技术。
#App原生配置
#Android平台原生配置
app-android 文件夹下存在Android平台原生配置，包括以下目录或文件
目录名/文件名 用途
assets Android平台原生assets资源目录
libs Android平台原生引用的三方jar/aar目录
res Android平台原生res资源目录
AndroidManifest.xml Android平台原生应用清单文件
config.json Android平台下的配置文件
index.uts 主入口，index.d.ts声明的能力在Android平台下的实现
#assets
Android平台原生assets资源目录，建议只保存UTS插件内置的资源文件。
除了插件下有assets目录，项目下也有。注意2者的区别。 如果需要插件使用者配置（如三方SDK的授权文件），则插件作者应该在插件文档中告诉插件使用者，配置到项目的Android原生应用资源目录，而不是配置在插件目录下。详见(opens new window)
#libs
Android平台原生三方库目录，支持以下类型文件：
jar
aar
如果使用了NDK开发so库，也支持保存到此目录，需按Android的abi类型分目录保存。
如果封装三方原生sdk为uni-app插件，可以将sdk的jar/aar文件放到此目录，但不推荐这么做，如果三方原生sdk支持仓储建议优先使用仓储，参考config.json的dependencies。
关于libs目录的使用，可以参考 Hello UTS(opens new window)
遗留事项: HBuilderX3.6.2版本对libs目录使用还不完善，详见
#res
Android平台原生res资源目录，建议只保存UTS插件内置的资源文件。
除了插件下有res目录，项目下也有。注意2者的区别。一般使用者的配置不放在插件下，而放在自己的项目下。项目下配置详见(opens new window)
注意：截止到HBuilderX3.6.2，uts插件无法使用res。图片资源建议放在assets目录。
#AndroidManifest.xml
Android原生应用清单文件，建议只保存UTS插件内置的清单文件配置。
除了插件下有AndroidManifest.xml，项目下也有。注意2者的区别。一般使用者的配置不放在插件下，而放在自己的项目下。项目下配置详见(opens new window)
#config.json
uts插件在Android平台的原生层配置文件，可以在其中配置依赖仓储等gradle相关内容。
{
// 使用NDK时支持的CPU类型，可选
“abis”: [
“使用NDK时支持的cpu类型, 可取值armeabi-v7a|arm64-v8a|x86|x86_64”
],
// 依赖的仓储配置，可选，打包时会合并到原生工程的build.gradle中
“dependencies”: [
“androidx.core:core-ktx:1.6.0”,
{
“id”: “com.xxx.richtext:richtext”,
“source”: “implementation ‘com.xxx.richtext:richtext:3.0.7’”
}
],
// Android系统版本要求，最低Android 5.0
“minSdkVersion”: 21}
复制代码
abis
当插件使用了NDK开发的so库时配置，描述插件支持CPU类型。
可取值：armeabi-v7a、arm64-v8a、x86、x86_64
dependencies
配置插件依赖的仓储，云端打包时会合并到Android原生工程的build.gradle的
数组类型，数组中的项可以是字符串类型或JSON对象
对于字符串类型项，将会作为implementation方式依赖添加到build.gradle中，上面示例中"androidx.core:core-ktx:1.6.0"将会添加以下配置
dependencies {
implementation ‘androidx.core:core-ktx:1.6.0’
}
复制代码
对于JSON类型项，将会把source字段值作为gradle源码添加到build.gradle中，上面示例中"id": "com.xxx.richtext:richtext"项将会添加以下配置
dependencies {
implementation ‘com.xxx.richtext:richtext:3.0.7’
}
复制代码
遗留事项: HBuilderX3.6.1版本对dependencies配置支持还不完善，详见
minSdkVersion
插件支持的Android最低版本，整数类型，取值范围为Android API Level
默认uni-app最低支持版本为19，即Android4.3.3
注意：
Android平台原生配置需提交云端打包才能生效，真机运行时需使用自定义基座(opens new window)
#HX3.6.2 临时注意事项
使用HBuilderX 3.6.2版本及更早版本，关于原生依赖的处理有部分不完善，需要注意以下事项：

config.json 目前还不支持配置仓库依赖，需要将gradle配置的库手动下载后，放置在libs目录，使用手动添加的方式集成

uni-app引擎内置了部分依赖库（比如androidX，清单详见下方），如你的插件需使用相同依赖，请注意：

确保与内置的依赖版本一致。

真机运行时，需将依赖库copy到libs目录下。但注意，打包自定义基座时需先从libs中暂时移除，避免打包类重复报错。生成自定义基座之后再将这些内置依赖库移回libs目录下，否则无法真机运行。

内置依赖清单(opens new window)
这些遗留事项会尽快升级完善。
#3 开发uts原生插件
以Android平台获取电量为例，介绍uts原生插件开发步骤

在Android平台目录下，编辑index.uts，键入以下内容。
// index.uts
// 引用android apiimport Context from “android.content.Context”;import BatteryManager from “android.os.BatteryManager”;// 引用uts环境库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%”;}

复制代码
io.dcloud.uts.android库介绍文档见下
至此，我们已经完成一个Android平台上获取电量的原生能力封装。
在下一节，将介绍前端如何使用这个插件。
注：HBuilderX的代码提示系统，支持在uts文件中对Android的原生API进行提示。
#4 前端使用插件
虽然uts插件由uts语法开发，但前端引用插件并不要求一定需要ts，普通js即可引用uts插件。
下面介绍两种常见的引入方式
泛型引用
作为一个对象全部import进来，然后通过点运算符调用这个对象的方法或属性。
// 先引用，全部导入，对象起名为UTSHelloimport * as UTSHello from “…/…/…/uni_modules/uts-osapi”;
// 然后使用UTSHello的方法
UTSHello.getBatteryCapacity()
复制代码
显性引用
从可导出的选项里import 1个或多个（逗号分隔），然后直接使用导出的方法或属性。
//先引用，导入指定方法或属性import {
getBatteryCapacity} from “…/…/…/uni_modules/uts-osapi”;
// 然后使用导入的方法getBatteryCapacity()
复制代码
关于电量这个插件，插件市场已经提供好了现成的插件，除了Android，还同时支持了web和小程序，可以去下载体验。详见(opens new window)
更多开发示例，可以参考 HelloUTS (opens new window)。
#5 真机运行
#5.1 UTS支持真机运行
uts虽然是原生代码，但同样具有真机运行功能
若HBuilderX中没有uts编译运行插件，在第一次运行时会自动下载。
在Android上，运行体验与uni-app基本无差异。一样可以热刷新，打印console.log。
#5.2 自定义基座
自定义基座也支持uts插件。
与原生插件一样,涉及以下场景,需要自定义基座后方能生效:
1 集成三方sdk
2 新增资源(包括res/asset 等)
总结来说，就是所有 涉及新增依赖/gralde配置/androidManifest.xml/资源 等标准基座不具备的能力时，需要自定义基座
#5.3 遗留问题
截止到HBuilderX 3.6.2 时遗留事项：
不能debug断点uts源码
iOS版还未发布
uts插件还不支持远程仓库依赖，目前添加插件的配置方法参考 这个章节
uts插件无法使用res。图片资源建议放在assets目录。
遗留事项后续升级完善。
#6 云端打包
正常支持云端打包。
注意：虽然uts在真机运行时支持热刷，但打包后uts编译为了纯原生二进制代码，不支持wgt热更新。
打包若包含了已经内置的依赖库，则需注意参考 这个章节
#uni-app的Android内置库
在uts里，Android的所有api都可以访问。同时DCloud提供了io.dcloud.uts.android库，处理在uni-app下的特殊情况。
import { getAppContext } from “io.dcloud.uts.android”;
复制代码
#getAppContext
获取当前应用Application上下文，对应android平台 Context.getApplicationContext 函数实现
Android开发场景中，调用应用级别的资源/能力，需要使用此上下文。更多用法，参考Android官方文档(opens new window)
// [示例]获取asset下的音频，并且播放let assetManager = getAppContext()!.getAssets();let afd = assetManager.openFd(“free.mp3”);let mediaPlayer = new MediaPlayer();
mediaPlayer.setDataSource(afd.getFileDescriptor(),afd.getStartOffset(), afd.getLength());
mediaPlayer.prepare();
mediaPlayer.start();
复制代码
#getUniActivity
获取当前插件所属的activity实例，对应android平台 getActivity 函数实现
Android开发场景中，调用活动的级别的资源/能力，需要使用此上下文。更多用法，参考Android官方文档(opens new window)
// [示例]获取当前activity顶层容器let frameContent = decorView.findViewById(android.R.id.content)
复制代码
#getResourcePath(resourceName:String)
获取指定插件资源的运行期绝对路径
// [示例]获取指定资源路径// 得到文件运行时路径: /storage/emulated/0/Android/data/io.dcloud.HBuilder/apps/__UNI__3732623/www/uni_modules/test-uts-static/static/logo.pnggetResourcePath(“uni_modules/test-uts-static/static/logo.png”)

复制代码
#onAppActivityPause
App的activity onPause时触发
onAppActivityPause(() => {
let eventName = "onAppActivityPause - " + Date.now();
console.log(eventName);});
复制代码
#onAppActivityResume
App的activity onResume时触发
onAppActivityResume(() => {
let eventName = "onAppActivityResume - " + Date.now();
console.log(eventName);});
复制代码
#onAppActivityDestroy
App 的 activity onDestroy时触发
onAppActivityDestroy(() => {
let eventName = "onAppActivityDestroy- " + Date.now();
console.log(eventName);});
复制代码
#onAppActivityBack
App 的 activity 回退物理按键点击时触发
onAppActivityBack(() => {
let eventName = "onAppActivityBack- " + Date.now();
console.log(eventName);});
复制代码
#onAppActivityRequestPermissionsResult
App 的 activity 获得权限请求结果的回调
onAppActivityRequestPermissionsResult((requestCode: number,
permissions: MutableList,
grantResults: MutableList) => {
/**
* 0 已同意
* -1 已拒绝
*/
console.log(grantResults);
console.log(permissions);
console.log(requestCode);
});
//发起定位权限申请
ActivityCompat.requestPermissions(getUniActivity()!,
arrayOf(Manifest.permission.ACCESS_COARSE_LOCATION), 1001);

复制代码
#常见问题
#常见报错

[plugin:vite:resolve] Failed toresolve entry for package “插件路径” HBuilderX 的最低要求为3.6.0，低于此版本无法import uts插件，编译时将报错。

文件查找失败：‘uts插件路径’ 目前暂未支持 vue2，vue2 的uni-app项目无法import uts插件，编译时将报错。

#Float类型传参
android很多布局参数强制要求Float，但是ts中没有内置这种类型。可以使用下面的代码实现转换
let textSize = 30.0.toFloat();
复制代码
#匿名内部类
UTS目前还不支持匿名内部类的写法，在android中类似这样的场景
getUniActivity()!!.runOnUiThread(Runnable(){
// do something});
复制代码
需要声明一个实现类，再新建实例的方式实现，代码如下
class AddUIRunnable extends Runnable {
override run():void {
// do something
}
};
let uiRunable = new AddUIRunnable();
getUniActivity()!.runOnUiThread(uiRunable)
复制代码
#泛型参数
android中UI相关的api，很多会要求泛型，目前uts中可以使用下面的代码实现
let frameContent = decorView.findViewById(android.R.id.content)let layoutParam = new FrameLayout.LayoutParams(ViewGroup.LayoutParams.MATCH_PARENT,ViewGroup.LayoutParams.WRAP_CONTENT);
复制代码
#路线图
uts是一个宏大工程，产品将分阶段发布。近期将陆续发布：
iOS相关功能
支持vue2编译器
debug
UI操作能力
插件市场支持uts插件的加密和计费销售
最终，uts不再是uni-app的插件，而是应用的主体。（现在是以js为主，uts作为插件存在，主引擎仍然在v8或jscore里）
那时，即便是最复杂的应用，比如微信，也可以使用uts来开发，毫无功能和性能的影响。
#示例项目