【HarmonyOS 5】桌面快捷方式功能實現詳解

##鴻蒙開發能力 ##HarmonyOS SDK應用服務##鴻蒙金融類應用 （金融理財#

一、前言

在移動應用開發中，如何讓用戶快速觸達核心功能，是目前很常見的功能之一。

鴻蒙系統提供的**桌面快捷方式（Shortcuts）**功能，允許開發者為應用內常用功能創建直達入口，用戶通過長按應用圖標即可快速啟動特定功能，大幅減少操作層級。

本文將結合地圖導航場景，詳細解析鴻蒙快捷方式的實現原理與開發流程。結合華為官方開源示例 DesktopShortcut 展開，該示例基于HarmonyOS 5.0實現，完整演示了地圖導航場景的快捷方式開發流程。

二、需求分析與示例工程介紹

以地圖應用為例，用戶日常高頻使用“回家”“去公司”等導航功能。傳統流程需先打開應用、搜索目的地、再啟動導航。通過快捷方式，可實現：

1. 長按應用圖標 ，在快捷方式列表中直接點擊“回家”或“去公司”；
2. 拖動快捷方式到桌面 ，通過獨立圖標一鍵啟動導航。
   

工程目錄介紹

├── entry/src/main/ets                  
│  ├── entryability                         
│  │  └── EntryAbility.ets                  // 核心邏輯：處理快捷方式參數并跳轉頁面
│  └── pages                                
│     ├── GoCompany.ets                     // 公司導航頁面（@Entry裝飾）
│     ├── GoHouse.ets                       // 回家導航頁面（@Entry裝飾）
│     └── Index.ets                         // 應用首頁
├── entry/src/main/resources                
│  └── base/profile                         
│     └── shortcuts_config.json             // 快捷方式元數據配置
└── module.json5                             // 模塊配置文件，關聯快捷方式

三、快捷方式功能實現步驟

1、 核心配置文件

（1）shortcuts_config.json ：定義快捷方式的元數據，包括ID、名稱、圖標及目標跳轉信息。

{
  "shortcuts": [
    {
      "shortcutId": "id_go_company",
      "label": "$string:go_company",        // 對應resources/base/element/string.json中的字符串資源
      "icon": "$media:icon_company",        // 對應resources/base/media目錄下的圖標文件
      "wants": [
        {
          "bundleName": "com.example.desktopshortcut", // 應用包名（需與module.json5一致）
          "moduleName": "entry",                        // 模塊名（固定為entry）
          "abilityName": "EntryAbility",               // 目標Ability（入口Ability）
          "parameters": { "page": "GoCompany" }         // 自定義參數：標識目標頁面
        }
      ]
    },
    {
      "shortcutId": "id_go_house",
      "label": "$string:go_home",
      "icon": "$media:icon_home",
      "wants": [
        {
          "bundleName": "com.example.desktopshortcut",
          "moduleName": "entry",
          "abilityName": "EntryAbility",
          "parameters": { "page": "GoHouse" } //  `parameters`鍵名可自定義（示例中使用`page`而非前文的`shortCutKey`），需與代碼邏輯保持一致。
        }
      ]
    }
  ]
}

（2）module.json5 ：聲明快捷方式配置文件的引用，關聯至應用模塊。

{
  "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" // 引用profile目錄下的配置文件
          }
        ]
      }
    ]
  }
}

（3）關鍵字段說明

2、快捷入口跳轉邏輯

import router from '@ohos.router';

export default class EntryAbility extends Ability {
  private context: UIAbilityContext | undefined;

  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) {
    super.onCreate(want, launchParam);
    this.context = this.getContext();
    // 首次啟動時加載首頁
    router.pushUrl({
      url: 'pages/Index',
      context: this.context
    });
  }

  onNewWant(want: Want, launchParam: AbilityConstant.LaunchParam) {
    const page = want.parameters?.page; // 提取快捷方式傳遞的參數
    if (page && this.context) {
      router.pushUrl({
        url: `pages/${page}`, // 動態拼接頁面路徑
        context: this.context
      });
    }
  }
}

注意

1. 快捷方式數量 ：僅支持跳轉至UIAbility入口頁面，最多配置4個。
2. 參數校驗 ：
   在onNewWant中增加參數非空校驗，避免因快捷方式參數缺失導致應用崩潰：

if (!page || !this.context) {
  hilog.error(0x0000, 'Shortcut', 'Invalid parameters or context');
  return;
}

1. 卡片 ：可展示動態內容，支持跳轉至非入口頁面。

審核編輯 黃宇