openharmony 鸿蒙 js-apis-app-ability-insightIntentDriver-sys

2025-06-12 浏览 (1)

@ohos.app.ability.insightIntentDriver (执行意图调用)(系统接口)

本模块提供执行意图调用的能力，系统根据用户交互等信息执行意图调用。

说明：

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

本模块接口仅可在Stage模型下使用。

本模块为系统接口。

本模块从API version 20开始支持通过@InsightIntentLink装饰器定义的意图来实现应用跳转。

导入模块

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

ExecuteParam

执行意图调用的参数。

模型约束：此接口仅可在Stage模型下使用。

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

系统能力：SystemCapability.Ability.AbilityRuntime.Core

名称类型必填说明
bundleNamestring是意图调用Ability所属的应用名称。
moduleNamestring是意图调用Ability所属的模块名称。
abilityNamestring是意图调用Ability名称。 如果通过@InsightIntentLink装饰器定义的意图来实现应用跳转，此字段传空字符串即可。
insightIntentNamestring是意图调用名称。
insightIntentParamRecord<string, Object>是意图调用参数。
executeModeinsightIntent.ExecuteMode是意图调用执行模式。 如果通过@InsightIntentLink装饰器定义的意图来实现应用跳转，此字段需填写（可填任意符合定义的值），但实际不会生效。
displayId12+number否意图调用时指定的物理屏幕id，该参数应为整数，仅在executeMode为UI_ABILITY_FOREGROUND时生效。
uris18+Array<string>否意图调用时，意图调用方给意图执行方授权的URI列表。 如果通过@InsightIntentLink装饰器定义的意图来实现应用跳转，此字段必选，仅读取数组第一个元素作为openLink的URI。
flags18+number否意图调用时，意图调用方给意图执行方授权的uris的flags。
说明：
该参数仅支持FLAG_AUTH_READ_URI_PERMISSION、FLAG_AUTH_WRITE_URI_PERMISSION、FLAG_AUTH_READ_URI_PERMISSION|FLAG_AUTH_WRITE_URI_PERMISSION。

LinkIntentInfo20+

LinkIntentInfo继承自IntentDecoratorInfo，用于描述@InsightIntentLink装饰器支持的参数，例如应用间跳转需要的uri信息。

模型约束：此接口仅可在Stage模型下使用。

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

系统能力：SystemCapability.Ability.AbilityRuntime.Core

名称类型只读可选说明
uristring是否表示意图的uri信息。

PageIntentInfo20+

PageIntentInfo继承自IntentDecoratorInfo，用于描述@InsightIntentPage装饰器支持的参数，例如目标页面的NavDestination名称。

模型约束：此接口仅可在Stage模型下使用。

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

系统能力：SystemCapability.Ability.AbilityRuntime.Core

名称类型只读可选说明
uiAbilitystring是否Ability名称。
pageRouterNamestring是否页面名称。
navigationIdstring是否表示与意图绑定Navigation的id。
navDestinationstring是否表示与意图绑定NavDestination组件的名称。

FunctionIntentInfo20+

@InsightIntentFunctionMethod装饰器的参数类型，当前全部属性均继承自IntentDecoratorInfo。

模型约束：此接口仅可在Stage模型下使用。

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

系统能力：SystemCapability.Ability.AbilityRuntime.Core

InsightIntentInfo20+

意图信息，表示设备中意图的具体参数配置。

模型约束：此接口仅可在Stage模型下使用。

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

系统能力：SystemCapability.Ability.AbilityRuntime.Core

名称类型只读可选说明
bundleNamestring是否表示应用包名称。
moduleNamestring是否表示模块名称。
intentNamestring是否表示意图名称。
domainstring是否表示意图垂域，用于将意图按垂直领域分类（例如：视频、音乐、游戏），取值范围参见各垂域的智慧分发特性列表中的垂域字段。
intentVersionstring是否意图版本号，当意图能力演进时，可通过版本号进行区分和管理。
displayNamestring是否表示在意图框架中显示的意图名称。
displayDescriptionstring是否表示在意图框架中显示的意图描述。
schemastring是否标准意图名称，如果在标准意图列表中存在schema与intentVersion字段均匹配的意图，则按照标准意图处理。
iconstring是否表示意图图标。
llmDescriptionstring是否表示意图的功能，用于大型语言模型理解该意图。
keywordsArray<string>是否表示意图的搜索关键字。
intentTypestring是否表示通过意图装饰器定义的意图类型。
subIntentInfoLinkIntentInfo |PageIntentInfo |FunctionIntentInfo是否表示特定意图装饰器的意图信息。
parametersRecord<string, Object>是否表示意图参数的数据格式声明，用于意图调用时定义入参的数据格式。

