@ohos.bundle.launcherBundleManager (launcherBundleManager模块)(系统接口)

本模块支持launcher应用（桌面有图标的应用）所需的查询能力，支持LauncherAbilityInfo、ShortcutInfo信息的查询。

说明：

本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。

本模块为系统接口。

导入模块

import { launcherBundleManager } from '@kit.AbilityKit';

launcherBundleManager.getLauncherAbilityInfo

getLauncherAbilityInfo(bundleName: string, userId: number, callback: AsyncCallback<Array<LauncherAbilityInfo>>) : void

查询指定bundleName及用户的LauncherAbilityInfo。使用callback异步回调。

需要权限： ohos.permission.GET_BUNDLE_INFO_PRIVILEGED

系统接口： 此接口为系统接口。

系统能力： SystemCapability.BundleManager.BundleFramework.Launcher

参数：

参数名	类型	必填	说明
bundleName	string	是	应用Bundle名称。
userId	number	是	被查询的用户ID，可以通过getOsAccountLocalId接口获取。
callback	AsyncCallback<Array<LauncherAbilityInfo>>	是	回调函数。当函数调用成功，err为undefined，data为bundle包含的LauncherAbilityInfo信息。否则为错误对象。

错误码：

以下错误码的详细介绍请参见通用错误码和包管理子系统通用错误码。

错误码ID	错误信息
201	Verify permission denied.
202	Permission denied, non-system app called system api.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
801	Capability not support.
17700001	The specified bundle name is not found.
17700004	The specified user ID is not found.

示例：

import { launcherBundleManager } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  launcherBundleManager.getLauncherAbilityInfo('com.example.demo', 100,
    (errData: BusinessError, data: launcherBundleManager.LauncherAbilityInfo[]) => {
      if (errData !== null) {
        console.error(`errData is errCode:${errData.code}  message:${errData.message}`);
      } else {
        console.info('data is ' + JSON.stringify(data));
      }
    })
} catch (errData) {
  let code = (errData as BusinessError).code;
  let message = (errData as BusinessError).message;
  console.error(`errData is errCode:${code}  message:${message}`);
}

launcherBundleManager.getLauncherAbilityInfo

getLauncherAbilityInfo(bundleName: string, userId: number) : Promise<Array<LauncherAbilityInfo>>

查询指定bundleName及用户的LauncherAbilityInfo。使用Promise异步回调。

需要权限： ohos.permission.GET_BUNDLE_INFO_PRIVILEGED

系统接口： 此接口为系统接口。

系统能力： SystemCapability.BundleManager.BundleFramework.Launcher

参数：

参数名	类型	必填	说明
bundleName	string	是	应用Bundle名称。
userId	number	是	被查询的用户ID，可以通过getOsAccountLocalId接口获取。

返回值：

类型	说明
Promise<Array<LauncherAbilityInfo>>	Promise对象。返回bundle包含的LauncherAbilityInfo信息。

错误码：

以下错误码的详细介绍请参见通用错误码和包管理子系统通用错误码。

错误码ID	错误信息
201	Verify permission denied.
202	Permission denied, non-system app called system api.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
801	Capability not support.
17700001	The specified bundle name is not found.
17700004	The specified user ID is not found.

示例：

import { launcherBundleManager } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  launcherBundleManager.getLauncherAbilityInfo("com.example.demo", 100)
    .then((data: launcherBundleManager.LauncherAbilityInfo[]) => {
      console.info('data is ' + JSON.stringify(data));
    }).catch((errData: BusinessError) => {
    console.error(`errData is errCode:${errData.code}  message:${errData.message}`);
  })
} catch (errData) {
  let code = (errData as BusinessError).code;
  let message = (errData as BusinessError).message;
  console.error(`errData is errCode:${code}  message:${message}`);
}

launcherBundleManager.getAllLauncherAbilityInfo

getAllLauncherAbilityInfo(userId: number, callback: AsyncCallback<Array<LauncherAbilityInfo>>) : void

查询指定用户下所有应用的LauncherAbilityInfo。使用callback异步回调。

需要权限： ohos.permission.GET_BUNDLE_INFO_PRIVILEGED

系统接口： 此接口为系统接口。

