UTSAndroid

app-android平台专有内置对象。在uni-app和uni-app x的uts环境中均可使用。

静态方法

onAppConfigChange

监听 App配置发生变化, 对应 android原生 onAppConfigChange

参数

名称	类型	必填	描述
callback	(res:UTSJSONObject)=>void	是	-

返回值

类型
void

兼容性

Android uni-app x	iOS uni-app x	web uni-app x	Android uni-app	iOS uni-app	web uni-app
3.9	x	-	√	x	-

offAppConfigChange

onAppConfigChange 对应的反注册函数

参数

名称	类型	必填	描述
callback	(res:UTSJSONObject)=>void	否	-

返回值

类型
void

兼容性

Android uni-app x	iOS uni-app x	web uni-app x	Android uni-app	iOS uni-app	web uni-app
3.9	x	-	√	x	-

onAppTrimMemory

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

参数

名称	类型	必填	描述
callback	(res:Number)=>void	否	-

返回值

类型
void

兼容性

Android uni-app x	iOS uni-app x	web uni-app x	Android uni-app	iOS uni-app	web uni-app
3.9	x	-	√	x	-

offAppTrimMemory

onAppTrimMemory 对应的反注册函数。

参数

名称	类型	必填	描述
callback	(res:Number)=>void	否	-

返回值

类型
void

兼容性

Android uni-app x	iOS uni-app x	web uni-app x	Android uni-app	iOS uni-app	web uni-app
3.9	x	-	√	x	-

onAppActivityPause

注册监听 activity onPause事件

参数

名称	类型	必填	描述
callback	()=>void	是	-

返回值

类型
void

兼容性

Android uni-app x	iOS uni-app x	web uni-app x	Android uni-app	iOS uni-app	web uni-app
3.9	x	-	√	x	-

offAppActivityPause

onAppActivityPause 对应的反注册函数

参数

名称	类型	必填	描述
callback	()=>void	否	-

返回值

类型
void

兼容性

Android uni-app x	iOS uni-app x	web uni-app x	Android uni-app	iOS uni-app	web uni-app
3.9	x	-	√	x	-

onAppActivityResume

注册监听 activity onResume事件

参数

名称	类型	必填	描述
callback	()=>void	是	-

返回值

类型
void

兼容性

Android uni-app x	iOS uni-app x	web uni-app x	Android uni-app	iOS uni-app	web uni-app
3.9	x	-	√	x	-

offAppActivityResume

onAppActivityResume 对应的反注册函数

参数

名称	类型	必填	描述
callback	()=>void	否	-

返回值

类型
void

兼容性

Android uni-app x	iOS uni-app x	web uni-app x	Android uni-app	iOS uni-app	web uni-app
3.9	x	-	√	x	-

onAppActivityDestroy

注册监听 activity onDestroy事件

参数

名称	类型	必填	描述
callback	()=>void	是	-

返回值

类型
void

兼容性

Android uni-app x	iOS uni-app x	web uni-app x	Android uni-app	iOS uni-app	web uni-app
3.9	x	-	√	x	-

offAppActivityDestroy

onAppActivityDestroy 对应的反注册函数。

参数

名称	类型	必填	描述
callback	()=>void	否	-

返回值

类型
void

兼容性

Android uni-app x	iOS uni-app x	web uni-app x	Android uni-app	iOS uni-app	web uni-app
3.9	x	-	√	x	-

onAppActivityResult

注册监听 activity onAppActivityResult 函数

参数

名称	类型	必填	描述
callback	(requestCode: Int, resultCode: Int, data: Intent?)=>void	是	用于监听的响应函数

返回值

类型
void

兼容性

Android uni-app x	iOS uni-app x	web uni-app x	Android uni-app	iOS uni-app	web uni-app
3.9	x	-	√	x	-

offAppActivityResult

onAppActivityResult 对应的反注册函数。

参数

名称	类型	必填	描述
callback	(requestCode: Int, resultCode: Int, data: Intent?)=>void	否	-

返回值

类型
void

兼容性

Android uni-app x	iOS uni-app x	web uni-app x	Android uni-app	iOS uni-app	web uni-app
3.9	x	-	√	x	-

onAppActivityBack

注册监听 activity onAppActivityBack 函数

参数

名称	类型	必填	描述
callback	()=>void	是	用于监听的响应函数

返回值

类型
void

兼容性

Android uni-app x	iOS uni-app x	web uni-app x	Android uni-app	iOS uni-app	web uni-app
3.9	x	-	√	x	-

offAppActivityBack

取消注册监听 activity onAppActivityBack 函数

参数

