探秘鸿蒙 HarmonyOS NEXT：教你如何创建APP桌面快捷方式

本文介绍了如何在HarmonyOS NEXT系统中为APP应用创建快捷方式。

lucky志

1635人浏览 · 2025-05-28 20:02:39

lucky志 · 2025-05-28 20:02:39 发布

概述

同学们，今天咱来聊聊咋在 APP 应用入口创建快捷方式哈～现在好多应用功能越来越复杂，找个常用功能得点好几步，可太麻烦了！这时候咱就可以给常用功能建桌面快捷方式，像扫一扫、车辆位置等这些常用功能，点一下就能直接进功能页面，效率超高！而且还能按自己习惯定制好几个快捷方式，使用起来贼简单～

简单来说，就是为了让大家用 APP 更方便，一键直达想找的功能，那么今天我们就基于HarmonyOS NEXT操作系统，API12以上的版本。来学习一下,如何在APP应用入口创建快捷方式。

实现原理

实现起来其实很简单,我们需要使用shortcuts来配置应用的快捷方式，其标签值为数组，包含四个子标签shortcutId、label、icon、wants。

shortcutId：标识快捷方式的ID，取值为长度不超过63字节的字符串。
label：标识快捷方式的标签信息，即快捷方式对外显示的文字描述信息。取值为长度不超过255字节的字符串，可以是描述性内容，也可以是标识label的资源索引。
icon：标识快捷方式的图标，取值为资源文件的索引。

wants：标识快捷方式内定义的目标wants信息集合，wants中可配置如下参数：

属性名称	含义
bundleName	表示快捷方式的目标包名。
moduleName	表示快捷方式的目标模块名。
abilityName	表示快捷方式的目标组件名。
parameters	表示拉起快捷方式时的自定义数据，仅支持配置字符串类型的数据。其中键值均最大支持1024长度的字符串。

shortcuts配置完成后，还需要在module.json5配置文件中配置 metadata 字段来指定应用的快捷方式配置文件，从而完成快捷方式的基本配置。

注意事项:

通过在module.json5配置文件中配置 metadata 字段的快捷方式是一种在系统中创建的可以快速访问应用程序或特定功能的链接，与卡片的区别在于：快捷方式只允许跳转至某个具体的UIAbility，无法直接跳转至非入口页面，且最多可以配置四个快捷方式。

实现流程

例如给APP添加常用的扫一扫快捷方式需要进行如下步骤：

创建页面并配置页面的路由信息。首先需要创建对应的快捷方式页面，且页面组件需要用@Entry装饰。然后在resources/base/profile下的main_pages.json文件中添加对应快捷方式页面的路由信息。

{
  "src": [
    "pages/Index",
    "pages/GoScan",
    "pages/GoCamera"
  ]
}

在/resources/base/profile/目录下创建名为shortcuts_config.json的文件，并在文件中定义应用快捷方式的相关配置。其中:

shortcutId表示快捷方式的ID、

label表示快捷方式对外显示的文字描述信息、

icon表示快捷方式的图标、

wants中则是快捷方式内定义的目标wants信息集合。

通过wants中的parameters参数来指定拉起快捷方式时的自定义数据。

{
  "shortcuts": [
    {
      "shortcutId": "id_Scan",
      "label": "$string:Go_to_the_Scan",
      "icon": "$media:scan",
      "wants": [
        {
          "bundleName": "com.example.desktopshortcuts",
          "moduleName": "entry",
          "abilityName": "EntryAbility",
          "parameters": {
            "shortCutKey": "ScanPage"
          }
        }
      ]
    },
    {
      "shortcutId": "id_Camera",
      "label": "$string:Go_to_Camera",
      "icon": "$media:camera",
      "wants": [
        {
          "bundleName": "com.example.desktopshortcuts",
          "moduleName": "entry",
          "abilityName": "EntryAbility",
          "parameters": {
            "shortCutKey": "CameraPage"
          }
        }
      ]
    }
  ]
}

在module.json5配置文件中的[abilities]标签下的[metadata]中设置resource属性值为$profile:shortcuts_config，指定应用的快捷方式配置文件，即使用shortcuts_config.json文件中的shortcuts配置。

{
  "module": {
    // ...
    "abilities": [
      {
        "name": "EntryAbility",
        "srcEntry": "./ets/entryability/EntryAbility.ets",
        // ...
        "skills": [
          {
            "entities": [
              "entity.system.home"
            ],
            "actions": [
              "ohos.want.action.home"
            ]
          }
        ],
        "metadata": [
          {
            "name": "ohos.ability.shortcuts", // 配置快捷方式，该值固定为ohos.ability.shortcuts
            "resource": "$profile:shortcuts_config" // 指定shortcuts信息的资源位置
          }
        ]
      }
    ]
  }
}

在EntryAbility.ets文件中定义跳转到指定页面的方法。在步骤2中，通过parameters参数来指定了拉起快捷方式时的自定义数据，如"shortCutKey": “HousePage”。此时，可以通过获取want中的parameters里的shortCutKey来判断用户使用了哪种快捷方式，从而进行对应的页面跳转。如用户使用了“回家”的快捷方式进行导航，则获取到的shortCutKey的值为HousePage。

goToSpecifyPage(want: Want) {
  let shortCutKey = want.parameters?.shortCutKey;


  if (this.uiContext && shortCutKey && shortCutKey === 'ScanPage') {
    let router: Router = this.uiContext.getRouter();
    router.pushUrl({
      url: 'pages/GoScan'
    }).catch((err: BusinessError) => {
      hilog.error(0x0000, 'testTag', `Failed to push url. Code is ${err.code},message is ${err.message}`);
    });
  }
  if (this.uiContext && shortCutKey && shortCutKey === 'CameraPage') {
    let router: Router = this.uiContext.getRouter();
    router.pushUrl({
      url: 'pages/GoCamera'
    }).catch((err: BusinessError) => {
      hilog.error(0x0000, 'testTag', `Failed to push url. Code is ${err.code},message is ${err.message}`);
    });
  }
}

最后，需要在EntryAbility.ets文件中的 onNewWant() / onCreate() 函数中调用步骤4的goToSpecifyPage()方法，并将want作为参数传入，下面以 onNewWant() 函数中调用goToSpecifyPage()方法为例。

onNewWant(want: Want, launchParam: AbilityConstant.LaunchParam): void {
  // Receive the parameters passed by UIAbility from the caller
  this.goToSpecifyPage(want);
  
  hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onNewWant');
}