GetInsightIntentFlag20+

意图信息（InsightIntentInfo）的标识，用于getAllInsightIntentInfo、getInsightIntentInfoByBundleName和getInsightIntentInfoByIntentName接口查询全量意图信息或者简要意图信息。

系统能力：SystemCapability.Ability.AbilityRuntime.Core

名称值说明
GET_FULL_INSIGHT_INTENT1查询InsightIntentInfo中的全部信息。
GET_SUMMARY_INSIGHT_INTENT2查询InsightIntentInfo中的部分信息，具体差异见表1。

表1 全量意图信息与简要意图信息差别

属性全量意图信息是否包含简要意图信息是否包含
bundleName是是
moduleName是是
intentName是是
domain是否
intentVersion是否
displayName是是
displayDescription是否
schema是否
icon是否
llmDescription是否
keywords是否
intentType是是
subIntentInfo是是
parameters是是

insightIntentDriver.execute

execute(param: ExecuteParam, callback: AsyncCallback<insightIntent.ExecuteResult>): void

执行意图调用的接口。使用callback异步回调。 当调用方在后台时，需要申请ohos.permission.START_ABILITIES_FROM_BACKGROUND权限。 当意图调用执行模式ExecuteMode取值为UI_ABILITY_BACKGROUND时，需要申请ohos.permission.ABILITY_BACKGROUND_COMMUNICATION权限。

模型约束：此接口仅可在Stage模型下使用。

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

需要权限：ohos.permission.EXECUTE_INSIGHT_INTENT

系统能力：SystemCapability.Ability.AbilityRuntime.Core

参数：

参数名类型必填说明
paramExecuteParam是执行意图调用的参数。
callbackAsyncCallback<insightIntent.ExecuteResult>是回调函数，返回意图调用执行结果。

错误码：

以下错误码详细介绍请参考通用错误码和元能力子系统错误码。

错误码ID错误信息
201Permission denied.
202Not system application.
401Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
16000001The specified ability does not exist.
16000002Incorrect ability type.
16000004Cannot start an invisible component.
16000005The specified process does not have the permission.
16000006Cross-user operations are not allowed.
16000008The crowdtesting application expires.
16000009An ability cannot be started or stopped in Wukong mode.
16000010The call with the continuation and prepare continuation flag is forbidden.
16000011The context does not exist.
16000012The application is controlled.
16000013The application is controlled by EDM.
16000050Internal error.
16000053The ability is not on the top of the UI.
16000055Installation-free timed out.

示例：

  import { insightIntentDriver, insightIntent } from '@kit.AbilityKit';
  import { hilog } from '@kit.PerformanceAnalysisKit';

  function executeInsightIntentAsync() {
    let param: insightIntentDriver.ExecuteParam = {
      bundleName: 'com.ohos.intentexecutedemo',
      moduleName: 'entry',
      abilityName: 'EntryAbility',
      insightIntentName: 'PlayMusic',
      insightIntentParam: {
        songName: 'City Of Stars',
      },
      executeMode: insightIntent.ExecuteMode.UI_ABILITY_FOREGROUND,
    };

    try {
      insightIntentDriver.execute(param, (error, data: insightIntent.ExecuteResult) => {
        if (error) {
          hilog.error(0x0000, 'testTag', 'execute insight intent failed with %{public}s', JSON.stringify(error));
        } else {
          hilog.info(0x0000, 'testTag', '%{public}s', 'execute insight intent succeed');
        }
        hilog.info(0x0000, 'testTag', 'execute insight intent return %{public}d', data.code);
        hilog.info(0x0000, 'testTag', 'execute insight intent result %{public}s', JSON.stringify(data.result));
      })
    } catch (error) {
      hilog.error(0x0000, 'testTag', 'execute insight intent error caught %{public}s', JSON.stringify(error));
    }
  }

insightIntentDriver.execute

execute(param: ExecuteParam): Promise<insightIntent.ExecuteResult>

执行意图调用的接口。使用Promise异步回调。 当调用方在后台时，需要申请ohos.permission.START_ABILITIES_FROM_BACKGROUND权限。 当意图调用执行模式ExecuteMode取值为UI_ABILITY_BACKGROUND时，需要申请ohos.permission.ABILITY_BACKGROUND_COMMUNICATION权限。

模型约束：此接口仅可在Stage模型下使用。

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

需要权限：ohos.permission.EXECUTE_INSIGHT_INTENT

系统能力：SystemCapability.Ability.AbilityRuntime.Core

参数：

参数名类型必填说明
paramExecuteParam是执行意图调用的参数。

返回值：