系统能力： SystemCapability.BundleManager.BundleFramework.Launcher

参数：

参数名	类型	必填	说明
userId	number	是	被查询的用户ID，可以通过getOsAccountLocalId接口获取。
callback	AsyncCallback<Array<LauncherAbilityInfo>>	是	回调函数。当函数调用成功，err为undefined，data为指定用户下所有应用的LauncherAbilityInfo信息。否则为错误对象。

错误码：

以下错误码的详细介绍请参见通用错误码和包管理子系统通用错误码。

错误码ID	错误信息
201	Verify permission denied.
202	Permission denied, non-system app called system api.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
801	Capability not support.
17700004	The specified user ID is not found.

示例：

import { launcherBundleManager } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  launcherBundleManager.getAllLauncherAbilityInfo(100,
    (errData: BusinessError, data: launcherBundleManager.LauncherAbilityInfo[]) => {
      if (errData !== null) {
        console.error(`errData is errCode:${errData.code}  message:${errData.message}`);
      } else {
        console.info('data is ' + JSON.stringify(data));
      }
    });
} catch (errData) {
  let code = (errData as BusinessError).code;
  let message = (errData as BusinessError).message;
  console.error(`errData is errCode:${code}  message:${message}`);
}

launcherBundleManager.getAllLauncherAbilityInfo

getAllLauncherAbilityInfo(userId: number) : Promise<Array<LauncherAbilityInfo>>

查询指定用户下所有应用的LauncherAbilityInfo。使用Promise异步回调。

需要权限： ohos.permission.GET_BUNDLE_INFO_PRIVILEGED

系统接口： 此接口为系统接口。

系统能力： SystemCapability.BundleManager.BundleFramework.Launcher

参数：

参数名	类型	必填	说明
userId	number	是	被查询的用户ID，可以通过getOsAccountLocalId接口获取。

返回值：

类型	说明
Promise<Array<LauncherAbilityInfo>>	Promise对象。返回指定用户下所有应用的LauncherAbilityInfo。

错误码：

以下错误码的详细介绍请参见通用错误码和包管理子系统通用错误码。

错误码ID	错误信息
201	Verify permission denied.
202	Permission denied, non-system app called system api.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
801	Capability not support.
17700004	The specified user ID is not found.

示例：

import { launcherBundleManager } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  launcherBundleManager.getAllLauncherAbilityInfo(100)
    .then((data: launcherBundleManager.LauncherAbilityInfo[]) => {
      console.info('data is ' + JSON.stringify(data));
    }).catch((errData: BusinessError) => {
    console.error(`errData is errCode:${errData.code}  message:${errData.message}`);
  });
} catch (errData) {
  let code = (errData as BusinessError).code;
  let message = (errData as BusinessError).message;
  console.error(`errData is errCode:${code}  message:${message}`);
}

launcherBundleManager.getShortcutInfo

getShortcutInfo(bundleName :string, callback: AsyncCallback<Array<ShortcutInfo>>) : void

查询当前用户下指定应用的快捷方式信息ShortcutInfo，只支持查询主应用的ShortcutInfo，查询分身应用请使用getShortcutInfoByAppIndex。使用callback异步回调。

获取调用方自身的信息时不需要权限。

需要权限： ohos.permission.GET_BUNDLE_INFO_PRIVILEGED or ohos.permission.GET_BUNDLE_INFO

系统接口： 此接口为系统接口。

系统能力： SystemCapability.BundleManager.BundleFramework.Launcher

参数：

参数名	类型	必填	说明
bundleName	string	是	应用Bundle名称。
callback	AsyncCallback<Array<ShortcutInfo>>	是	回调函数。当函数调用成功，err为undefined，data为当前用户下指定应用的ShortcutInfo信息。否则为错误对象。

错误码：

以下错误码的详细介绍请参见通用错误码和包管理子系统通用错误码。

错误码ID	错误信息
201	Verify permission denied.
202	Permission denied, non-system app called system api.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
801	Capability not support.
17700001	The specified bundle name is not found.
17700026	The specified bundle is disabled.

示例：

