当前位置：首页 > news >正文

HarmonyOS —— UIAbility 页面跳转总结

news 2025/12/16 1:38:09

HarmonyOS —— UIAbility 页面跳转总结

Author：Gorit

Date：2023年12月27日

一、系统环境

HarmonOS API9
SDK 3.1.0
Stage 模型

二、应用内跳转

在应用内之前实现不同 page 的跳转，我们使用 router 即可，页面跳转主要支持如下两个方法:

router.pushUrl()：目标页不会替换当前页，而是压入页面栈。这样可以保留当前页的状态，并且可以通过返回键或者调用router.back()方法返回到当前页。
router.replaceUrl()：目标页会替换当前页，并销毁当前页。这样可以释放当前页的资源，并且无法返回到当前页。

router 跳转模式

Standard：标准实例模式，也是默认情况下的实例模式。每次调用该方法都会新建一个目标页，并压入栈顶。
Single：单实例模式。即如果目标页的url在页面栈中已经存在同url页面，则离栈顶最近的同url页面会被移动到栈顶，并重新加载；如果目标页的url在页面栈中不存在同url页面，则按照标准模式跳转。

具体的使用案例及应用场景可以查看官方文档，我这里就不做多余赘述

PS：在卡 ArkTS 卡片中可采用 postCardAction 实现的跳转

三、UIAbility 之间跳转

原理：基于 startAbility 实现页面跳转，主要应用场景如下

打开当前 App
选择多个 App，选择打开某一个 App
打开指定 App

3.1 了解什么是 UIAbility？

概述：

UIAbility组件是一种包含UI界面的应用组件，主要用于和用户交互。

UIAbility组件是系统调度的基本单元，为应用提供绘制界面的窗口；一个UIAbility组件中可以通过多个页面来实现一个功能模块。每一个UIAbility组件实例，都对应于一个最近任务列表中的任务。

更多的 UIAbility 的信息需要大家自行查阅文档~，比如生命周期，启动方式等等

3.2 如何启动其它应用 UIAbility？

获取 UIAbility 上下文信息
通过文档得知，我们可以在 EntryAbility 中直接获取当前实例的上下文，也可以自己在任意 Page 中去获取 UIAbility 的实例信息
定义 Want 参数配置，这里东西有很多，我们进需要关注两个配置参数即可（bundleName 和 abilityName）
调用 context.startAbility(want).then(...) 实现调用其他 UIAbility

转换成代码如下:

