HarmonyOS：创建应用静态快捷方式

一、前言

静态快捷方式是一种在系统中创建的可以快速访问应用程序或特定功能的链接。它通常可以在长按应用图标，以图标和相应的文字出现在应用图标的上方，用户可以迅速启动对应应用程序的组件。使用快捷方式，可以提高效率，节省了查找和打开对应的组件时间；也可以实现个性化定制的需求，创建多个快捷方式，以满足个性化的工作流程和操作偏好。应用配置静态快捷方式，在桌面上展示的效果如下图：

安装该应用后，在桌面上长按该应用图标，在应用的图标上方会出现开发者配置的快捷方式（“创建应用静态快捷方式详情”和“分享好友”），点击对应的标签，即可拉起对应的组件。

二、shortcuts标签

shortcuts标识应用的快捷方式信息。标签值为数组，包含四个子标签shortcutId、label、icon、wants。

metadata中指定shortcut信息，其中：

name：指定shortcuts的名称，使用ohos.ability.shortcuts作为shortcuts信息的标识。
resource：指定shortcuts信息的资源位置。

shortcuts标签说明

属性名称	含义	类型	是否可缺省
shortcutId	标识快捷方式的ID，取值为长度不超过63字节的字符串。不支持通过资源索引的方式（$string）配置该字段。	字符串	该标签不可缺省。
label	标识快捷方式的标签信息，即快捷方式对外显示的文字描述信息。取值为长度不超过255字节的字符串，可以是描述性内容，也可以是标识label的资源索引。	字符串	该标签可缺省，缺省值为空。
icon	标识快捷方式的图标，取值为资源文件的索引。	字符串	该标签可缺省，缺省值为空。
wants	标识快捷方式内定义的目标wants信息集合，在调用launcherBundleManager的startShortcut接口时，会拉起wants标签里的第一个目标组件，推荐只配置一个wants元素。	对象	该标签可缺省，缺省为空。

三、配置方法

2.1 配置快捷方式的配置文件。

开发者若要配置静态快捷方式，可以在某个模块的/resources/base/profile/目录下配置快捷方式的配置文件，如shortcuts_config.json。

{
  "shortcuts": [
    {
      "shortcutId": "id_test1",  // 标识快捷方式，在应用有多个快捷方式时，该字段可作为快捷方式的唯一标识符
      "label": "$string:share",  // 标识该快捷方式对外显示的文字
      "icon": "$media:share_icon",  // 标识该快捷方式对外显示的图片
      "wants": [
        {
          "bundleName": "com.ohos.hello",   // 对应该快捷方式对应拉起组件的包名
          "moduleName": "entry",    // 对应该快捷方式对应拉起组件的模块名
          "abilityName": "EntryAbility",   // 对应该快捷方式对应拉起组件的组件名
          "parameters": {
            "testKey": "testValue"   // 表示拉起快捷方式时的自定义数据
          }
        }
      ]
    }
  ]
}

示例图

2.2 在应用module.json5文件中配置metadata指向快捷方式的配置文件。

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

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

示例图

四、示例

效果图

示例代码

shortcuts_config.json

{
  "shortcuts": [
    {
      "shortcutId": "1",
      "label": "$string:create_short_cut_detail",
      "icon": "$media:icon_create_shortcut",
      "wants": [
        {
          "bundleName": "com.example.learnharmonyos",
          "moduleName": "entry",
          "abilityName": "ShortcutsEntryAbility",
          "parameters": {
            "pageType": "1"
          }
        }
      ]
    },
    {
      "shortcutId": "2",
      "label": "$string:share_friend",
      "icon": "$media:icon_share",
      "wants": [
        {
          "bundleName": "com.example.learnharmonyos",
          "moduleName": "entry",
          "abilityName": "ShortcutsEntryAbility",
          "parameters": {
            "pageType": "2"
          }
        }
      ]
    }
  ]
}

module.json5

 "abilities": [
      {
        "name": "EntryAbility",
        "srcEntry": "./ets/entryability/EntryAbility.ets",
        "description": "$string:EntryAbility_desc",
        "icon": "$media:layered_image",
        "label": "$string:EntryAbility_label",
        "startWindowIcon": "$media:startIcon",
        "startWindowBackground": "$color:start_window_background",
        "exported": true,
        "skills": [
          {
            "entities": [
              "entity.system.home"
            ],
            "actions": [
              "action.system.home"
            ]
          }
        ],
        "metadata": [
          {
            // 配置快捷方式，该值固定为ohos.ability.shortcuts
            "name": "ohos.ability.shortcuts",
            // 指定shortcuts信息的资源位置
            "resource": "$profile:shortcuts_config"
          }
        ]
      }
  ]

