【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、显示文本、图标和跳转目标。每个快捷方式需包含以下核心参数：
示例配置：
{ "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 允许应用添加快捷方式的数量为两个。这是鸿蒙官方的设计如此。
三、两种快捷方式的区别与适用场景
评论