名称	类型	必填	描述
callback	()=>void	否	-

返回值

类型
void

兼容性

Android uni-app x	iOS uni-app x	web uni-app x	Android uni-app	iOS uni-app	web uni-app
3.9	x	-	√	x	-

getAppContext()

获取当前应用Application上下文，对应android平台 Context.getApplicationContext 函数实现

返回值

类型	描述
Context | null	当前应用程序 上下文实例对象

兼容性

Android uni-app x	iOS uni-app x	web uni-app x	Android uni-app	iOS uni-app	web uni-app
3.9	x	-	√	x	-

let packageName = UTSAndroid.getAppContext()?.packageName
console.log("packageName",packageName)

getUniActivity()

获取当前应用 栈顶的 Activity实例，对应android平台 getActivity 函数实现

返回值

类型	描述
Activity | null	当前应用栈顶的 Activity实例

兼容性

Android uni-app x	iOS uni-app x	web uni-app x	Android uni-app	iOS uni-app	web uni-app
3.9	x	-	√	x	-

// 获取第一个可以响应图像采集行为组件
let takePictureIntent = new Intent(MediaStore.ACTION_IMAGE_CAPTURE);
if (takePictureIntent.resolveActivity(UTSAndroid.getUniActivity()!.getPackageManager()) != null) {
	UTSAndroid.getUniActivity()!.startActivityForResult(takePictureIntent, 1001);
}

getResourcePath(resourceName:string)

获取资源文件的原生路径。

参数

名称	类型	必填	描述
resourceName	string	是	资源文件相对于工程的绝对路径, 如：“/static/logo.png”

返回值

类型	描述
string	该资源在原生目录下的路径

兼容性

Android uni-app x	iOS uni-app x	web uni-app x	Android uni-app	iOS uni-app	web uni-app
3.9	x	-	√	√	-

注意事项

getResourcePath 与 convert2AbsFullPath 区别在于：

getResourcePath 屏蔽了读取代码包文件时 各平台/各模式下的底层细节，即使是存放在asset目录也会返回符合android 读取规范的协议地址

convert2AbsFullPath 没有实现这一点

当开发者需要读取代码包文件时，建议使用 getResourcePath

• 代码包文件
  • 代码包文件在真机运行和云打包模式下的释放策略不同：
    本地真机运行：会被存在放内置储存目录
    云打包： uni-app x项目会被存放在asset目录, uni-app 项目默认会被存放在内置储存目录
    因此 uni-app/uni-app x 平台对 代码包文件 均仅支持读取操作
• 本地磁盘文件
  • 沙盒文件
    • 不支持
  • 沙盒外文件
    • 不支持

// 代码包文件
console.log(UTSAndroid.getResourcePath('static/logo.png'))
// 沙盒文件
console.log(UTSAndroid.getResourcePath('unifile://sandbox/static/logo.png'))
// 沙盒外文件
console.log(UTSAndroid.getResourcePath('/storage/emulated/0/Android/data/io.dcloud.HBuilder/apps/HBuilder/www/static/logo.png'))

exit()

退出当前应用

返回值

类型
void

兼容性

Android uni-app x	iOS uni-app x	web uni-app x	Android uni-app	iOS uni-app	web uni-app
3.9	x	-	√	x	-

// 退出当前应用
UTSAndroid.exit()

getDispatcher

获取一个任务分发器实例

参数

名称	类型	必填	描述
threadName	string|null	是	任务组名称，可能为： main: ui thread / dom: 仅uni-app x环境生效，uni-app 环境会自动切换到 ui io : io thread 匿名线程 null 或者 '': 来源线程，如果来源线程不支持任务分发，则会在当前线程执行执行. 这个场景下要求第一个参数必须是线程环境

返回值

类型
UTSTaskDispatcher

UTSTaskDispatcher 的方法

async(action, param?)

在当前任务分发器 异步执行任务

参数

名称	类型	必填	默认值	描述
action	(action?: any | null) => void	是	-	任务函数
param	any | null	否	-	任务函数需要的参数

兼容性

Android uni-app x	iOS uni-app x	web uni-app x	Android uni-app	iOS uni-app	web uni-app
3.9	x	-	√	x	-

// 不传任何参数，得到是当前代码运行线程
let currentDispatcher = UTSAndroid.getDispatcher()
console.log("currentDispatcher",currentDispatcher)
// 期望在 io 任务队列执行
UTSAndroid.getDispatcher("io").async(function(_){
    console.log("当前任务执行在",Thread.currentThread().getName())
    // 期望在 主线程 任务队列执行
    UTSAndroid.getDispatcher("main").async(function(_){
        console.log("当前任务执行在",Thread.currentThread().getName())
        currentDispatcher.async(function(_){
            console.log("起始任务执行在",Thread.currentThread().getName())
        },null)
    },null)
},null)