import common from '@ohos.app.ability.common'// 业务代码 ...
{Button().onClick(() => {startSettingsMainAbilityExplicit()})}function startSettingsMainAbilityExplicit() {console.log("begin to navigate");let context = getContext(this) as unknown as common.UIAbilityContext;let want = {deviceId: "",bundleName: 'com.examples', // com.ohos.settingsabilityName: 'EntryAbility', // com.ohos.settings};// previewer 无法调用context.startAbility(want).then((res) => {console.log(res + "");}).catch((e) => {console.log(e.code, e.message);})}

PS：如果你是模拟器用户，需要记得在被跳转的 UIAbility 中 `module.json5` 下 `exported: true` 下面添加一个配置 `visible: true`，不然得话程序会崩溃，暂时还没找到其他替代方案。真机需要使用后才清楚

完整的文档可以参考：UIAbility组件相互交互

这里有很多跳转方式，我简单总结下

一个应用内有两个 UIAbility，可以采用此方法启动应用内的 UIAbility
同上，并获取返回结果
启动其它应用的 UIAbility，这里又分为 显示 Want 启动 和 隐示 Want 启动，我们前面第二点提到的就是 显示 Want 启动，可以理解为精准匹配某一个 APP
同上，可以修改 Want 参数和 module.json5 参数，进行模糊匹配，选择多个 UIAbility 可以打开
Call 实现 UIAbility 交互，但是仅支持 系统应用

3.3 跳转系统应用

系统应用——拉起系统相册
拉起系统设置及二级页面


let want  = {"deviceId": "","bundleName": "","abilityName": "","uri": "","flags":wantConstant.Flags.FLAG_AUTH_READ_URI_PERMISSION,"action": "android.settings.SETTINGS","parameters": {},"entities": []
}
this.context.startAbility(want, (err) => {if (err.code) {// 处理业务逻辑错误console.log('startAbility failed, error.code: ' + JSON.stringify(err.code) +' error.message: ' + JSON.stringify(err.message));return;}
// 正常逻辑
})

系统设置 action 配置

系统设置常见子页面（在当前 HarmonOS 3.1 版本，4.0 版本可以使用，NEXT 版本是否支持有待考证）
Action名称作用

android.settings.SETTINGS    跳转到设置界面
android.settings.ACCESSIBILITY_SETTINGS    跳转系统的辅助功能界面
android.settings.ADD_ACCOUNT_SETTINGS    显示添加帐户创建一个新的帐户屏幕。【测试跳转到微信登录界面】
android.settings.AIRPLANE_MODE_SETTINGS    飞行模式，无线网和网络设置界面
android.settings.WIRELESS_SETTINGS    飞行模式，无线网和网络设置界面
android.settings.APN_SETTINGS    跳转 APN设置界面
android.settings.APPLICATION_DETAILS_SETTINGS    根据包名跳转到系统自带的应用程序信息界面
android.settings.APPLICATION_DEVELOPMENT_SETTINGS    跳转开发人员选项界面
android.settings.APPLICATION_SETTINGS    跳转应用程序列表界面
android.settings.MANAGE_ALL_APPLICATIONS_SETTINGS    跳转到应用程序界面【所有的】
android.settings.MANAGE_APPLICATIONS_SETTINGS    跳转 应用程序列表界面【已安装的】
android.settings.BLUETOOTH_SETTINGS    跳转系统的蓝牙设置界面
android.settings.DATA_ROAMING_SETTINGS    跳转到移动网络设置界面
android.settings.DATE_SETTINGS    跳转日期时间设置界面
android.settings.DEVICE_INFO_SETTINGS    跳转手机状态界面
android.settings.DISPLAY_SETTINGS    跳转手机显示界面
android.settings.INPUT_METHOD_SETTINGS    跳转语言和输入设备
android.settings.INPUT_METHOD_SUBTYPE_SETTINGS    【API 11及以上】 // 跳转 语言选择界面 【多国语言选择】
android.settings.INTERNAL_STORAGE_SETTINGS    跳转存储设置界面【内部存储】
android.settings.MEMORY_CARD_SETTINGS    跳转 存储设置 【记忆卡存储】
android.settings.LOCALE_SETTINGS    跳转语言选择界面【仅有English 和 中文两种选择】
android.settings.LOCATION_SOURCE_SETTINGS    跳转位置服务界面【管理已安装的应用程序。】
android.settings.NETWORK_OPERATOR_SETTINGS    跳转到 显示设置选择网络运营商。
android.settings.NFCSHARING_SETTINGS    显示NFC共享设置。 【API 14及以上】
android.settings.NFC_SETTINGS    显示NFC设置。这显示了用户界面,允许NFC打开或关闭。 【API 16及以上】
android.settings.PRIVACY_SETTINGS    跳转到备份和重置界面
android.settings.QUICK_LAUNCH_SETTINGS    跳转快速启动设置界面
android.search.action.SEARCH_SETTINGS    跳转到 搜索设置界面
android.settings.SECURITY_SETTINGS    跳转到安全设置界面
android.settings.SOUND_SETTINGS    跳转到声音设置界面
android.settings.SYNC_SETTINGS    跳转账户同步界面
android.settings.USER_DICTIONARY_SETTINGS    跳转用户字典界面
android.settings.WIFI_IP_SETTINGS    跳转到IP设定界面
android.settings.WIFI_SETTINGS    跳转Wifi列表设置

四、跨设备跳转【TODO】

经过尝试，两个模拟器之间貌似不支持，会提示如下错误

2-27 10:19:19.724 16971-193/com.examples.demo I 0FEFE/JsApp: startAbility failed, error.code: 16000009 error.message: "Cannot operate in wukong mode."

五、相关文档

Stage模型应用组件 —— 配置
应用上下文Context
codelabs 下载通知案例 —— want 应用
其它 HarmonOS 跳转案例