uni-app 鸿蒙 UTS 插件开发UTSHarmony 内置 API 完全指南【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址: https://gitcode.com/gh_mirrors/un/uni-app导读UTSHarmony 是 uni-app 在 HarmonyOS 平台为 UTS 插件作者提供的一组内置原生 API封装了鸿蒙侧最常见的系统能力——从颜色转换、路径换算、主题获取到 UIAbility 生命周期监听与系统权限申请。本文以 docs/uts/utsharmony.md 为骨架逐一解析其全部实例方法、参数签名与平台兼容版本并结合仓库内真实 UTS 插件的源码实现如 uni-theme、uni-exit、uni-clipboard 等给出可直接落地的调用范式帮助你写出能在 uni-app 与 uni-app x 两个体系中同时运行的鸿蒙原生插件。一、UTSHarmony 是什么鸿蒙 UTS 插件的内置能力入口1.1 UTS 插件与 HarmonyOS 的编译关系UTSuni type script是一门可编译为多平台原生语言的强类型语言。根据 docs/uts/README.md 的说明UTS 编译到鸿蒙 OS 平台时生成 ArkTS.ets且只有 uts 插件即uni_modules目录下utssdk中的代码才会编译为 ArkTS普通页面内的代码仍编译为 JS。因此 UTSHarmony 这套 API 的受众是那些需要调用鸿蒙原生能力的插件作者而不是普通页面开发者。UTSHarmony 与 UTSAndroid、UTSiOS 是同一设计思路下的平台兄弟——把只能在该平台使用、无法跨端抹平的原生能力通过条件编译隔离在// #ifdef APP-HARMONY代码块中。示例工程 examples/hello-uts/uni_modules/uts-tests/utssdk/UTSXXX.uts 就给出了标准写法// #ifdef APP-HARMONY let tempDir UTSHarmony.onAppAbilityCreate(() { const context UTSHarmony.getUIAbilityContext() tempDir context?.getApplicationContext?.()?.tempDir || }) // #endif1.2 整体 API 清单官方文档 docs/uts/utsharmony.md 共收录 13 个实例方法按用途可分为五类| 分类 | 方法 | | :- | :- | | 颜色与像素换算 |colorWithString、devicePX2px| | 路径与资源换算 |convert2AbsFullPath、getResourcePath| | 主题与环境 |getAppTheme、getOsTheme| | 应用生命周期监听 |onAppAbilityCreate、onAppAbilityNewWant、onAppAbilityShare、onAppAbilityWindowStageCreate| | 窗口、上下文与系统操作 |getCurrentWindow、getUIAbilityContext、exit、requestSystemPermission|说明文档中列出的方法为 13 个其中getAppTheme/getOsTheme/getCurrentWindow/getUIAbilityContext同时涉及主题、窗口与上下文语义上表按主用途归类。需要特别指出的是从仓库源码如 uni-rpx2px 调用UTSHarmony.getWindowStage()、uni-theme 调用UTSHarmony.onOsThemeChange/setAppTheme/onAppThemeChange/offOsThemeChange/offAppThemeChange可以推断UTSHarmony 暴露的内置成员并不仅限于该文档所列举的实例方法还有getWindowStage、setAppTheme、onOsThemeChange、offOsThemeChange、onAppThemeChange、offAppThemeChange等成员文档只选取了其中通用性最强的一部分进行收录。二、颜色与像素换算2.1 colorWithString(colorString)colorwithstring将颜色字符串转换为鸿蒙平台对应的颜色值。参数| 名称 | 类型 | 必填 | | :- | :- | :- | | colorString | string | 是 |返回值string兼容性| 运行环境 | 最低版本 | | :- | :- | | uni-app xHarmonyOS | 5.21 | | uni-appHarmonyOS UTS 插件 | 5.21 |该方法输入一个颜色字符串如#FF0000、rgba(...)等 CSS 风格写法返回鸿蒙原生侧可识别的颜色值字符串。它属于典型的跨端抹平工具Web/小程序侧直接使用颜色字符串而鸿蒙侧需要经此转换才能用于原生组件或 ArkUI 属性。colorString为必填参数调用时无需关心具体内部格式返回值可直接透传给原生能力。2.2 devicePX2px(px)物理像素转换为页面的 px 像素。参数| 名称 | 类型 | 必填 | | :- | :- | :- | | px | number | 是 |返回值number兼容性| 运行环境 | 最低版本 | | :- | :- | | uni-app xHarmonyOS | 4.61 | | uni-appHarmonyOS UTS 插件 | 4.31 |鸿蒙设备的物理像素密度与 uni-app 页面逻辑像素px并不一致当插件拿到原生返回的物理像素尺寸例如截屏尺寸、图像宽高需要换算为页面 px 时即可调用本方法。与此相关的思路可参考仓库中 uni-rpx2px 的实现——它通过UTSHarmony.getWindowStage()拿到窗口后用mainWindow.getWindowProperties().windowRect.width获取窗口物理宽度、用px2vp换算为 vp再按(number / 750) * windowWidthInVp计算 rpx 对应的 vp 值。devicePX2px与rpx2px同为像素体系换算工具差别在于前者处理物理像素与逻辑像素后者处理 rpx 与 vp。三、路径换算与资源定位三、路径与资源定位3.1 convert2AbsFullPath(filePath)将文件的项目相对地址转换为运行期对应的绝对地址。参数| 名称 | 类型 | 必填 | | :- | :- | :- | | filePath | string | 是 |返回值string兼容性| 运行环境 | 最低版本 | | :- | :- | | uni-app xHarmonyOS | 4.61 | | uni-appHarmonyOS UTS 插件 | 4.61 |UTS 插件中拿到的文件路径通常是相对于项目根目录的项目相对地址例如static/logo.png或_doc/uniapp_start/xxx。但调用鸿蒙原生文件能力File I/O、媒体库、相机返回等时系统要求的是沙箱内的绝对路径。convert2AbsFullPath就是完成这一换算的官方入口。这一设计在其他平台有完全对称的 APIAndroid 侧UTSAndroid.convert2AbsFullPath(src)出现在 uni-chooseMedia 等插件的源码中iOS 侧UTSiOS.convert2AbsFullPath(self.src)出现在 uni-createInnerAudioContext 中。因此在编写跨端 UTS 插件时可以这样组织代码// #ifdef APP-HARMONY const absPath UTSHarmony.convert2AbsFullPath(static/logo.png) // #endif3.2 getResourcePath(filePath)获取资源文件的原生路径。参数| 名称 | 类型 | 必填 | | :- | :- | :- | | filePath | string | 是 |返回值string兼容性| 运行环境 | 最低版本 | | :- | :- | | uni-app xHarmonyOS | 4.61 | | uni-appHarmonyOS UTS 插件 | 4.61 |与convert2AbsFullPath面向运行期生成/项目内文件不同getResourcePath面向资源文件打包进应用的 rawfile / resources 等原生资源的原生路径获取。两者都要求传入string类型文件路径并返回string在插件中用于将资源路径交给原生模块处理前的最后一步换算。四、主题获取与系统环境4.1 getAppTheme()获取应用主题。返回值| 类型 | 描述 | | :- | :- | | AppTheme | 应用主题 |兼容性| 运行环境 | 最低版本 | | :- | :- | | uni-app xHarmonyOS | 4.71需 HarmonyOS 系统版本 5.0.012及以上 | | uni-appHarmonyOS UTS 插件 | 4.71 |返回值AppTheme即应用当前的主题模式。仓库中的 uni-theme 插件展示了完整的主题能力闭环UTSHarmony.setAppTheme(options.theme)写入主题auto | dark | lightUTSHarmony.onAppThemeChange(callback)监听应用主题变化并返回AppThemeChangeResult配合offAppThemeChange(id)反注册。插件作者在实现自定义主题跟随逻辑时可用getAppTheme()获取初始应用主题再用onAppThemeChange响应后续变化。4.2 getOsTheme()获取系统主题。返回值| 类型 | 描述 | | :- | :- | | OsTheme | 系统主题 |兼容性| 运行环境 | 最低版本 | | :- | :- | | uni-app xHarmonyOS | 4.71需 HarmonyOS 系统版本 5.0.012及以上 | | uni-appHarmonyOS UTS 插件 | 4.71 |系统主题浅色/深色是设备级状态应用主题可在其基础上覆盖。uni-theme 插件中的onHostThemeChange就是通过UTSHarmony.onOsThemeChange把系统主题映射为宿主主题osTheme dark ? dark : light见 uni-theme说明 UTSHarmony 内部同时具备系统主题的查询与监听能力getOsTheme()与onOsThemeChange相互配合可完成完整的深色模式适配。五、应用 EntryAbility 生命周期监听鸿蒙应用以 Ability默认 EntryAbility为运行单元。UTSHarmony 提供了一组以onAppAbility...开头的事件监听方法用于在 UTS 插件侧感知应用启动、复用与分享等关键生命周期时机。它们的共同特点是参数均为必填回调函数返回值均为void调用后无需管理句柄回调按需注册即可在 uni-app x 中最低支持 4.61在 uni-app UTS 插件中最低支持 4.31。5.1 onAppAbilityCreate(callback)监听应用 EntryAbility 生命周期onCreate。参数| 名称 | 类型 | 必填 | | :- | :- | :- | | callback |(want: Want, launchParam: AbilityConstant.LaunchParam) void| 是 |返回值void兼容性uni-app x 4.61 / uni-app UTS 插件 4.31。onCreate是应用冷启动的入口此时通常还拿不到 Window但可以安全获取UIAbilityContext。示例工程 examples/hello-uts/uni_modules/uts-tests/utssdk/UTSXXX.uts 正是在onAppAbilityCreate回调里调用getUIAbilityContext()获取tempDir并用于后续单元测试断言。回调携带的want包含启动参数如冷启动的 url、query 等launchParam描述启动方式冷启动/热启动等。5.2 onAppAbilityNewWant(callback)监听应用 EntryAbility 生命周期onNewWant。参数| 名称 | 类型 | 必填 | | :- | :- | :- | | callback |(want: Want, launchParam: AbilityConstant.LaunchParam) void| 是 |返回值void兼容性uni-app x 4.61 / uni-app UTS 插件 4.31。当应用已运行、再次通过 startAbility 等方式拉起时触发onNewWant。典型场景是App 已在前台/后台存活用户从外部链接、系统分享或其他应用再次唤起应用。此时需要在此回调中解析新的want参数并刷新页面状态。5.3 onAppAbilityShare(callback)监听应用 EntryAbility 生命周期onShare。参数| 名称 | 类型 | 必填 | | :- | :- | :- | | callback |(wantParam: Recordstring, any) void| 是 |返回值void兼容性uni-app x 4.61 / uni-app UTS 插件 4.31。鸿蒙系统级分享如分享到本应用触发onShare时回调接收分享参数wantParam。UTS 中Recordstring, any对应鸿蒙侧分享携带的键值参数集合插件可在回调中读取分享内容并路由到对应业务页面。5.4 onAppAbilityWindowStageCreate(callback)监听应用 EntryAbility 生命周期onWindowStageCreate。参数| 名称 | 类型 | 必填 | | :- | :- | :- | | callback |(windowStage: _ohos_window__default.WindowStage) void| 是 |返回值void兼容性uni-app x 4.61 / uni-app UTS 插件 4.31。onWindowStageCreate是窗口阶段创建完成的时机回调携带WindowStage对象——这正是getCurrentWindow()与getWindowStage()系 API 可用性的前提。仓库中 uni-rpx2px 在运行时通过UTSHarmony.getWindowStage()拿到WindowStage后调用getMainWindowSync()读取窗口尺寸从源码结构看getWindowStage获取的窗口阶段即来源于此生命周期需要窗口相关能力尺寸、旋转、沉浸式等的插件应在该回调之后再访问窗口对象。六、窗口、上下文与系统操作6.1 getCurrentWindow()获取当前原生窗口对象。返回值| 类型 | | :- | |_ohos_window.default.Window|兼容性uni-app x 4.61 / uni-app UTS 插件 4.31。返回鸿蒙ohos.window模块的Window对象可用于查询窗口属性宽高、避免区域、设置窗口全屏或沉浸式等原生操作。注意该方法依赖窗口已创建建议在onAppAbilityWindowStageCreate回调之后调用。6.2 getUIAbilityContext()获取应用的 UIAbilityContext。返回值| 类型 | | :- | |common.UIAbilityContext|兼容性uni-app x 4.61 / uni-app UTS 插件 4.31。UIAbilityContext是鸿蒙应用上下文的入口可进一步获取applicationContext从而得到tempDir、filesDir、cacheDir等目录、启动其他 Ability、申请权限等。示例工程中的测试用例正是这一链路的标准用法UTSXXX.utsconst context UTSHarmony.getUIAbilityContext() tempDir context?.getApplicationContext?.()?.tempDir || 官方文档同时给出鸿蒙官方参考文档入口 UIAbilityContext详见 docs/uts/utsharmony.md 的关联文档一节需要深入理解 Context 各字段语义时可查阅鸿蒙官方文档。6.3 exit()退出应用。返回值void兼容性uni-app xHarmonyOS标记为x当前版本不支持/ uni-app UTS 插件 4.31。注意一个值得关注的版本差异exit()在 uni-app x 的兼容表格中标记为x意味着 uni-app x 环境暂不支持直接退出应用而 uni-app 的鸿蒙 UTS 插件自 4.31 起可用。仓库中 uni-exit 插件的鸿蒙实现即为一行透传export const exit: Exit defineSyncApivoid( API_EXIT, function () { UTSHarmony.exit() } ) as Exit该插件把UTSHarmony.exit()封装为uni.exitAPI 供页面调用插件作者可直接复用这一模式在 uni-app x 中需自行评估替代方案如引导用户通过系统手势退出。6.4 requestSystemPermission(permissions, success?, fail?)请求系统权限。参数| 名称 | 类型 | 必填 | | :- | :- | :- | | permissions |string[]| 是 | | success |(allRight: boolean, grantedList: Arraystring) void| 否 | | fail |(doNotAskAgain: boolean, grantedList: Arraystring) void| 否 |返回值void兼容性uni-app x 4.61 / uni-app UTS 插件 4.31。这是 UTS 插件申请鸿蒙运行时权限的统一入口。permissions传入鸿蒙权限名数组如ohos.permission.READ_PASTEBOARD、ohos.permission.WRITE_CONTACTS、ohos.permission.ACCESS_BIOMETRIC等success回调中allRight表示是否全部授权grantedList为本次已授权的权限列表fail回调中doNotAskAgain表示用户是否勾选了不再询问。仓库中大量官方插件都以它为权限前置校验以下是两个典型范式范式一请求单个权限授权后继续业务uni-addPhoneContactUTSHarmony.requestSystemPermission([ohos.permission.WRITE_CONTACTS], (allRight: boolean) { if (allRight) { // 写入联系人业务 } })范式二请求读剪贴板权限并在 fail 回调中兜底uni-clipboardUTSHarmony.requestSystemPermission( [ohos.permission.READ_PASTEBOARD], (allRight: boolean) { if (allRight) { const pasteData systemPasteboard.getDataSync() // 读取剪贴板内容 } else { callback({ data: Permission denied, result: fail } as ClipboardCallbackOptions) } }, () { callback({ data: Permission denied, result: fail } as ClipboardCallbackOptions) }, )范式三生物识别权限 拒绝时的错误码映射uni-authenticationconst PERMISSIONS [ohos.permission.ACCESS_BIOMETRIC] UTSHarmony.requestSystemPermission(PERMISSIONS, (allRight: boolean) { if (allRight) { // 检测指纹/人脸支持能力 } else { executor.reject(getErrorMessage(201)) } }, () { executor.reject(getErrorMessage(201)) })同时可见 uni-oauth-huawei、uni-openAppAuthorizeSetting、uni-payment-wxpay 等插件也都以requestSystemPermission作为各自敏感权限的前置申请方式。实战建议fail回调务必处理——当用户拒绝且勾选不再询问doNotAskAgain为 true时应引导用户到系统设置页手动开启而非重复弹窗。七、版本兼容矩阵速查将文档中的兼容性信息汇总如下uni-app x指 uni-app x 的 HarmonyOS 端uni-app指 uni-app 的 HarmonyOS UTS 插件环境x表示该环境当前版本不支持| 方法 | uni-app xHarmonyOS | uni-appHarmonyOS UTS 插件 | 特殊前提 | | :- | :- | :- | :- | |colorWithString| 5.21 | 5.21 | — | |convert2AbsFullPath| 4.61 | 4.61 | — | |devicePX2px| 4.61 | 4.31 | — | |exit| x暂不支持 | 4.31 | — | |getAppTheme| 4.71 | 4.71 | 系统版本 ≥ 5.0.012 | |getCurrentWindow| 4.61 | 4.31 | 需在窗口创建后调用 | |getOsTheme| 4.71 | 4.71 | 系统版本 ≥ 5.0.012 | |getResourcePath| 4.61 | 4.61 | — | |getUIAbilityContext| 4.61 | 4.31 | — | |onAppAbilityCreate| 4.61 | 4.31 | — | |onAppAbilityNewWant| 4.61 | 4.31 | — | |onAppAbilityShare| 4.61 | 4.31 | — | |onAppAbilityWindowStageCreate| 4.61 | 4.31 | — | |requestSystemPermission| 4.61 | 4.31 | — |从矩阵可以看出几个规律主题类 APIgetAppTheme/getOsTheme版本要求最高4.71且依赖鸿蒙系统 5.0.012及以上低版本系统调用前应做能力探测colorWithString要求 5.21是最晚开放的方法大部分生命周期、上下文、权限方法在 4.314.61 区间已开放属于基础设施级别的能力exit()是唯一在 uni-app x 侧标为x的方法跨体系复用uni.exit时需注意环境差异。八、在 UTS 插件中的落地步骤综合文档与仓库实践在 uni-app/uni-app x 项目中编写使用 UTSHarmony 的鸿蒙 UTS 插件推荐按以下流程创建插件目录在项目的uni_modules下新建插件如uni-my-plugin鸿蒙实现放在uni_modules/uni-my-plugin/utssdk/app-harmony/index.utsAndroid/iOS 分别放在app-android/app-ios目录参考 uni-exit、uni-clipboard 的目录结构用条件编译隔离平台代码// #ifdef APP-HARMONY块内使用 UTSHarmony其他平台使用 UTSAndroid/UTSiOS参考 UTSXXX.uts 的写法注册插件 API通过defineSyncApi/defineAsyncApi将内部实现封装为对外 API如 uni-exit 的defineSyncApi包装并同步维护interface.uts类型声明与protocol.uts协议号权限先行涉及敏感能力联系人、剪贴板、生物识别、相机、定位等时先调用UTSHarmony.requestSystemPermission申请权限并在fail回调处理不再询问分支注意生命周期与窗口时序需要getUIAbilityContext()应在onAppAbilityCreate之后需要getCurrentWindow()应在onAppAbilityWindowStageCreate之后核对版本矩阵根据目标 HBuilderX 版本与鸿蒙系统版本对照上文兼容矩阵避免在低版本环境调用高版本 API。九、常见问题与注意事项页面代码中能直接用 UTSHarmony 吗不能。UTSHarmony 面向uni_modules中utssdk目录下的 UTS 插件代码该部分才编译为 ArkTS页面内的脚本仍编译为 JS无法访问这些原生 API。需要先封装为插件 API 再在页面中调用。exit()在 uni-app x 不可用怎么办文档将 uni-app x 的兼容版本标为x说明该环境暂不支持直接调用退出应用在 uni-app x 中如需类似能力应评估替代方案而不能直接透传UTSHarmony.exit()。主题 API 的系统版本门槛getAppTheme/getOsTheme需要 HarmonyOS 系统版本 ≥ 5.0.012且 uni-app x 与 uni-app 插件均要求 HBuilderX 4.71低版本环境需通过条件编译或运行时能力探测保护。权限弹窗与不再询问鸿蒙系统对同一权限的多次拒绝会进入不再询问状态届时requestSystemPermission的fail回调中doNotAskAgain为true应引导用户前往系统设置开启避免请求无效化。路径换算的语义区分项目内文件用convert2AbsFullPath资源文件用getResourcePath二者入参同为项目相对路径但转换的目标存储区域不同混用可能导致原生模块读取失败。生命周期回调注册时机onAppAbilityCreate等监听建议在插件初始化模块顶层或首次调用时尽早注册避免错过冷启动早期的want参数监听是常驻型的无需手动反注册文档中未提供对应的 off 方法。更多 UTS 语言细节UTSHarmony 属于平台增补 API使用前建议先掌握 UTS 语言基础类型、条件编译、与 TS 的差异详见 docs/uts/README.md、数据类型、条件编译、uts 与 ts 的差异鸿蒙插件开发的完整流程另见 docs/plugin/uts-for-harmony.md 与 docs/plugin/uts-plugin.md。十、参考文件索引| 内容 | 仓库路径 | | :- | :- | | UTSHarmony 官方 API 文档 | docs/uts/utsharmony.md | | UTS 语言介绍与编译矩阵 | docs/uts/README.md | | UTS 数据类型 | docs/uts/data-type.md | | UTS 条件编译 | docs/uts/conditional.md | | UTS 与 TS 差异 | docs/uts/uts_diff_ts.md | | 鸿蒙 UTS 插件开发指南 | docs/plugin/uts-for-harmony.md | | UTS 插件通用开发指南 | docs/plugin/uts-plugin.md | | 官方插件退出应用鸿蒙实现透传UTSHarmony.exit | src/uni_modules/uni-exit/utssdk/app-harmony/index.uts | | 官方插件主题setAppTheme/onAppThemeChange/onOsThemeChange | src/uni_modules/uni-theme/utssdk/app-harmony/index.uts | | 官方插件剪贴板权限requestSystemPermission | src/uni_modules/uni-clipboard/utssdk/app-harmony/index.uts | | 官方插件添加联系人requestSystemPermission | src/uni_modules/uni-addPhoneContact/utssdk/app-harmony/index.uts | | 官方插件生物认证权限 失败码映射 | src/uni_modules/uni-authentication/utssdk/app-harmony/index.uts | | 官方插件rpx 换算getWindowStage窗口读取 | src/uni_modules/uni-rpx2px/utssdk/app-harmony/index.uts | | 测试示例onAppAbilityCreategetUIAbilityContext| examples/hello-uts/uni_modules/uts-tests/utssdk/UTSXXX.uts |【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址: https://gitcode.com/gh_mirrors/un/uni-app创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
uni-app 鸿蒙 UTS 插件开发UTSHarmony 内置 API 完全指南【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址: https://gitcode.com/gh_mirrors/un/uni-app导读UTSHarmony 是 uni-app 在 HarmonyOS 平台为 UTS 插件作者提供的一组内置原生 API封装了鸿蒙侧最常见的系统能力——从颜色转换、路径换算、主题获取到 UIAbility 生命周期监听与系统权限申请。本文以 docs/uts/utsharmony.md 为骨架逐一解析其全部实例方法、参数签名与平台兼容版本并结合仓库内真实 UTS 插件的源码实现如 uni-theme、uni-exit、uni-clipboard 等给出可直接落地的调用范式帮助你写出能在 uni-app 与 uni-app x 两个体系中同时运行的鸿蒙原生插件。一、UTSHarmony 是什么鸿蒙 UTS 插件的内置能力入口1.1 UTS 插件与 HarmonyOS 的编译关系UTSuni type script是一门可编译为多平台原生语言的强类型语言。根据 docs/uts/README.md 的说明UTS 编译到鸿蒙 OS 平台时生成 ArkTS.ets且只有 uts 插件即uni_modules目录下utssdk中的代码才会编译为 ArkTS普通页面内的代码仍编译为 JS。因此 UTSHarmony 这套 API 的受众是那些需要调用鸿蒙原生能力的插件作者而不是普通页面开发者。UTSHarmony 与 UTSAndroid、UTSiOS 是同一设计思路下的平台兄弟——把只能在该平台使用、无法跨端抹平的原生能力通过条件编译隔离在// #ifdef APP-HARMONY代码块中。示例工程 examples/hello-uts/uni_modules/uts-tests/utssdk/UTSXXX.uts 就给出了标准写法// #ifdef APP-HARMONY let tempDir UTSHarmony.onAppAbilityCreate(() { const context UTSHarmony.getUIAbilityContext() tempDir context?.getApplicationContext?.()?.tempDir || }) // #endif1.2 整体 API 清单官方文档 docs/uts/utsharmony.md 共收录 13 个实例方法按用途可分为五类| 分类 | 方法 | | :- | :- | | 颜色与像素换算 |colorWithString、devicePX2px| | 路径与资源换算 |convert2AbsFullPath、getResourcePath| | 主题与环境 |getAppTheme、getOsTheme| | 应用生命周期监听 |onAppAbilityCreate、onAppAbilityNewWant、onAppAbilityShare、onAppAbilityWindowStageCreate| | 窗口、上下文与系统操作 |getCurrentWindow、getUIAbilityContext、exit、requestSystemPermission|说明文档中列出的方法为 13 个其中getAppTheme/getOsTheme/getCurrentWindow/getUIAbilityContext同时涉及主题、窗口与上下文语义上表按主用途归类。需要特别指出的是从仓库源码如 uni-rpx2px 调用UTSHarmony.getWindowStage()、uni-theme 调用UTSHarmony.onOsThemeChange/setAppTheme/onAppThemeChange/offOsThemeChange/offAppThemeChange可以推断UTSHarmony 暴露的内置成员并不仅限于该文档所列举的实例方法还有getWindowStage、setAppTheme、onOsThemeChange、offOsThemeChange、onAppThemeChange、offAppThemeChange等成员文档只选取了其中通用性最强的一部分进行收录。二、颜色与像素换算2.1 colorWithString(colorString)colorwithstring将颜色字符串转换为鸿蒙平台对应的颜色值。参数| 名称 | 类型 | 必填 | | :- | :- | :- | | colorString | string | 是 |返回值string兼容性| 运行环境 | 最低版本 | | :- | :- | | uni-app xHarmonyOS | 5.21 | | uni-appHarmonyOS UTS 插件 | 5.21 |该方法输入一个颜色字符串如#FF0000、rgba(...)等 CSS 风格写法返回鸿蒙原生侧可识别的颜色值字符串。它属于典型的跨端抹平工具Web/小程序侧直接使用颜色字符串而鸿蒙侧需要经此转换才能用于原生组件或 ArkUI 属性。colorString为必填参数调用时无需关心具体内部格式返回值可直接透传给原生能力。2.2 devicePX2px(px)物理像素转换为页面的 px 像素。参数| 名称 | 类型 | 必填 | | :- | :- | :- | | px | number | 是 |返回值number兼容性| 运行环境 | 最低版本 | | :- | :- | | uni-app xHarmonyOS | 4.61 | | uni-appHarmonyOS UTS 插件 | 4.31 |鸿蒙设备的物理像素密度与 uni-app 页面逻辑像素px并不一致当插件拿到原生返回的物理像素尺寸例如截屏尺寸、图像宽高需要换算为页面 px 时即可调用本方法。与此相关的思路可参考仓库中 uni-rpx2px 的实现——它通过UTSHarmony.getWindowStage()拿到窗口后用mainWindow.getWindowProperties().windowRect.width获取窗口物理宽度、用px2vp换算为 vp再按(number / 750) * windowWidthInVp计算 rpx 对应的 vp 值。devicePX2px与rpx2px同为像素体系换算工具差别在于前者处理物理像素与逻辑像素后者处理 rpx 与 vp。三、路径换算与资源定位三、路径与资源定位3.1 convert2AbsFullPath(filePath)将文件的项目相对地址转换为运行期对应的绝对地址。参数| 名称 | 类型 | 必填 | | :- | :- | :- | | filePath | string | 是 |返回值string兼容性| 运行环境 | 最低版本 | | :- | :- | | uni-app xHarmonyOS | 4.61 | | uni-appHarmonyOS UTS 插件 | 4.61 |UTS 插件中拿到的文件路径通常是相对于项目根目录的项目相对地址例如static/logo.png或_doc/uniapp_start/xxx。但调用鸿蒙原生文件能力File I/O、媒体库、相机返回等时系统要求的是沙箱内的绝对路径。convert2AbsFullPath就是完成这一换算的官方入口。这一设计在其他平台有完全对称的 APIAndroid 侧UTSAndroid.convert2AbsFullPath(src)出现在 uni-chooseMedia 等插件的源码中iOS 侧UTSiOS.convert2AbsFullPath(self.src)出现在 uni-createInnerAudioContext 中。因此在编写跨端 UTS 插件时可以这样组织代码// #ifdef APP-HARMONY const absPath UTSHarmony.convert2AbsFullPath(static/logo.png) // #endif3.2 getResourcePath(filePath)获取资源文件的原生路径。参数| 名称 | 类型 | 必填 | | :- | :- | :- | | filePath | string | 是 |返回值string兼容性| 运行环境 | 最低版本 | | :- | :- | | uni-app xHarmonyOS | 4.61 | | uni-appHarmonyOS UTS 插件 | 4.61 |与convert2AbsFullPath面向运行期生成/项目内文件不同getResourcePath面向资源文件打包进应用的 rawfile / resources 等原生资源的原生路径获取。两者都要求传入string类型文件路径并返回string在插件中用于将资源路径交给原生模块处理前的最后一步换算。四、主题获取与系统环境4.1 getAppTheme()获取应用主题。返回值| 类型 | 描述 | | :- | :- | | AppTheme | 应用主题 |兼容性| 运行环境 | 最低版本 | | :- | :- | | uni-app xHarmonyOS | 4.71需 HarmonyOS 系统版本 5.0.012及以上 | | uni-appHarmonyOS UTS 插件 | 4.71 |返回值AppTheme即应用当前的主题模式。仓库中的 uni-theme 插件展示了完整的主题能力闭环UTSHarmony.setAppTheme(options.theme)写入主题auto | dark | lightUTSHarmony.onAppThemeChange(callback)监听应用主题变化并返回AppThemeChangeResult配合offAppThemeChange(id)反注册。插件作者在实现自定义主题跟随逻辑时可用getAppTheme()获取初始应用主题再用onAppThemeChange响应后续变化。4.2 getOsTheme()获取系统主题。返回值| 类型 | 描述 | | :- | :- | | OsTheme | 系统主题 |兼容性| 运行环境 | 最低版本 | | :- | :- | | uni-app xHarmonyOS | 4.71需 HarmonyOS 系统版本 5.0.012及以上 | | uni-appHarmonyOS UTS 插件 | 4.71 |系统主题浅色/深色是设备级状态应用主题可在其基础上覆盖。uni-theme 插件中的onHostThemeChange就是通过UTSHarmony.onOsThemeChange把系统主题映射为宿主主题osTheme dark ? dark : light见 uni-theme说明 UTSHarmony 内部同时具备系统主题的查询与监听能力getOsTheme()与onOsThemeChange相互配合可完成完整的深色模式适配。五、应用 EntryAbility 生命周期监听鸿蒙应用以 Ability默认 EntryAbility为运行单元。UTSHarmony 提供了一组以onAppAbility...开头的事件监听方法用于在 UTS 插件侧感知应用启动、复用与分享等关键生命周期时机。它们的共同特点是参数均为必填回调函数返回值均为void调用后无需管理句柄回调按需注册即可在 uni-app x 中最低支持 4.61在 uni-app UTS 插件中最低支持 4.31。5.1 onAppAbilityCreate(callback)监听应用 EntryAbility 生命周期onCreate。参数| 名称 | 类型 | 必填 | | :- | :- | :- | | callback |(want: Want, launchParam: AbilityConstant.LaunchParam) void| 是 |返回值void兼容性uni-app x 4.61 / uni-app UTS 插件 4.31。onCreate是应用冷启动的入口此时通常还拿不到 Window但可以安全获取UIAbilityContext。示例工程 examples/hello-uts/uni_modules/uts-tests/utssdk/UTSXXX.uts 正是在onAppAbilityCreate回调里调用getUIAbilityContext()获取tempDir并用于后续单元测试断言。回调携带的want包含启动参数如冷启动的 url、query 等launchParam描述启动方式冷启动/热启动等。5.2 onAppAbilityNewWant(callback)监听应用 EntryAbility 生命周期onNewWant。参数| 名称 | 类型 | 必填 | | :- | :- | :- | | callback |(want: Want, launchParam: AbilityConstant.LaunchParam) void| 是 |返回值void兼容性uni-app x 4.61 / uni-app UTS 插件 4.31。当应用已运行、再次通过 startAbility 等方式拉起时触发onNewWant。典型场景是App 已在前台/后台存活用户从外部链接、系统分享或其他应用再次唤起应用。此时需要在此回调中解析新的want参数并刷新页面状态。5.3 onAppAbilityShare(callback)监听应用 EntryAbility 生命周期onShare。参数| 名称 | 类型 | 必填 | | :- | :- | :- | | callback |(wantParam: Recordstring, any) void| 是 |返回值void兼容性uni-app x 4.61 / uni-app UTS 插件 4.31。鸿蒙系统级分享如分享到本应用触发onShare时回调接收分享参数wantParam。UTS 中Recordstring, any对应鸿蒙侧分享携带的键值参数集合插件可在回调中读取分享内容并路由到对应业务页面。5.4 onAppAbilityWindowStageCreate(callback)监听应用 EntryAbility 生命周期onWindowStageCreate。参数| 名称 | 类型 | 必填 | | :- | :- | :- | | callback |(windowStage: _ohos_window__default.WindowStage) void| 是 |返回值void兼容性uni-app x 4.61 / uni-app UTS 插件 4.31。onWindowStageCreate是窗口阶段创建完成的时机回调携带WindowStage对象——这正是getCurrentWindow()与getWindowStage()系 API 可用性的前提。仓库中 uni-rpx2px 在运行时通过UTSHarmony.getWindowStage()拿到WindowStage后调用getMainWindowSync()读取窗口尺寸从源码结构看getWindowStage获取的窗口阶段即来源于此生命周期需要窗口相关能力尺寸、旋转、沉浸式等的插件应在该回调之后再访问窗口对象。六、窗口、上下文与系统操作6.1 getCurrentWindow()获取当前原生窗口对象。返回值| 类型 | | :- | |_ohos_window.default.Window|兼容性uni-app x 4.61 / uni-app UTS 插件 4.31。返回鸿蒙ohos.window模块的Window对象可用于查询窗口属性宽高、避免区域、设置窗口全屏或沉浸式等原生操作。注意该方法依赖窗口已创建建议在onAppAbilityWindowStageCreate回调之后调用。6.2 getUIAbilityContext()获取应用的 UIAbilityContext。返回值| 类型 | | :- | |common.UIAbilityContext|兼容性uni-app x 4.61 / uni-app UTS 插件 4.31。UIAbilityContext是鸿蒙应用上下文的入口可进一步获取applicationContext从而得到tempDir、filesDir、cacheDir等目录、启动其他 Ability、申请权限等。示例工程中的测试用例正是这一链路的标准用法UTSXXX.utsconst context UTSHarmony.getUIAbilityContext() tempDir context?.getApplicationContext?.()?.tempDir || 官方文档同时给出鸿蒙官方参考文档入口 UIAbilityContext详见 docs/uts/utsharmony.md 的关联文档一节需要深入理解 Context 各字段语义时可查阅鸿蒙官方文档。6.3 exit()退出应用。返回值void兼容性uni-app xHarmonyOS标记为x当前版本不支持/ uni-app UTS 插件 4.31。注意一个值得关注的版本差异exit()在 uni-app x 的兼容表格中标记为x意味着 uni-app x 环境暂不支持直接退出应用而 uni-app 的鸿蒙 UTS 插件自 4.31 起可用。仓库中 uni-exit 插件的鸿蒙实现即为一行透传export const exit: Exit defineSyncApivoid( API_EXIT, function () { UTSHarmony.exit() } ) as Exit该插件把UTSHarmony.exit()封装为uni.exitAPI 供页面调用插件作者可直接复用这一模式在 uni-app x 中需自行评估替代方案如引导用户通过系统手势退出。6.4 requestSystemPermission(permissions, success?, fail?)请求系统权限。参数| 名称 | 类型 | 必填 | | :- | :- | :- | | permissions |string[]| 是 | | success |(allRight: boolean, grantedList: Arraystring) void| 否 | | fail |(doNotAskAgain: boolean, grantedList: Arraystring) void| 否 |返回值void兼容性uni-app x 4.61 / uni-app UTS 插件 4.31。这是 UTS 插件申请鸿蒙运行时权限的统一入口。permissions传入鸿蒙权限名数组如ohos.permission.READ_PASTEBOARD、ohos.permission.WRITE_CONTACTS、ohos.permission.ACCESS_BIOMETRIC等success回调中allRight表示是否全部授权grantedList为本次已授权的权限列表fail回调中doNotAskAgain表示用户是否勾选了不再询问。仓库中大量官方插件都以它为权限前置校验以下是两个典型范式范式一请求单个权限授权后继续业务uni-addPhoneContactUTSHarmony.requestSystemPermission([ohos.permission.WRITE_CONTACTS], (allRight: boolean) { if (allRight) { // 写入联系人业务 } })范式二请求读剪贴板权限并在 fail 回调中兜底uni-clipboardUTSHarmony.requestSystemPermission( [ohos.permission.READ_PASTEBOARD], (allRight: boolean) { if (allRight) { const pasteData systemPasteboard.getDataSync() // 读取剪贴板内容 } else { callback({ data: Permission denied, result: fail } as ClipboardCallbackOptions) } }, () { callback({ data: Permission denied, result: fail } as ClipboardCallbackOptions) }, )范式三生物识别权限 拒绝时的错误码映射uni-authenticationconst PERMISSIONS [ohos.permission.ACCESS_BIOMETRIC] UTSHarmony.requestSystemPermission(PERMISSIONS, (allRight: boolean) { if (allRight) { // 检测指纹/人脸支持能力 } else { executor.reject(getErrorMessage(201)) } }, () { executor.reject(getErrorMessage(201)) })同时可见 uni-oauth-huawei、uni-openAppAuthorizeSetting、uni-payment-wxpay 等插件也都以requestSystemPermission作为各自敏感权限的前置申请方式。实战建议fail回调务必处理——当用户拒绝且勾选不再询问doNotAskAgain为 true时应引导用户到系统设置页手动开启而非重复弹窗。七、版本兼容矩阵速查将文档中的兼容性信息汇总如下uni-app x指 uni-app x 的 HarmonyOS 端uni-app指 uni-app 的 HarmonyOS UTS 插件环境x表示该环境当前版本不支持| 方法 | uni-app xHarmonyOS | uni-appHarmonyOS UTS 插件 | 特殊前提 | | :- | :- | :- | :- | |colorWithString| 5.21 | 5.21 | — | |convert2AbsFullPath| 4.61 | 4.61 | — | |devicePX2px| 4.61 | 4.31 | — | |exit| x暂不支持 | 4.31 | — | |getAppTheme| 4.71 | 4.71 | 系统版本 ≥ 5.0.012 | |getCurrentWindow| 4.61 | 4.31 | 需在窗口创建后调用 | |getOsTheme| 4.71 | 4.71 | 系统版本 ≥ 5.0.012 | |getResourcePath| 4.61 | 4.61 | — | |getUIAbilityContext| 4.61 | 4.31 | — | |onAppAbilityCreate| 4.61 | 4.31 | — | |onAppAbilityNewWant| 4.61 | 4.31 | — | |onAppAbilityShare| 4.61 | 4.31 | — | |onAppAbilityWindowStageCreate| 4.61 | 4.31 | — | |requestSystemPermission| 4.61 | 4.31 | — |从矩阵可以看出几个规律主题类 APIgetAppTheme/getOsTheme版本要求最高4.71且依赖鸿蒙系统 5.0.012及以上低版本系统调用前应做能力探测colorWithString要求 5.21是最晚开放的方法大部分生命周期、上下文、权限方法在 4.314.61 区间已开放属于基础设施级别的能力exit()是唯一在 uni-app x 侧标为x的方法跨体系复用uni.exit时需注意环境差异。八、在 UTS 插件中的落地步骤综合文档与仓库实践在 uni-app/uni-app x 项目中编写使用 UTSHarmony 的鸿蒙 UTS 插件推荐按以下流程创建插件目录在项目的uni_modules下新建插件如uni-my-plugin鸿蒙实现放在uni_modules/uni-my-plugin/utssdk/app-harmony/index.utsAndroid/iOS 分别放在app-android/app-ios目录参考 uni-exit、uni-clipboard 的目录结构用条件编译隔离平台代码// #ifdef APP-HARMONY块内使用 UTSHarmony其他平台使用 UTSAndroid/UTSiOS参考 UTSXXX.uts 的写法注册插件 API通过defineSyncApi/defineAsyncApi将内部实现封装为对外 API如 uni-exit 的defineSyncApi包装并同步维护interface.uts类型声明与protocol.uts协议号权限先行涉及敏感能力联系人、剪贴板、生物识别、相机、定位等时先调用UTSHarmony.requestSystemPermission申请权限并在fail回调处理不再询问分支注意生命周期与窗口时序需要getUIAbilityContext()应在onAppAbilityCreate之后需要getCurrentWindow()应在onAppAbilityWindowStageCreate之后核对版本矩阵根据目标 HBuilderX 版本与鸿蒙系统版本对照上文兼容矩阵避免在低版本环境调用高版本 API。九、常见问题与注意事项页面代码中能直接用 UTSHarmony 吗不能。UTSHarmony 面向uni_modules中utssdk目录下的 UTS 插件代码该部分才编译为 ArkTS页面内的脚本仍编译为 JS无法访问这些原生 API。需要先封装为插件 API 再在页面中调用。exit()在 uni-app x 不可用怎么办文档将 uni-app x 的兼容版本标为x说明该环境暂不支持直接调用退出应用在 uni-app x 中如需类似能力应评估替代方案而不能直接透传UTSHarmony.exit()。主题 API 的系统版本门槛getAppTheme/getOsTheme需要 HarmonyOS 系统版本 ≥ 5.0.012且 uni-app x 与 uni-app 插件均要求 HBuilderX 4.71低版本环境需通过条件编译或运行时能力探测保护。权限弹窗与不再询问鸿蒙系统对同一权限的多次拒绝会进入不再询问状态届时requestSystemPermission的fail回调中doNotAskAgain为true应引导用户前往系统设置开启避免请求无效化。路径换算的语义区分项目内文件用convert2AbsFullPath资源文件用getResourcePath二者入参同为项目相对路径但转换的目标存储区域不同混用可能导致原生模块读取失败。生命周期回调注册时机onAppAbilityCreate等监听建议在插件初始化模块顶层或首次调用时尽早注册避免错过冷启动早期的want参数监听是常驻型的无需手动反注册文档中未提供对应的 off 方法。更多 UTS 语言细节UTSHarmony 属于平台增补 API使用前建议先掌握 UTS 语言基础类型、条件编译、与 TS 的差异详见 docs/uts/README.md、数据类型、条件编译、uts 与 ts 的差异鸿蒙插件开发的完整流程另见 docs/plugin/uts-for-harmony.md 与 docs/plugin/uts-plugin.md。十、参考文件索引| 内容 | 仓库路径 | | :- | :- | | UTSHarmony 官方 API 文档 | docs/uts/utsharmony.md | | UTS 语言介绍与编译矩阵 | docs/uts/README.md | | UTS 数据类型 | docs/uts/data-type.md | | UTS 条件编译 | docs/uts/conditional.md | | UTS 与 TS 差异 | docs/uts/uts_diff_ts.md | | 鸿蒙 UTS 插件开发指南 | docs/plugin/uts-for-harmony.md | | UTS 插件通用开发指南 | docs/plugin/uts-plugin.md | | 官方插件退出应用鸿蒙实现透传UTSHarmony.exit | src/uni_modules/uni-exit/utssdk/app-harmony/index.uts | | 官方插件主题setAppTheme/onAppThemeChange/onOsThemeChange | src/uni_modules/uni-theme/utssdk/app-harmony/index.uts | | 官方插件剪贴板权限requestSystemPermission | src/uni_modules/uni-clipboard/utssdk/app-harmony/index.uts | | 官方插件添加联系人requestSystemPermission | src/uni_modules/uni-addPhoneContact/utssdk/app-harmony/index.uts | | 官方插件生物认证权限 失败码映射 | src/uni_modules/uni-authentication/utssdk/app-harmony/index.uts | | 官方插件rpx 换算getWindowStage窗口读取 | src/uni_modules/uni-rpx2px/utssdk/app-harmony/index.uts | | 测试示例onAppAbilityCreategetUIAbilityContext| examples/hello-uts/uni_modules/uts-tests/utssdk/UTSXXX.uts |【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址: https://gitcode.com/gh_mirrors/un/uni-app创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