getAppId()

获取当前运行的app的AppId。

返回值

类型	描述
string	当前运行的app的AppId。

兼容性

Android uni-app x	iOS uni-app x	web uni-app x	Android uni-app	iOS uni-app	web uni-app
3.9	x	-	√	x	-

let appid = UTSAndroid.getAppId()
console.log("appid",appid)

getOsTheme()

获取当前系统主题样式

返回值

类型	描述
string	系统主题样式 "dark":暗色模式 "light":亮色模式

兼容性

Android uni-app x	iOS uni-app x	web uni-app x	Android uni-app	iOS uni-app	web uni-app
3.9	x	-	√	x	-

let theme = UTSAndroid.getOsTheme()
console.log("OsTheme",theme)

isUniMp()

获取当前运行环境是否是unimp。

返回值

类型	描述
boolean	是否是unimp。

兼容性

Android uni-app x	iOS uni-app x	web uni-app x	Android uni-app	iOS uni-app	web uni-app
3.9	x	-	√	x	-

let isUniMp = UTSAndroid.isUniMp()
console.log("isUniMp",isUniMp)

getAppName()

获取manifest.json 中配置的应用名称

返回值

类型	描述
string	应用名称。

兼容性

Android uni-app x	iOS uni-app x	web uni-app x	Android uni-app	iOS uni-app	web uni-app
3.9	x	-	√	x	-

let appName = UTSAndroid.getAppName()
console.log("AppName",appName)

getAppVersion()

获取manifest.json 中配置的应用版本信息

返回值

类型	描述
UTSJSONObject	应用版本信息

兼容性

Android uni-app x	iOS uni-app x	web uni-app x	Android uni-app	iOS uni-app	web uni-app
3.9	x	-	√	x	-

let appVersion = UTSAndroid.getAppVersion()
console.log("AppVersion",appVersion)

getInnerVersion()

获取引擎版本号。

返回值

类型	描述
string	引擎版本号。

兼容性

Android uni-app x	iOS uni-app x	web uni-app x	Android uni-app	iOS uni-app	web uni-app
3.9	x	-	√	x	-

let innerVersion = UTSAndroid.getInnerVersion()
console.log("InnerVersion",innerVersion)

isUniAppX()

获取当前是否是uniapp x 环境

返回值

类型	描述
boolean	uniapp x 环境 true, uniapp 环境： false。

兼容性

Android uni-app x	iOS uni-app x	web uni-app x	Android uni-app	iOS uni-app	web uni-app
3.9	x	-	√	x	-

let isUniAppX = UTSAndroid.isUniAppX()
console.log("isUniAppX",isUniAppX)

getAppCachePath()

获取app 临时目录。

返回值

类型	描述
string | null	返回app临时目录路径。存放在该文件可能会在应用退出后被清理

兼容性

Android uni-app x	iOS uni-app x	web uni-app x	Android uni-app	iOS uni-app	web uni-app
3.99	x	-	√	x	-

let appCachePath = UTSAndroid.getAppCachePath()
console.log("AppCachePath",appCachePath)

rpx2px(rpx:number) : number;

参数

名称	类型	必填	描述
rpx	number	是	-

返回值

类型	描述
number	返回对应的逻辑像素值

兼容性

Android uni-app x	iOS uni-app x	web uni-app x	Android uni-app	iOS uni-app	web uni-app
3.9	x	-	3.9+	x	-

推荐使用uni.rpx2px来替代本API，详见

devicePX2px(devicePX:number) : number;

物理像素转换为页面的px像素

参数

名称	类型	必填	描述
devicePX	number	是	待转换的物理像素

返回值

类型	描述
number	转换后的页面px

兼容性

Android uni-app x	iOS uni-app x	web uni-app x	Android uni-app	iOS uni-app	web uni-app
3.95	x	-	3.95	x	-

// 对 100物理像素长度 进行转换
let pagePX = UTSAndroid.devicePX2px(100)
// 在特定设备返回值:36.3636360168457
console.log("pagePX",pagePX)

isPrivacyAgree() : boolean;

当前应用是否已取得用户同意隐私协议

返回值

类型	描述
boolean	true 用户已同意 false 用户未同意

兼容性

Android uni-app x	iOS uni-app x	web uni-app x	Android uni-app	iOS uni-app	web uni-app
3.9	x	-	3.9+	x	-

