【HarmonyOS】【进阶】鸿蒙原生实现3DTouch快捷方式原创

走向菜鸟的菜鸟

发布于 2025-3-13 10:29

浏览

0收藏

开发语言：ArkTs
开发工具：DevEco Studio 5.0.0 Release
API版本：API 12

demo演示Gitee:harmony-qrscan.git

【HarmonyOS】【进阶】鸿蒙原生实现3DTouch快捷方式-鸿蒙开发者社区

需求：长按桌面图片显示快捷入口，通过快捷入口快速打开指定页面。

一、新建配置文件

在/resources/base/profile/目录下新建shortcuts_config.json配置文件。
这里配置了扫一扫和乘车码两个快捷入口，单个配置项中label和icon分别是快捷入口显示的文字和图标，其中parameters参数下的3DTouchType字段用于区分快捷入口打开APP时点击的业务类型，字段名可自定义。

{
  "shortcuts": [
    {
      "shortcutId": "id_scan",
      "label": "$string:3DTouch_SCAN",
      "icon": "$media:foreground",
      "wants": [
        {
          "bundleName": "com.example.qrcodescan",
          "abilityName": "EntryAbility",
          "moduleName": "entry",
          "parameters": {
            "3DTouchType": "scan" 
          }
        }
      ]
    },
    {
      "shortcutId": "id_ride",
      "label": "$string:3DTouch_RIDE",
      "icon": "$media:foreground",
      "wants": [
        {
          "bundleName": "com.example.qrcodescan",
          "abilityName": "EntryAbility",
          "moduleName": "entry",
          "parameters": {
            "3DTouchType": "ride"
          }
        }
      ]
    }
  ]
}
1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
21.
22.
23.
24.
25.
26.
27.
28.
29.
30.
31.
32.
33.
34.

二、生效配置文件

在src/main/module.json5文件中引用配置文件。
在module.json5配置文件的abilities标签中，针对需要添加快捷方式的UIAbility进行配置metadata标签，使shortcut配置文件对该UIAbility生效。

{
  "module": {
    //...
    "abilities": [
      {
        "name": "EntryAbility",
        "srcEntry": "./ets/entryability/EntryAbility.ets",
        //...
        "skills": [
          {
            "entities": [
              "entity.system.home"
            ],
            "actions": [
              "action.system.home"
            ]
          }
        ],
        "metadata": [
          {
            "name": "ohos.ability.shortcuts",
            "resource": "$profile:shortcuts_config"
          }
        ]
      }
    ]
  }
}
1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
21.
22.
23.
24.
25.
26.
27.
28.

三、拦截快捷方式跳转

1、热启动跳转（APP退到后台）

在EntryAbility.ets文件中实现onNewWant()方法，在方法内拦截快捷方式的类型进行业务跳转。

onNewWant(want: Want, launchParam: AbilityConstant.LaunchParam): void {
  // 点击了快捷入口（热启动）
  this.shortcutsPushToPage(want);
}
1.
2.
3.
4.

2、冷启动跳转（APP进程被杀掉）

在EntryAbility.ets文件的onCreate()方法内记录want对象，然后在onWindowStageCreate()方法中的windowStage.loadContent()加载内容后处理快捷方式的类型进行业务跳转。

// 快捷入口want
private shortcutsWant?: Want;

onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
  // 冷启动 点击了快捷入口，记录下want对象
  if (want) {
    this.shortcutsWant = want;
  }
}


onWindowStageCreate(windowStage: window.WindowStage): void {
  // Main window is created, set main page for this ability
  hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onWindowStageCreate');

  windowStage.loadContent('pages/Index', (err) => {
    if (err.code) {
      hilog.error(0x0000, 'testTag', 'Failed to load the content. Cause: %{public}s', JSON.stringify(err) ?? '');
      return;
    }
    hilog.info(0x0000, 'testTag', 'Succeeded in loading the content.');
    // 冷启动 点击了快捷入口，在加载内容后执行跳转页面，这里仅简单实现跳转，真实项目不建议这么写
    // 此处做延迟0.5s执行，是为了显示首页后再跳转，否则会先跳转，再显示首页
    // 真实项目中可将跳转放到pages/Index页面显示后执行，这里为了方便简单处理
    setTimeout(() => {
      this.shortcutsPushToPage(this.shortcutsWant);
    }, 500)
  });
}
1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
21.
22.
23.
24.
25.
26.
27.
28.
29.

3、处理跳转

/**
 * 快捷入口跳转页面
 * @param want
 */
shortcutsPushToPage(want?: Want) {
  if (want) {
    let wantParameters = want['parameters'] as object;
    if (wantParameters) {
      let touchType: string = wantParameters['3DTouchType'];
      if (touchType === "scan") {
        // 扫一扫
        router.pushUrl({url: "pages/HMQRCodeScanPage"});
      } else if (touchType === "ride") {
        // 乘车码
        router.pushUrl({url: "pages/HMQRScanResultPage", params: {"result": "乘车码"}});
      }
    }
  }
  // 跳转后清除记录
  this.shortcutsWant = undefined;
}
1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
21.