BackToHomeComponent.ets

import { common, Want } from '@kit.AbilityKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { BusinessError } from '@kit.BasicServicesKit';

const TAG: string = '[BackToHomeComponent]';
const DOMAIN_NUMBER: number = 0xFF00;


@Component
export struct BackToHomeComponent {
  pageName: string = ""

  build() {
    Button('回到首页')
      .fontColor($r('app.color.c_black'))
      .fontWeight(FontWeight.Medium)
      .fontSize(20)
      .padding(10)
      .onClick(() => {
        let context: common.UIAbilityContext = getContext(this) as common.UIAbilityContext; // UIAbilityContext
        // 在FuncAbility中通过调用terminateSelf()方法实现。
        // context为需要停止的UIAbility实例的AbilityContext
        let wantInfo: Want = {
          deviceId: '', // deviceId为空表示本设备
          bundleName: 'com.example.learnharmonyos',
          moduleName: 'entry', // moduleName非必选
          abilityName: 'EntryAbility',
          parameters: {
            // 自定义信息
            info: this.pageName
          },
        }
        context.startAbility(wantInfo).then(() => {
          hilog.info(DOMAIN_NUMBER, TAG, 'startAbility EntryAbility 首页 success.');
        }).catch((error: BusinessError) => {
          hilog.error(DOMAIN_NUMBER, TAG, 'startAbility EntryAbility 首页 failed.');
        })

        context.terminateSelf((err) => {
          if (err.code) {
            hilog.error(DOMAIN_NUMBER, TAG,
              `Failed to terminate self. Code is ${err.code}, message is ${err.message}`);
            return;
          }
        });
      })
  }
}

CreateShortCutInfo.ets

import { webview } from '@kit.ArkWeb'
import { BackToHomeComponent } from './BackToHomeComponent'

@Entry
@Component
struct CreateShortCutInfo {
  private webviewController: webview.WebviewController = new webview.WebviewController();
  private url: string =
    'https://developer.huawei.com/consumer/cn/doc/harmonyos-guides-V5/typical-scenario-configuration-V5'

  build() {
    Column({ space: 10 }) {
      BackToHomeComponent({ pageName: "CreateShortCutInfo" })
      Web({ src: this.url, controller: this.webviewController })
    }
    .height('100%')
    .width('100%')
  }
}

ShortCutShare.ets


import { BackToHomeComponent } from './BackToHomeComponent'

@Entry
@Component
struct ShortCutShare {
  @State message: string = '分享成功';

  build() {
    Column({ space: 10 }) {
      BackToHomeComponent({ pageName: "ShortCutShare" })

      Text(this.message)
        .fontSize(10)
        .fontWeight(FontWeight.Bold)
        .margin({ top: 20 })
    }
    .width('100%')
    .height('100%')
  }
}

ShortcutsEntryAbility.ets

import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { window } from '@kit.ArkUI';

export default class ShortcutsEntryAbility extends UIAbility {
  shortcutsEntryAbilityWant: Want | undefined = undefined

  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onCreate');
    this.shortcutsEntryAbilityWant = want;
  }

  onDestroy(): void {
    hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onDestroy');
  }

  onWindowStageCreate(windowStage: window.WindowStage): void {
    // Main window is created, set main page for this ability
    hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onWindowStageCreate');
    let router = 'pages/shortcuts/CreateShortCutInfo'
    if (this.shortcutsEntryAbilityWant?.parameters?.pageType &&
      this.shortcutsEntryAbilityWant?.parameters?.pageType === '2') {
      router = 'pages/shortcuts/ShortCutShare'
    }
    windowStage.loadContent(router, (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.');
    });
  }

  onWindowStageDestroy(): void {
    // Main window is destroyed, release UI related resources
    hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onWindowStageDestroy');
  }

  onForeground(): void {
    // Ability has brought to foreground
    hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onForeground');
  }

  onBackground(): void {
    // Ability has back to background
    hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onBackground');
  }
}