// 手动标记用户已同意隐私协议
UTSAndroid.setPrivacyAgree(true)
// 此时为 true
console.log(UTSAndroid.isPrivacyAgree())
// 重置用户隐私协议状态
UTSAndroid.resetPrivacyAgree()
// 此时为 false
console.log(UTSAndroid.isPrivacyAgree())

setPrivacyAgree(state:boolean):void;

设置当前应用是否已取得用户同意隐私协议

参数

名称	类型	必填	描述
state	boolean	是	true 用户已同意 false 用户未同意

返回值

类型
void

兼容性

Android uni-app x	iOS uni-app x	web uni-app x	Android uni-app	iOS uni-app	web uni-app
3.9	x	-	3.9+	x	-

// 手动标记用户已同意隐私协议
UTSAndroid.setPrivacyAgree(true)
// 此时为 true
console.log(UTSAndroid.isPrivacyAgree())
// 重置用户隐私协议状态
UTSAndroid.resetPrivacyAgree()
// 此时为 false
console.log(UTSAndroid.isPrivacyAgree())

resetPrivacyAgree():void;

重置当前应用至用户未同意隐私协议

返回值

类型
void

兼容性

Android uni-app x	iOS uni-app x	web uni-app x	Android uni-app	iOS uni-app	web uni-app
3.9	x	-	3.9+	x	-

// 手动标记用户已同意隐私协议
UTSAndroid.setPrivacyAgree(true)
// 此时为 true
console.log(UTSAndroid.isPrivacyAgree())
// 重置用户隐私协议状态
UTSAndroid.resetPrivacyAgree()
// 此时为 false
console.log(UTSAndroid.isPrivacyAgree())

requestSystemPermission

请求系统权限

参数

名称	类型	必填	描述
context	Activity	是	-
requestPermission	Array<string>	是	期望请求的权限
success	(allRight:boolean, grantedList:Array<string>)=>void	是	-
fail	(doNotAskAgain:boolean, grantedList:Array<string>)=>void	是	-

返回值

类型
void

兼容性

Android uni-app x	iOS uni-app x	web uni-app x	Android uni-app	iOS uni-app	web uni-app
3.9	x	-	3.9+	x	-

	let permissionNeed = ["android.permission.CAMERA"]
    // 请求拍照权限
	UTSAndroid.requestSystemPermission(UTSAndroid.getUniActivity()!, permissionNeed, function (allRight : boolean, _ : string[]) {
		if (allRight) {
			// 权限请求成功
		} else {
			//用户拒绝了部分权限
		}
	}, function (_ : boolean, _ : string[]) {
		//用户拒绝了部分权限
	})

请求权限后有三种情况:

• 用户允许了全部权限请求，会通过 success回调通知调用者，并且此时allRight参数为 true

• 用户拒绝了全部权限请求，会通过 fail 回调通知调用者，doNotAskAgain 参数标识了用户拒绝时是否选择了不再询问

• 用户允许了部分请求，拒绝了部分权限请求,此时既会调用success也会调用fail。由其中的 string数组参数 标识具体被拒绝/允许的权限

checkSystemPermissionGranted

检查当前应用是否已经具备指定权限

参数

名称	类型	必填	描述
context	Activity	是	-
requestPermission	Array<string>	是	期望具备的权限

返回值

类型	描述
boolean	请求的权限列表中是否已经具备

兼容性

Android uni-app x	iOS uni-app x	web uni-app x	Android uni-app	iOS uni-app	web uni-app
3.9	x	-	3.9+	x	-

let permissionCheck = ["android.permission.CAMERA"]
// 请求拍照权限
if (UTSAndroid.checkSystemPermissionGranted(UTSAndroid.getUniActivity()!, permissionCheck)) {
	console.log("当前已具备指定权限")
}else{
	console.log("当前不具备指定权限")
}

gotoSystemPermissionActivity

跳转至系统权限手动设备列表

参数

名称	类型	必填	描述
context	Activity	是	-
requestPermission	Array<string>	是	期望请求的权限

返回值

类型
void

兼容性

Android uni-app x	iOS uni-app x	web uni-app x	Android uni-app	iOS uni-app	web uni-app
3.9	x	-	3.9+	x	-

// 前往系统权限设置界面
let permissionNeed = ["android.permission.READ_PHONE_STATE"]
UTSAndroid.gotoSystemPermissionActivity(UTSAndroid.getUniActivity()!,permissionNeed)

getSystemPermissionDenied

获取当前应用不具备的权限列表

参数

名称	类型	必填	描述
context	Activity	是	-
requestPermission	Array<string>	是	期望请求的权限

返回值

类型	描述
Array<string>	请求的权限列表中已经被禁用的部分

