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

一、前言

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

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

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

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

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

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

json 复制代码

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

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

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

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

示例配置：

json 复制代码

{
  "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 配置，指定快捷方式配置文件路径，让系统识别快捷方式：

json 复制代码

{
  "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，判断用户点击的快捷方式，进而跳转到对应页面：

typescript 复制代码

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 参数，确保页面能获取到跳转信息：

typescript 复制代码

// 冷启动时保存参数
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 参数，调用跳转方法完成快捷方式响应：

typescript 复制代码

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 工具类，封装动态添加快捷方式的逻辑，包含权限校验、重复判断和创建请求：

typescript 复制代码

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}`);
    }
  }
}

使用方式

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

typescript 复制代码

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

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

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

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

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