import { launcherBundleManager } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  launcherBundleManager.getShortcutInfo("com.example.demo",
    (errData: BusinessError, data: launcherBundleManager.ShortcutInfo[]) => {
      if (errData !== null) {
        console.error(`errData is errCode:${errData.code}  message:${errData.message}`);
      } else {
        console.info('data is ' + JSON.stringify(data));
      }
    });
} catch (errData) {
  let code = (errData as BusinessError).code;
  let message = (errData as BusinessError).message;
  console.error(`errData is errCode:${code}  message:${message}`);
}

launcherBundleManager.getShortcutInfo

getShortcutInfo(bundleName : string) : Promise<Array<ShortcutInfo>>

查询当前用户下指定应用的快捷方式信息ShortcutInfo，只支持查询主应用的ShortcutInfo，查询分身应用请使用getShortcutInfoByAppIndex。使用Promise异步回调。

获取调用方自身的信息时不需要权限。

需要权限： ohos.permission.GET_BUNDLE_INFO_PRIVILEGED or ohos.permission.GET_BUNDLE_INFO

系统接口： 此接口为系统接口。

系统能力： SystemCapability.BundleManager.BundleFramework.Launcher

参数：

参数名	类型	必填	说明
bundleName	string	是	应用Bundle名称。

返回值：

类型	说明
Promise<Array<ShortcutInfo>>	Promise对象。返回当前用户下指定应用的ShortcutInfo。

错误码：

以下错误码的详细介绍请参见通用错误码和包管理子系统通用错误码。

错误码ID	错误信息
201	Verify permission denied.
202	Permission denied, non-system app called system api.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
801	Capability not support.
17700001	The specified bundle name is not found.
17700026	The specified bundle is disabled.

示例：

import { launcherBundleManager } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  launcherBundleManager.getShortcutInfo("com.example.demo")
    .then((data: launcherBundleManager.ShortcutInfo[]) => {
      console.info('data is ' + JSON.stringify(data));
    }).catch((errData: BusinessError) => {
    console.error(`errData is errCode:${errData.code}  message:${errData.message}`);
  });
} catch (errData) {
  let code = (errData as BusinessError).code;
  let message = (errData as BusinessError).message;
  console.error(`errData is errCode:${code}  message:${message}`);
}

launcherBundleManager.getShortcutInfoSync¹⁰⁺

getShortcutInfoSync(bundleName : string) : Array<ShortcutInfo>

查询当前用户下指定应用的快捷方式信息ShortcutInfo，只支持查询主应用的ShortcutInfo，查询分身应用请使用getShortcutInfoByAppIndex。

获取调用方自身的信息时不需要权限。

需要权限： ohos.permission.GET_BUNDLE_INFO_PRIVILEGED or ohos.permission.GET_BUNDLE_INFO

系统接口： 此接口为系统接口。

系统能力： SystemCapability.BundleManager.BundleFramework.Launcher

参数：

参数名	类型	必填	说明
bundleName	string	是	应用Bundle名称。

返回值：

类型	说明
Array<ShortcutInfo>	Array形式返回当前用户下指定应用的ShortcutInfo。

错误码：

以下错误码的详细介绍请参见通用错误码和包管理子系统通用错误码。

错误码ID	错误信息
201	Verify permission denied.
202	Permission denied, non-system app called system api.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
801	Capability not support.
17700001	The specified bundle name is not found.
17700026	The specified bundle is disabled.

示例：

import { launcherBundleManager } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  let data = launcherBundleManager.getShortcutInfoSync("com.example.demo");
  console.info('data is ' + JSON.stringify(data));
} catch (errData) {
  let code = (errData as BusinessError).code;
  let message = (errData as BusinessError).message;
  console.error(`errData is errCode:${code}  message:${message}`);
}

launcherBundleManager.getShortcutInfoSync¹³⁺

getShortcutInfoSync(bundleName: string, userId: number) : Array<ShortcutInfo>

查询指定用户下指定应用的快捷方式信息ShortcutInfo，只支持查询主应用的ShortcutInfo，查询分身应用请使用getShortcutInfoByAppIndex。

获取调用方自身的信息时不需要权限。

需要权限： ohos.permission.GET_BUNDLE_INFO_PRIVILEGED or ohos.permission.GET_BUNDLE_INFO

