【HarmonyOS 5】桌面快捷方式功能實(shí)現(xiàn)詳解

##鴻蒙開(kāi)發(fā)能力 ##HarmonyOS SDK應(yīng)用服務(wù)##鴻蒙金融類(lèi)應(yīng)用 （金融理財(cái)#

一、前言

在移動(dòng)應(yīng)用開(kāi)發(fā)中，如何讓用戶(hù)快速觸達(dá)核心功能，是目前很常見(jiàn)的功能之一。

鴻蒙系統(tǒng)提供的**桌面快捷方式（Shortcuts）**功能，允許開(kāi)發(fā)者為應(yīng)用內(nèi)常用功能創(chuàng)建直達(dá)入口，用戶(hù)通過(guò)長(zhǎng)按應(yīng)用圖標(biāo)即可快速啟動(dòng)特定功能，大幅減少操作層級(jí)。

本文將結(jié)合地圖導(dǎo)航場(chǎng)景，詳細(xì)解析鴻蒙快捷方式的實(shí)現(xiàn)原理與開(kāi)發(fā)流程。結(jié)合華為官方開(kāi)源示例 DesktopShortcut 展開(kāi)，該示例基于HarmonyOS 5.0實(shí)現(xiàn)，完整演示了地圖導(dǎo)航場(chǎng)景的快捷方式開(kāi)發(fā)流程。

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

以地圖應(yīng)用為例，用戶(hù)日常高頻使用“回家”“去公司”等導(dǎo)航功能。傳統(tǒng)流程需先打開(kāi)應(yīng)用、搜索目的地、再啟動(dòng)導(dǎo)航。通過(guò)快捷方式，可實(shí)現(xiàn)：

1. 長(zhǎng)按應(yīng)用圖標(biāo) ，在快捷方式列表中直接點(diǎn)擊“回家”或“去公司”；
2. 拖動(dòng)快捷方式到桌面 ，通過(guò)獨(dú)立圖標(biāo)一鍵啟動(dòng)導(dǎo)航。
   

工程目錄介紹

├── entry/src/main/ets                  
│  ├── entryability                         
│  │  └── EntryAbility.ets                  // 核心邏輯：處理快捷方式參數(shù)并跳轉(zhuǎn)頁(yè)面
│  └── pages                                
│     ├── GoCompany.ets                     // 公司導(dǎo)航頁(yè)面（@Entry裝飾）
│     ├── GoHouse.ets                       // 回家導(dǎo)航頁(yè)面（@Entry裝飾）
│     └── Index.ets                         // 應(yīng)用首頁(yè)
├── entry/src/main/resources                
│  └── base/profile                         
│     └── shortcuts_config.json             // 快捷方式元數(shù)據(jù)配置
└── module.json5                             // 模塊配置文件，關(guān)聯(lián)快捷方式

三、快捷方式功能實(shí)現(xiàn)步驟

1、 核心配置文件

（1）shortcuts_config.json ：定義快捷方式的元數(shù)據(jù)，包括ID、名稱(chēng)、圖標(biāo)及目標(biāo)跳轉(zhuǎn)信息。

{
  "shortcuts": [
    {
      "shortcutId": "id_go_company",
      "label": "$string:go_company",        // 對(duì)應(yīng)resources/base/element/string.json中的字符串資源
      "icon": "$media:icon_company",        // 對(duì)應(yīng)resources/base/media目錄下的圖標(biāo)文件
      "wants": [
        {
          "bundleName": "com.example.desktopshortcut", // 應(yīng)用包名（需與module.json5一致）
          "moduleName": "entry",                        // 模塊名（固定為entry）
          "abilityName": "EntryAbility",               // 目標(biāo)Ability（入口Ability）
          "parameters": { "page": "GoCompany" }         // 自定義參數(shù)：標(biāo)識(shí)目標(biāo)頁(yè)面
        }
      ]
    },
    {
      "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 ：聲明快捷方式配置文件的引用，關(guān)聯(lián)至應(yīng)用模塊。

{
  "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）關(guān)鍵字段說(shuō)明

2、快捷入口跳轉(zhuǎn)邏輯

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();
    // 首次啟動(dòng)時(shí)加載首頁(yè)
    router.pushUrl({
      url: 'pages/Index',
      context: this.context
    });
  }

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

注意

1. 快捷方式數(shù)量 ：僅支持跳轉(zhuǎn)至UIAbility入口頁(yè)面，最多配置4個(gè)。
2. 參數(shù)校驗(yàn) ：
   在onNewWant中增加參數(shù)非空校驗(yàn)，避免因快捷方式參數(shù)缺失導(dǎo)致應(yīng)用崩潰：

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

1. 卡片 ：可展示動(dòng)態(tài)內(nèi)容，支持跳轉(zhuǎn)至非入口頁(yè)面。

審核編輯 黃宇