帮你快速理解、总结文档立即下载

uniapp_uts

最近更新时间:2026-09-11 17:47:30
我的收藏
美颜特效 SDK uni-app X (UTS) 版本核心接口类 XmagicApi,用于更新美颜数值、调用动效等功能。

接口说明

API
描述
设置资源存放的路径,用于把美颜资源复制到此路径下,如果不设置此路径,SDK 内部会有一个默认路径。
初始化美颜,用于复制美颜资源。
美颜鉴权。
设置日志级别。
打开或关闭美颜。
onResume
恢复美颜。
onPause
暂停美颜。
setEffect
设置美颜属性。
判断设备是否支持美颜。
返回当前设备支持的原子能力表。
检测当前设备是否支持此素材。
开启美颜增强模式。默认未开启,具体请参考 增强模式使用指南
调用此方法开启高性能模式。高性能模式开启后,美颜占用的系统 CPU/GPU 资源更少,可减少手机的发热和卡顿现象,更适合低端机长时间使用。此方法需要在 enableCustomVideoProcess 方法之前调用。
获取当前设备的性能等级。
获取本地美颜资源的根目录路径。
设置静音。
开启/关闭某些特性。
设置图像方向。
设置输出纹理保持比例。
addAiMode
添加 AI 模型文件,将下载好的 AI 模型文件复制到对应的文件夹下。如果 AI 模型放在工程中,则不需要调用此接口。
动态加载网络下载的 so 文件,这里只需要出入存放 so 的文件夹即可,仅支持 Android。
订阅 SDK 的回调事件。
取消订阅的事件。

成员函数说明

1. setResPath

设置资源存放的路径,用于把美颜资源复制到此路径下,如果不设置此路径,SDK 内部会有一个默认路径。
/**
* 设置存放美颜资源的路径,
* @param {String} resourceDir 用于存放美颜资源的路径文件夹(绝对路径),可参考demo
*/
static setResPath(resourceDir)
参数:
参数
含义
resourceDir
资源文件放置的目录。

2. copyXmaigcRes

用于复制美颜资源。
/**
* 用于复制美颜资源
* @param {Function(result)} callback result===true表示成功,false 表示失败
*/
static copyXmaigcRes(callback)
参数:
参数
含义
callback
由于资源复制是耗时任务,处理完成之后通过此接口回调结果。

3. setLicense

进行美颜鉴权,app 启动之后,需要成功鉴权一次才能使用美颜功能。
/**
* 鉴权
* @param {String} licenseUrl
* @param {String} licenseKey
* @param {Function(code,message)} callback code===0表示成功
*/
static setLicense(licenseUrl, licenseKey, callback)
其他错误码请参考 错误码
参数:
参数
含义
licenseUrl
官网申请的用于美颜鉴权的 licenseUrl。
licenseKey
官网申请的用于美颜鉴权的 licenseKey。
callback
鉴权结果回调方法,code==0表示鉴权成功。

4. setLogLevel

设置 native SDK 的日志级别。
/**
* 设置日志级别
* @param {number} logLevel
*/
static setLogLevel(logLevel)
参数:
参数
含义
logLevel
日志级别,具体参考 SDK 中的 LogLevel。

5. enableCustomVideoProcess

开启或关闭美颜。
/**
* 打开或关闭美颜
* @param {boolean} enable
* @returns
*/
static enableCustomVideoProcess(enable)
参数:
参数
含义
enable
开启或关闭美颜,true 表示开启美颜,false 表示关闭美颜。

6. onResume

恢复贴纸声音。
static onResume()

7. onPause

暂停贴纸声音。
static onPause()

8. setEffect

设置美颜、美型、滤镜、美妆、贴纸、分割等效果,可在任意线程调用。具体参数请参考 美颜参数说明
/**
* 更新美颜对象
* @param effect 对象结构如下
* {
* effectName:"",不为空的字符串,参考美颜参数表
* effectValue: 数值,一般为-100---100的值,可参考官网的美颜参数表
* resourcePath: 资源文件的路径,请参考美颜参数表 https://cloud.tencent.com/document/product/616/103616
* extraInfo:一个map集合,具体数值请参考美颜参数表
* }
*/
static setEffect(effect)

9. isSupportBeauty

判断当前设备是否支持美颜功能。
/**
* 判断设备是否支持美颜
* @returns {Boolean}
*/
static isSupportBeauty()
返回值:
类型
说明
Boolean
true 表示支持,false 表示不支持。

10. getDeviceAbilities