类型说明
Promise<insightIntent.ExecuteResult>Promise对象，返回意图调用执行结果。

错误码：

以下错误码详细介绍请参考通用错误码和元能力子系统错误码。

错误码ID错误信息
201Permission denied.
202Not system application.
401Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
16000001The specified ability does not exist.
16000002Incorrect ability type.
16000004Cannot start an invisible component.
16000005The specified process does not have the permission.
16000006Cross-user operations are not allowed.
16000008The crowdtesting application expires.
16000009An ability cannot be started or stopped in Wukong mode.
16000010The call with the continuation and prepare continuation flag is forbidden.
16000011The context does not exist.
16000012The application is controlled.
16000013The application is controlled by EDM.
16000050Internal error.
16000053The ability is not on the top of the UI.
16000055Installation-free timed out.

示例：

  import { insightIntentDriver, insightIntent } from '@kit.AbilityKit';
  import { hilog } from '@kit.PerformanceAnalysisKit';

  async function executeSearchMusicIntentPromise() {
    let param: insightIntentDriver.ExecuteParam = {
      bundleName: 'com.ohos.intentexecutedemo',
      moduleName: 'entry',
      abilityName: 'EntryAbility',
      insightIntentName: 'PlayMusic',
      insightIntentParam: {
        songName: 'City Of Stars',
      },
      executeMode: insightIntent.ExecuteMode.UI_ABILITY_FOREGROUND,
    };

    try {
      let resultData: insightIntent.ExecuteResult = await insightIntentDriver.execute(param);
      hilog.info(0x0000, 'testTag', 'execute insight intent return %{public}d', resultData.code);
      hilog.info(0x0000, 'testTag', 'execute insight intent result %{public}s', JSON.stringify(resultData.result));
    } catch (error) {
      hilog.error(0x0000, 'testTag', 'execute insight intent error caught %{public}s', JSON.stringify(error));
    }
  }

insightIntentDriver.getAllInsightIntentInfo20+

getAllInsightIntentInfo(intentFlags: number): Promise<Array<InsightIntentInfo>>

查询当前设备上的所有意图信息。使用Promise异步回调。

模型约束：此接口仅可在Stage模型下使用。

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

需要权限：ohos.permission.GET_BUNDLE_INFO_PRIVILEGED

系统能力：SystemCapability.Ability.AbilityRuntime.Core

参数：

参数名类型必填说明
intentFlagsnumber是意图信息（InsightIntentInfo）的标识，用于表示查询全量意图信息或者简要意图信息，参考GetInsightIntentFlag。

返回值：

类型说明
Promise<Array<InsightIntentInfo>>Promise对象，返回意图信息对象数组。

错误码：

以下错误码详细介绍请参考通用错误码和元能力子系统错误码。

错误码ID错误信息
201Permission denied.
202Not system application.
16000050Internal error.

示例：

  import { insightIntentDriver } from '@kit.AbilityKit';
  import { BusinessError } from '@kit.BasicServicesKit';
  import { hilog } from '@kit.PerformanceAnalysisKit';

  async function getInfos() {
    try {
      insightIntentDriver.getAllInsightIntentInfo(insightIntentDriver.GetInsightIntentFlag.GET_FULL_INSIGHT_INTENT).then((data) => {
        hilog.info(0x0000, 'testTag', 'getAllInsightIntentInfo return %{public}s', JSON.stringify(data));
      }).catch((err: BusinessError) => {
        hilog.info(0x0000, 'testTag', 'getAllInsightIntentInfo errCode: %{public}d', err.code);
        hilog.info(0x0000, 'testTag', 'getAllInsightIntentInfo errMessage: %{public}s', err.message);
      });
    } catch (error) {
      hilog.error(0x0000, 'testTag', 'getAllInsightIntentInfo error caught %{public}s', JSON.stringify(error));
    }
  }

insightIntentDriver.getInsightIntentInfoByBundleName20+

getInsightIntentInfoByBundleName(bundleName: string, intentFlags: number): Promise<Array<InsightIntentInfo>>

根据包名查询当前设备上的意图信息。使用Promise异步回调。

模型约束：此接口仅可在Stage模型下使用。

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

需要权限：ohos.permission.GET_BUNDLE_INFO_PRIVILEGED

系统能力：SystemCapability.Ability.AbilityRuntime.Core

参数：

参数名类型必填说明
bundleNamestring是应用包名称。
说明：
若包名不存在，则返回空数组。
intentFlagsnumber是意图信息（InsightIntentInfo）的标识，用于表示查询全量意图信息或者简要意图信息，参考GetInsightIntentFlag。

返回值：

类型说明
Promise<Array<InsightIntentInfo>>Promise对象，返回意图信息对象数组。

