1# @ohos.app.ability.insightIntentDriver (执行意图调用)(系统接口)
2
3本模块提供执行意图调用的能力，系统根据用户交互等信息执行意图调用。
4
5> **说明：**
6>
7> 本模块首批接口从API version 11开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
8>
9> 本模块接口仅可在Stage模型下使用。
10>
11> 本模块为系统接口。
12
13## 导入模块
14
15```ts
16import { insightIntentDriver } from '@kit.AbilityKit';
17```
18
19## ExecuteParam
20
21执行意图调用的参数。
22
23**模型约束**：此接口仅可在Stage模型下使用。
24
25**系统接口**：此接口为系统接口。
26
27**系统能力**：SystemCapability.Ability.AbilityRuntime.Core
28
29| 名称 | 类型 | 必填 | 说明 |
30| -------- | -------- | -------- | -------- |
31| bundleName | string | 是 | 意图调用Ability所属的应用名称。 |
32| moduleName | string | 是 | 意图调用Ability所属的模块名称。 |
33| abilityName | string | 是 | 意图调用Ability名称。 |
34| insightIntentName | string | 是 | 意图调用名称。 |
35| insightIntentParam | string | 是 | 意图调用参数。 |
36| executeMode | [insightIntent.ExecuteMode](js-apis-app-ability-insightIntent.md#executemode) | 是 | 意图调用执行模式。 |
37| displayId<sup>12+</sup> | number | 否 | 意图调用时指定的物理屏幕id，该参数应为整数，仅在executeMode为UI_ABILITY_FOREGROUND时生效。 |
38
39## insightIntentDriver.execute
40
41execute(param: ExecuteParam, callback: AsyncCallback<insightIntent.ExecuteResult>): void
42
43执行意图调用的接口。使用callback异步回调。
44当调用方在后台时，需要申请`ohos.permission.START_ABILITIES_FROM_BACKGROUND`权限。
45当意图调用执行模式[ExecuteMode](js-apis-app-ability-insightIntent.md#executemode)取值为UI_ABILITY_BACKGROUND时，需要申请`ohos.permission.ABILITY_BACKGROUND_COMMUNICATION`权限。
46
47**模型约束**：此接口仅可在Stage模型下使用。
48
49**系统接口**：此接口为系统接口。
50
51**需要权限**：ohos.permission.EXECUTE_INSIGHT_INTENT
52
53**系统能力**：SystemCapability.Ability.AbilityRuntime.Core
54
55**参数：**
56
57  | 参数名 | 类型 | 必填 | 说明 |
58  | -------- | -------- | -------- | -------- |
59  | param | [ExecuteParam](#executeparam) | 是 | 执行意图调用的参数。 |
60  | callback | AsyncCallback<[insightIntent.ExecuteResult](js-apis-app-ability-insightIntent.md#executeresult)> | 是 | 回调函数，返回意图调用执行结果。 |
61
62**错误码**：
63
64以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。
65
66| 错误码ID | 错误信息 |
67| -------- | -------- |
68| 201      | Permission denied. |
69| 202      | Not system application. |
70| 401      | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
71| 16000001 | The specified ability does not exist. |
72| 16000002 | Incorrect ability type. |
73| 16000004 | Failed to start the invisible ability. |
74| 16000005 | The specified process does not have the permission. |
75| 16000006 | Cross-user operations are not allowed. |
76| 16000008 | The crowdtesting application expires. |
77| 16000009 | An ability cannot be started or stopped in Wukong mode. |
78| 16000010 | The call with the continuation flag is forbidden. |
79| 16000011 | The context does not exist.        |
80| 16000012 | The application is controlled.        |
81| 16000013 | The application is controlled by EDM.       |
82| 16000050 | Internal error. |
83| 16000053 | The ability is not on the top of the UI. |
84| 16000055 | Installation-free timed out. |
85
86**示例：**
87
88```ts
89  import { insightIntentDriver, insightIntent } from '@kit.AbilityKit';
90  import { hilog } from '@kit.PerformanceAnalysisKit';
91
92  function executeInsightIntentAsync() {
93    let param: insightIntentDriver.ExecuteParam = {
94      bundleName: 'com.ohos.intentexecutedemo',
95      moduleName: 'entry',
96      abilityName: 'EntryAbility',
97      insightIntentName: 'PlayMusic',
98      insightIntentParam: {
99        songName: 'City Of Stars',
100      },
101      executeMode: insightIntent.ExecuteMode.UI_ABILITY_FOREGROUND,
102    };
103
104    try {
105      insightIntentDriver.execute(param, (error, data: insightIntent.ExecuteResult) => {
106        if (error) {
107          hilog.error(0x0000, 'testTag', 'execute insight intent failed with %{public}s', JSON.stringify(error));
108        } else {
109          hilog.info(0x0000, 'testTag', '%{public}s', 'execute insight intent succeed');
110        }
111        hilog.info(0x0000, 'testTag', 'execute insight intent return %{public}d', data.code);
112        hilog.info(0x0000, 'testTag', 'execute insight intent result %{public}s', JSON.stringify(data.result));
113      })
114    } catch (error) {
115      hilog.error(0x0000, 'testTag', 'execute insight intent error caught %{public}s', JSON.stringify(error));
116    }
117  }
118```
119
120## insightIntentDriver.execute
121
122execute(param: ExecuteParam): Promise<insightIntent.ExecuteResult>
123
124执行意图调用的接口。使用Promise异步回调。
125当调用方在后台时，需要申请`ohos.permission.START_ABILITIES_FROM_BACKGROUND`权限。
126当意图调用执行模式[ExecuteMode](js-apis-app-ability-insightIntent.md#executemode)取值为UI_ABILITY_BACKGROUND时，需要申请`ohos.permission.ABILITY_BACKGROUND_COMMUNICATION`权限。
127
128**模型约束**：此接口仅可在Stage模型下使用。
129
130**系统接口**：此接口为系统接口。
131
132**需要权限**：ohos.permission.EXECUTE_INSIGHT_INTENT
133
134**系统能力**：SystemCapability.Ability.AbilityRuntime.Core
135
136**参数：**
137
138  | 参数名 | 类型 | 必填 | 说明 |
139  | -------- | -------- | -------- | -------- |
140  | param | [ExecuteParam](#executeparam) | 是 | 执行意图调用的参数。 |
141
142**返回值：**
143
144| 类型 | 说明 |
145| -------- | -------- |
146| Promise<[insightIntent.ExecuteResult](js-apis-app-ability-insightIntent.md#executeresult)> | Promise对象，返回意图调用执行结果。 |
147
148**错误码**：
149
150以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。
151
152| 错误码ID | 错误信息 |
153| -------- | -------- |
154| 201      | Permission denied. |
155| 202      | Not system application. |
156| 401      | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
157| 16000001 | The specified ability does not exist. |
158| 16000002 | Incorrect ability type. |
159| 16000004 | Failed to start the invisible ability. |
160| 16000005 | The specified process does not have the permission. |
161| 16000006 | Cross-user operations are not allowed. |
162| 16000008 | The crowdtesting application expires. |
163| 16000009 | An ability cannot be started or stopped in Wukong mode. |
164| 16000010 | The call with the continuation flag is forbidden. |
165| 16000011 | The context does not exist.        |
166| 16000012 | The application is controlled.        |
167| 16000013 | The application is controlled by EDM.       |
168| 16000050 | Internal error. |
169| 16000053 | The ability is not on the top of the UI. |
170| 16000055 | Installation-free timed out. |
171
172**示例：**
173
174```ts
175  import { insightIntentDriver, insightIntent } from '@kit.AbilityKit';
176  import { hilog } from '@kit.PerformanceAnalysisKit';
177
178  async function executeSearchMusicIntentPromise() {
179    let param: insightIntentDriver.ExecuteParam = {
180      bundleName: 'com.ohos.intentexecutedemo',
181      moduleName: 'entry',
182      abilityName: 'EntryAbility',
183      insightIntentName: 'PlayMusic',
184      insightIntentParam: {
185        songName: 'City Of Stars',
186      },
187      executeMode: insightIntent.ExecuteMode.UI_ABILITY_FOREGROUND,
188    };
189
190    try {
191      let resultData: insightIntent.ExecuteResult = await insightIntentDriver.execute(param);
192      hilog.info(0x0000, 'testTag', 'execute insight intent return %{public}d', resultData.code);
193      hilog.info(0x0000, 'testTag', 'execute insight intent result %{public}s', JSON.stringify(resultData.result));
194    } catch (error) {
195      hilog.error(0x0000, 'testTag', 'execute insight intent error caught %{public}s', JSON.stringify(error));
196    }
197  }
198```
199