返回当前设备支持的原子能力表。
/**
* 返回当前设备支持的原子能力表
* @returns {String} JSON 格式的字符串
*/
static getDeviceAbilities()
返回值:
类型
说明
String
JSON 格式的设备能力信息。

11. isDeviceSupportMotion

检测当前设备是否支持指定的动效素材。
/**
* 检测当前设备是否支持此素材
* @param {String} motionPath 动效素材路径
* @returns {Boolean}
*/
static isDeviceSupportMotion(motionPath)
参数:
参数
含义
motionPath
动效素材文件路径。
返回值:
类型
说明
Boolean
true 表示支持该素材,false 表示不支持。

12. enableEnhancedMode

开启美颜增强模式。默认未开启,具体请参考 增强模式使用指南
/**
* 开启增强模式
*/
static enableEnhancedMode()

13. enableHighPerformance

调用此方法开启高性能模式。高性能模式开启后,美颜占用的系统 CPU/GPU 资源更少,可减少手机的发热和卡顿现象,更适合低端机长时间使用。此方法需要在 enableCustomVideoProcess 方法之前调用。
/**
* 开启性能模式,如果要使用此方法,此方法需要在 enableCustomVideoProcess 方法之前调用
*/
static enableHighPerformance()

14. getDeviceLevel

获取当前设备的性能等级。
/**
* 获取设备等级
* @returns {Number} 参见 SDK 中 interface.uts 文件的 DeviceLevel
*/
static getDeviceLevel()

15. getLocalResPath

获取本地美颜资源的根目录路径。
/**
* 获取资源根目录
* @returns {String} 资源根目录的绝对路径
*/
static getLocalResPath()
返回值:
类型
说明
String
资源根目录的绝对路径。

16. setAudioMute

设置静音。
/**
* 设置静音
*/
static setAudioMute(isMute)
参数:
参数
含义
isMute
true:静音

17. setFeatureEnableDisable

开启或关闭某些特性功能。
/**
* 开启/关闭某些特性
* @param {String} featuresJson feature 为 JSON 字符串,key 的值参考 SDK 中 interface.uts 文件的 FeatureName 对象,value 设置为 true 开启,false 关闭
*/
static setFeatureEnableDisable(featuresJson)
参数:
参数
含义
featuresJson
JSON 格式的特性配置字符串。

18. setImageOrientation

设置输入图像的方向。
/**
* 设置图像方向
* @param {Number} orientation 参见 SDK 中 interface.uts 文件的 TEImageOrientation
*/
static setImageOrientation(orientation)
参数:
参数
含义
orientation
图像方向值。

19. setOutputTextureKeepRatio

设置输出纹理保持比例。
/**
* 设置输出纹理保持比例
* @param {Number} ratio 保持比例值
*/
static setOutputTextureKeepRatio(ratio)
参数:
参数
含义
ratio
纹理保持比例值。

20. addAiMode

设置模型文件,如果模型文件是动态下载的,则需要在下载成功之后通过此接口将模型文件设置为 SDK,下次启动时不需要再设置。
/**
* 设置模型文件路径、
*
* @param {String} aiModePath 模型文件路径(绝对路径)
* @param callback 结果回调方法(0 成功, -1 路径不存在, -2 IO 错误)
*/
static addAiMode(aiModePath, callback)
参数:
参数
含义
aiModePath
模型文件路径(绝对路径)。
callback
结果回调方法。

21. setLibPathAndLoad

设置网络下载的 so 文件,只支持 Android 平台。
/**
* 动态加载网络下载的so文件,这里只需要出入存放so的文件夹即可
* @param {String} soDir 下载好的so文件的存放目录路径
*/
static setLibPathAndLoad(soDir)
参数:
参数
含义
soDir
下载好的 so 文件的存放目录路径。

22. onXmagicEvent

订阅 SDK 返回的事件。
/**
* 订阅回调事件
*
* @param {String} event 事件名称
* @param {Function} callback 事件名称以及回调方法可参考 SDK 中interface.uts 文件的 EventName
*/
static onXmagicEvent(event, callback)
参数:
参数
含义
event
事件名称,可以参考 EventName 类,订阅对应的事件。
callback
SDK 通过此方法将订阅的事件返回给 JS 侧。

23. offXmagicEvent

取消对应的事件订阅。
/**
* 取消回调事件
*
* @param {String} event 事件名称 可参考 SDK 中 interface.uts 文件的 EventName
*/
static offXmagicEvent(event)
参数:
参数
含义
event
事件名称,可以参考 EventName 类。