错误码：

以下错误码详细介绍请参考通用错误码和元能力子系统错误码。

错误码ID错误信息
201Permission denied.
202Not system application.
16000050Internal error.

示例：

  import { insightIntentDriver } from '@kit.AbilityKit';
  import { BusinessError } from '@kit.BasicServicesKit';
  import { hilog } from '@kit.PerformanceAnalysisKit';

  async function getInfosByBundleName() {
    try {
      let bundleName = "com.example.intent"; // 开发者需自行修改为实际包名
      insightIntentDriver.getInsightIntentInfoByBundleName(bundleName, insightIntentDriver.GetInsightIntentFlag.GET_FULL_INSIGHT_INTENT).then((data) => {
        hilog.info(0x0000, 'testTag', 'getInsightIntentInfoByBundleName return %{public}s', JSON.stringify(data));
      }).catch((err: BusinessError) => {
        hilog.info(0x0000, 'testTag', 'getInsightIntentInfoByBundleName errCode: %{public}d', err.code);
        hilog.info(0x0000, 'testTag', 'getInsightIntentInfoByBundleName errMessage: %{public}s', err.message);
      });
    } catch (error) {
      hilog.error(0x0000, 'testTag', 'getInsightIntentInfoByBundleName error caught %{public}s', JSON.stringify(error));
    }
  }

insightIntentDriver.getInsightIntentInfoByIntentName20+

getInsightIntentInfoByIntentName(bundleName: string, moduleName: string, intentName: string, intentFlags: number): Promise<InsightIntentInfo>

根据包名、模块名和意图名查询当前设备上的意图信息。使用Promise异步回调。

模型约束：此接口仅可在Stage模型下使用。

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

需要权限：ohos.permission.GET_BUNDLE_INFO_PRIVILEGED

系统能力：SystemCapability.Ability.AbilityRuntime.Core

参数：

参数名类型必填说明
bundleNamestring是应用包名称。
说明：
若包名不存在，则返回空对象。
moduleNamestring是模块名称。
说明：
若模块名不存在，则返回空对象。
intentNamestring是意图名称。
说明：
若意图名不存在，则返回空对象。
intentFlagsnumber是意图信息（InsightIntentInfo）的标识，用于表示查询全量意图信息或者简要意图信息，参考GetInsightIntentFlag。

返回值：

类型说明
Promise<InsightIntentInfo>Promise对象，返回意图信息对象。

错误码：

以下错误码详细介绍请参考通用错误码和元能力子系统错误码。

错误码ID错误信息
201Permission denied.
202Not system application.
16000050Internal error.

示例：

  import { insightIntentDriver } from '@kit.AbilityKit';
  import { BusinessError } from '@kit.BasicServicesKit';
  import { hilog } from '@kit.PerformanceAnalysisKit';

  function getInfoByIntentName() {
    try {
      let bundleName = "com.example.intent"; // 开发者需自行修改为实际包名
      let moduleName = "entry"; // 开发者需自行修改为实际模块名
      let intentName = "play"; // 开发者需自行修改为实际意图名
      insightIntentDriver.getInsightIntentInfoByIntentName(
        bundleName, moduleName, intentName, insightIntentDriver.GetInsightIntentFlag.GET_FULL_INSIGHT_INTENT)
      .then((data) => {
        hilog.info(0x0000, 'testTag', 'getInsightIntentInfoByIntentName return %{public}s', JSON.stringify(data));
      }).catch((err: BusinessError) => {
        hilog.info(0x0000, 'testTag', 'getInsightIntentInfoByIntentName errCode: %{public}d', err.code);
        hilog.info(0x0000, 'testTag', 'getInsightIntentInfoByIntentName errMessage: %{public}s', err.message);
      });
    } catch (error) {
      hilog.error(0x0000, 'testTag', 'getInsightIntentInfoByIntentName error caught %{public}s', JSON.stringify(error));
    }
  }

你可能感兴趣的鸿蒙文章

harmony 鸿蒙Ability Kit（程序框架服务）

harmony 鸿蒙AbilityBase

harmony 鸿蒙AbilityBase_Element

harmony 鸿蒙AbilityRuntime

harmony 鸿蒙bundle

harmony 鸿蒙OH_NativeBundle_ApplicationInfo

harmony 鸿蒙OH_NativeBundle_ElementName

harmony 鸿蒙ability_base_common.h

harmony 鸿蒙ability_runtime_common.h

harmony 鸿蒙application_context.h

  • 所属分类： 后端技术
  • 本文标签： 软件 鸿蒙
  • 版权声明： 本文链接 https://seaxiang.com/blog/aG5eV8