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

【HarmonyOS 6】静态和动态添加应用快捷方式详解

news 2025/11/15 11:58:48

【HarmonyOS 6】静态和动态添加应用快捷方式详解

一、前言

在功能日益复杂的应用中，用户往往需要多步操作才能找到常用功能。而应用快捷方式能让用户一键直达核心功能，既提升操作效率，也能增强用户对应用的粘性。

本文结合实际开发场景，详细分享 HarmonyOS 中两种快捷方式的实现方法，包括静态快捷方式配置和应用内动态添加，全程基于单 HAP 包场景（多 HAP 包配置逻辑一致）。

二、静态快捷方式：基础配置与快速跳转

静态快捷方式是通过配置文件预先定义的快捷方式，用户长按应用图标即可看到。例如“回家导航”“新建便签”这类高频固定功能。效果如下：
在这里插入图片描述

1、创建目标页面并配置路由

首先创建快捷方式对应的功能页面（如“回家”“去公司”页面），页面需用 @Entry 装饰。然后在 resources/base/profile/main_pages.json 中添加页面路由，确保应用能识别页面路径：

{"src": ["pages/Index",  // 应用主页面"pages/GoHouse", // 回家导航页面"pages/GoCompany" // 去公司导航页面]
}

2、编写快捷方式配置文件

在 resources/base/profile/ 目录下新建 shortcuts_config.json 文件，定义快捷方式的 ID、显示文本、图标和跳转目标。每个快捷方式需包含以下核心参数：

shortcutId：唯一标识，不超过 63 字节
label：显示文本（支持字符串或资源索引）
icon：图标资源索引
wants：跳转配置（包名、模块名、组件名、自定义参数）

示例配置：

{"shortcuts": [{"shortcutId": "id_company","label": "$string:Go_to_the_Company","icon": "$media:company","wants": [{"bundleName": "com.example.desktopshortcuts","moduleName": "entry","abilityName": "EntryAbility","parameters": {"shortCutKey": "CompanyPage"}}]},{"shortcutId": "id_house","label": "$string:Go_to_House","icon": "$media:house","wants": [{"bundleName": "com.example.desktopshortcuts","moduleName": "entry","abilityName": "EntryAbility","parameters": {"shortCutKey": "HousePage"}}]}]
}

3、在 module.json5 中关联配置

在 module.json5 的 abilities 标签下添加 metadata 配置，指定快捷方式配置文件路径，让系统识别快捷方式：

{"module": {"abilities": [{"name": "EntryAbility","srcEntry": "./ets/entryability/EntryAbility.ets","skills": [{"entities": ["entity.system.home"],"actions": ["ohos.want.action.home"]}],"metadata": [{"name": "ohos.ability.shortcuts","resource": "$profile:shortcuts_config"}]}]}
}

4、实现页面跳转逻辑

在主页面（Index.ets）中定义跳转方法，通过读取 wants 中的自定义参数 shortCutKey，判断用户点击的快捷方式，进而跳转到对应页面：

goToSpecifyPage(want?: Want) {let shortCutKey = want?.parameters?.shortCutKey;if (shortCutKey === 'CompanyPage') {this.getUIContext().getRouter().pushUrl({ url: 'pages/GoCompany' }).catch((err: BusinessError) => {hilog.error(0x0000, 'testTag', `跳转失败：${err.code}, ${err.message}`);});}if (shortCutKey === 'HousePage') {this.getUIContext().getRouter().pushUrl({ url: 'pages/GoHouse' }).catch((err: BusinessError) => {hilog.error(0x0000, 'testTag', `跳转失败：${err.code}, ${err.message}`);});}
}

5、保存并传递 Want 参数

快捷方式跳转分为冷启动和热启动，需在 EntryAbility.ets 中通过 AppStorage 保存 want 参数，确保页面能获取到跳转信息：

// 冷启动时保存参数
onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {this.context.getApplicationContext().setColorMode(ConfigurationConstant.ColorMode.COLOR_MODE_NOT_SET);if (want?.parameters?.shortCutKey) {AppStorage.setOrCreate('want', want);}
}// 热启动时更新参数
onNewWant(want: Want, launchParam: AbilityConstant.LaunchParam): void {if (want?.parameters?.shortCutKey) {AppStorage.setOrCreate('want', want);}
}

6、页面显示时执行跳转

在主页面的 onPageShow 方法中，读取 AppStorage 中保存的 want 参数，调用跳转方法完成快捷方式响应：

onPageShow(): void {if (AppStorage.has('want')) {let want: Want | undefined = AppStorage.get('want');if (want) {this.goToSpecifyPage(want);AppStorage.delete('want'); // 跳转后清除参数，避免重复触发}}
}

具体跳转的处理，通过want中的参数，开发者可以根据自己业务习惯进行跳转处理，以上处理为参考。

注意事项

（1）静态快捷方式最多支持配置 4 个，仅能跳转至 UIAbility 入口页面，无法直接跳转到非入口页面。
（2）多 HAP 包场景无需额外配置，所有操作均在 entry 文件夹下完成。

二、应用内动态添加快捷方式

除了预先配置的静态快捷方式，还可以在应用内通过代码动态添加快捷方式（如用户点击“添加到桌面”按钮时创建），灵活性更高。

核心实现代码

创建 ShortcutsUtils 工具类，封装动态添加快捷方式的逻辑，包含权限校验、重复判断和创建请求：

import { hilog } from "@kit.PerformanceAnalysisKit";
import { BusinessError } from "@kit.BasicServicesKit";
import { productViewManager } from "@kit.StoreKit";
import { common, Want } from "@kit.AbilityKit";
import promptAction from '@ohos.promptAction';export class ShortcutsUtils {/*** 点击按钮添加快捷方式*/static addShortcuts() {const uiContext = getContext() as common.UIAbilityContext;const shortcutId = "id_test1"; // 需与 shortcuts_config.json 中定义的一致const labelResName = "shortcut"; // 对应 label 的资源索引名称const iconResName = "aa_icon"; // 对应 icon 的资源索引名称const want: Want = {bundleName: "com.example.appgallery.kit.demo",moduleName: "entry",abilityName: "EntryAbility",parameters: {testKey: "testValue" // 自定义参数}};try {// 校验快捷方式是否可添加（是否已存在、是否有权限）productViewManager.checkPinShortcutPermitted(uiContext, shortcutId, want, labelResName, iconResName).then((result) => {hilog.info(0x0001, 'addShortcuts', `校验成功：${JSON.stringify(result)}`);const tid = result.tid;// 发起添加快捷方式请求productViewManager.requestNewPinShortcut(uiContext, tid).then(() => {hilog.info(0x0001, 'addShortcuts', "快捷方式添加成功！");}).catch((error: BusinessError) => {hilog.error(0x0001, 'addShortcuts', `快捷方式添加失败：${error.code}, ${error.message}`);});}).catch((error: BusinessError) => {hilog.error(0x0001, 'addShortcuts', `err：${error.code}, ${error.message}`);// 错误码 1006620003 表示快捷方式已存在if (error.code === 1006620003) {promptAction.showToast({ message: '桌面已存在此快捷方式！' });}});} catch (err) {hilog.error(0x0001, 'TAG', `catch err：${err.code}, ${err.message}`);}}
}

使用方式

在应用页面的按钮点击事件中调用工具类方法，即可触发快捷方式添加流程：

// 示例：按钮点击事件
Button('添加测试快捷方式').onClick(() => {ShortcutsUtils.addShortcuts();})

productViewManager允许应用添加快捷方式的数量为两个。这是鸿蒙官方的设计如此。

三、两种快捷方式的区别与适用场景

类型	配置方式	灵活性	适用场景
静态快捷方式	配置文件定义	较低（固定功能）	高频固定功能，如导航、新建、快速拍照
动态快捷方式	代码动态添加	较高（用户触发）	个性化功能，如用户自定义收藏、临时高频功能

查看全文

http://www.dtcms.com/a/610959.html