系统接口： 此接口为系统接口。

系统能力： SystemCapability.BundleManager.BundleFramework.Launcher

参数：

参数名	类型	必填	说明
bundleName	string	是	应用Bundle名称。
userId	number	是	表示用户ID，可以通过getOsAccountLocalId接口获取。

返回值：

类型	说明
Array<ShortcutInfo>	Array形式返回指定用户下指定应用的ShortcutInfo。

错误码：

以下错误码的详细介绍请参见通用错误码和包管理子系统通用错误码。

错误码ID	错误信息
201	Verify permission denied.
202	Permission denied, non-system app called system api.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
801	Capability not support.
17700001	The specified bundle name is not found.
17700004	The specified user ID is not found.
17700026	The specified bundle is disabled.

示例：

import { launcherBundleManager } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  let data = launcherBundleManager.getShortcutInfoSync("com.example.demo", 100);
  console.info('data is ' + JSON.stringify(data));
} catch (errData) {
  let code = (errData as BusinessError).code;
  let message = (errData as BusinessError).message;
  console.error(`errData is errCode:${code}  message:${message}`);
}

launcherBundleManager.startShortcut¹²⁺

startShortcut(shortcutInfo: ShortcutInfo, options?: StartOptions): Promise<void>

拉起指定ShortcutInfo中的ability。使用Promise异步回调。

需要权限： ohos.permission.START_SHORTCUT

系统接口： 此接口为系统接口。

系统能力： SystemCapability.BundleManager.BundleFramework.Launcher

参数：

参数名	类型	必填	说明
shortcutInfo	ShortcutInfo	是	应用的快捷方式信息。
options	StartOptions	否	启动参数选项，用于指定任务切到前台时的窗口模式，设备ID等。

返回值：

类型	说明
Promise<void>	Promise对象，无返回结果。

错误码：

以下错误码的详细介绍请参见通用错误码和包管理子系统通用错误码。

错误码ID	错误信息
201	Verify permission denied.
202	Permission denied, non-system app called system api.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
801	Capability not support.
17700065	The specified shortcut want in shortcut info is not supported to be started.

示例：

import { launcherBundleManager } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  let data: Array<launcherBundleManager.ShortcutInfo> = launcherBundleManager.getShortcutInfoSync("com.example.demo");
  console.info('data is ' + JSON.stringify(data));
  if (data) {
    try {
      launcherBundleManager.startShortcut(data[0])
        .then(() => {
          console.info('startShortcut success');
        }).catch((err: BusinessError) => {
        console.error(`errData is errCode:${err.code}  message:${err.message}`);
      });
    } catch (error) {
      let code = (error as BusinessError).code;
      let message = (error as BusinessError).message;
      console.error(`error is errCode:${code}  message:${message}`);
    }
  }
} catch (errData) {
  let code = (errData as BusinessError).code;
  let message = (errData as BusinessError).message;
  console.error(`errData is errCode:${code}  message:${message}`);
}

launcherBundleManager.startShortcutWithReason²⁰⁺

startShortcutWithReason(shortcutInfo: ShortcutInfo, startReason: string, options?: StartOptions): Promise<void>

根据指定的快捷方式信息，拉起对应的Ability，并携带快捷方式的启动原因。使用Promise异步回调。

被拉起方可以通过LaunchParam的launchReasonMessage字段获取到启动原因，并根据启动原因进行业务逻辑处理。

需要权限： ohos.permission.START_SHORTCUT 和 ohos.permission.SET_LAUNCH_REASON_MESSAGE (如果调用方有ohos.permission.START_SHORTCUT权限，没有ohos.permission.SET_LAUNCH_REASON_MESSAGE权限，Ability可以被拉起，但是携带的快捷方式启动原因无效)

系统接口： 此接口为系统接口。

系统能力： SystemCapability.BundleManager.BundleFramework.Launcher

参数：

参数名	类型	必填	说明
shortcutInfo	ShortcutInfo	是	应用的快捷方式信息。
startReason	string	是	快捷方式的启动原因，取值包括：AbilityConstant.REASON_MESSAGE_DESKTOP_SHORTCUT，表示桌面快捷方式启动。
options	StartOptions	否	启动Ability所携带的参数，用于指定目标Ability的窗口模式。