兼容性

Android uni-app x	iOS uni-app x	web uni-app x	Android uni-app	iOS uni-app	web uni-app
3.9	x	-	3.9+	x	-

	let permissionNeed = ["android.permission.READ_PHONE_STATE"]
	if (UTSAndroid.getSystemPermissionDenied(UTSAndroid.getUniActivity()!, permissionNeed).isEmpty()) {
    	console.log("当前已具备指定权限")
	}

convert2AbsFullPath(path:string)

将文件的项目相对地址转换为 运行期对应的绝对地址 eg. 'static/logo.png' -> '/storage/sdcard/0/apps/com.xxxx/files/logo.png'

参数

名称	类型	必填	描述
inputPath	string	是	待转换的文件相对路径

返回值

类型	描述
string	转换后文件绝对路径

兼容性

Android uni-app x	iOS uni-app x	web uni-app x	Android uni-app	iOS uni-app	web uni-app
3.9	x	-	3.9	x	-

注意事项

convert2AbsFullPath 与 getResourcePath 区别在于：

convert2AbsFullPath 对文件路径支持范围更大，不仅支持 代码包文件内置储存目录的情况，还支持相对路径，沙盒路径，沙盒外路径（包括系统API返回的文件地址） 等形式。

getResourcePath 不支持这些

当开发者明确需要操作文件，而非代码包资源时，建议使用 convert2AbsFullPath

• 代码包文件
  • 代码包文件在真机运行和云打包模式下的释放策略不同：
    本地真机运行：会被存在放内置储存目录
    云打包： uni-app x项目会被存放在asset目录, uni-app 项目会被存放在内置储存目录
    因此在 uni-app/uni-app x 平台对 代码包文件 均仅支持读取操作
• 本地磁盘文件
  • 沙盒文件
    • uni-app x支持读写
    • uni-app不支持
  • 沙盒外文件
    • 沙盒管理范围外的其他文件。 调用系统API返回的绝对地址属于此类。uni-app/uni-app x平台 均支持读写

// 代码包文件
console.log(UTSAndroid.convert2AbsFullPath('static/logo.png'))
// 沙盒文件
console.log(UTSAndroid.convert2AbsFullPath('unifile://sandbox/static/logo.png'))
// 沙盒外文件 包含相对路径
console.log(UTSAndroid.convert2AbsFullPath('../../../io.dcloud.HBuilder/apps/HBuilder/www/static/logo.png'))

getFileProviderUri(file:File)

将应用的私有文件 通过内置的FileProvider转换为外部应用可以访问的Uri

参数

名称	类型	必填	描述
file	File	是	待转换的私有文件

返回值

类型	描述
Uri	转换后的Uri

兼容性

Android uni-app x	iOS uni-app x	web uni-app x	Android uni-app	iOS uni-app	web uni-app
3.99	x	-	3.99	x	-

// 使用外部应用打开项目内置图片资源
let file = new File(UTSAndroid.getResourcePath("static/logo.png"))
const uri = UTSAndroid.getFileProviderUri(file)
const intent = new Intent(Intent.ACTION_VIEW, uri)
intent.addFlags(Intent.FLAG_GRANT_READ_URI_PERMISSION)
const context = UTSAndroid.getUniActivity()!;
context.startActivity(intent);

getJavaClass(input:any)

获取对象的jvm class实例

参数

名称	类型	必填	描述
input	any	是	任意不为空对象

返回值

类型	描述
Class	传入对象所对应的class实例

兼容性

Android uni-app x	iOS uni-app x	web uni-app x	Android uni-app	iOS uni-app	web uni-app
4.0	x	-	4.0	x	-

export function getJavaClassTest() : boolean {
	let dispatcherClass = UTSAndroid.getJavaClass(UTSAndroid.getDispatcher())
	if("io.dcloud.uts.task.UTSTaskDispatcher" == dispatcherClass.name){
    	return true
	}
  	let applicationClass = UTSAndroid.getJavaClass(UTSAndroid.getAppContext()!)
  	if("io.dcloud.uniapp.UniApplication" == applicationClass.name){
    	return true
  	}
	return false
}

getTopPageActivity()

获取与当前页面绑定的activity对象，需要注意的是:当页面对象未与activity建立绑定关系时，可能为null

返回值

类型	描述
Activity | null	当前页面绑定的activity示例

兼容性

Android uni-app x	iOS uni-app x	web uni-app x	Android uni-app	iOS uni-app	web uni-app
4.0	x	-	4.0	x	-

// 获取当前栈顶activity
console.log(UTSAndroid.getTopPageActivity())

参见

相关 Bug