返回值：

类型	说明
Promise<void>	Promise对象，无返回结果。

错误码：

以下错误码的详细介绍请参见通用错误码和包管理子系统通用错误码。

错误码ID	错误信息
201	Verify permission denied.
202	Permission denied, non-system app called system api.
801	Capability not support.
17700065	The specified shortcut want in shortcut info is not supported to be started.

示例：

import { launcherBundleManager } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { AbilityConstant } from '@kit.AbilityKit';

try {
  let data: Array<launcherBundleManager.ShortcutInfo> =
    launcherBundleManager.getShortcutInfoSync("com.example.myapplication");
  console.info('startShortcutWithReason data is ' + JSON.stringify(data));
  let startReason = AbilityConstant.REASON_MESSAGE_DESKTOP_SHORTCUT;
  if (data) {
    try {
      launcherBundleManager.startShortcutWithReason(data[0], startReason)
        .then(() => {
          console.info('startShortcutWithReason success');
        }).catch((err: BusinessError) => {
        console.error(`startShortcutWithReason errData is errCode:${err.code}  message:${err.message}`);
      });
    } catch (error) {
      let code = (error as BusinessError).code;
      let message = (error as BusinessError).message;
      console.error(`startShortcutWithReason error is errCode:${code}  message:${message}`);
    }
  }
} catch (errData) {
  let code = (errData as BusinessError).code;
  let message = (errData as BusinessError).message;
  console.error(`startShortcutWithReason errData is errCode:${code}  message:${message}`);
}

launcherBundleManager.getShortcutInfoByAppIndex²⁰⁺

getShortcutInfoByAppIndex(bundleName: string, appIndex: number): Array<ShortcutInfo>

查询当前用户下指定分身应用的快捷方式信息ShortcutInfo。

调用方获取自己的信息时不需要权限。

需要权限： ohos.permission.GET_BUNDLE_INFO_PRIVILEGED

系统接口： 此接口为系统接口。

系统能力： SystemCapability.BundleManager.BundleFramework.Launcher

参数：

参数名	类型	必填	说明
bundleName	string	是	应用Bundle名称。
appIndex	number	是	分身应用的索引。

返回值：

类型	说明
Array<ShortcutInfo>	Array形式返回当前用户下指定分身应用的ShortcutInfo。

错误码：

以下错误码的详细介绍请参见通用错误码和包管理子系统通用错误码。

错误码ID	错误信息
201	Verify permission denied.
202	Permission denied, non-system app called system api.
801	Capability not support.
17700001	The specified bundle name is not found.
17700061	The specified app index is invalid.

示例：

import { launcherBundleManager } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  let data = launcherBundleManager.getShortcutInfoByAppIndex("com.example.demo", 1);
  console.info('getShortcutInfoByAppIndex successfully, data is ' + JSON.stringify(data));
} catch (errData) {
  let code = (errData as BusinessError).code;
  let message = (errData as BusinessError).message;
  console.error(`Failed to getShortcutInfoByAppIndex. Code: ${code}, message: ${message}`);
}

@ohos.bundle.launcherBundleManager (launcherBundleManager模块)(系统接口)

导入模块

launcherBundleManager.getLauncherAbilityInfo

launcherBundleManager.getLauncherAbilityInfo

launcherBundleManager.getAllLauncherAbilityInfo

launcherBundleManager.getAllLauncherAbilityInfo

launcherBundleManager.getShortcutInfo

launcherBundleManager.getShortcutInfo

launcherBundleManager.getShortcutInfoSync10+

launcherBundleManager.getShortcutInfoSync13+

launcherBundleManager.startShortcut12+

launcherBundleManager.startShortcutWithReason20+

launcherBundleManager.getShortcutInfoByAppIndex20+

launcherBundleManager.getShortcutInfoSync¹⁰⁺

launcherBundleManager.getShortcutInfoSync¹³⁺

launcherBundleManager.startShortcut¹²⁺

launcherBundleManager.startShortcutWithReason²⁰⁺

launcherBundleManager.getShortcutInfoByAppIndex²⁰⁺