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
45**模型约束**：此接口仅可在Stage模型下使用。
46
47**系统接口**: 此接口为系统接口，三方应用不支持调用。
48
49**需要权限**: ohos.permission.EXECUTE_INSIGHT_INTENT
50
51**系统能力**：SystemCapability.Ability.AbilityRuntime.Core
52
53**参数：**
54
55  | 参数名 | 类型 | 必填 | 说明 |
56  | -------- | -------- | -------- | -------- |
57  | param | [ExecuteParam](#executeparam) | 是 | 执行意图调用的参数。 |
58  | callback | AsyncCallback<[insightIntent.ExecuteResult](js-apis-app-ability-insightIntent.md#executeresult)> | 是 | 回调函数，返回意图调用执行结果。 |
59
60**错误码**：
61
62以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。
63
64| 错误码ID | 错误信息 |
65| -------- | -------- |
66| 201      | Permission denied. |
67| 202      | Not system application. |
68| 401      | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
69| 16000001 | The specified ability does not exist. |
70| 16000002 | Incorrect ability type. |
71| 16000004 | Failed to start the invisible ability. |
72| 16000005 | The specified process does not have the permission. |
73| 16000006 | Cross-user operations are not allowed. |
74| 16000008 | The crowdtesting application expires. |
75| 16000009 | An ability cannot be started or stopped in Wukong mode. |
76| 16000010 | The call with the continuation flag is forbidden. |
77| 16000011 | The context does not exist.        |
78| 16000012 | The application is controlled.        |
79| 16000013 | The application is controlled by EDM.       |
80| 16000050 | Internal error. |
81| 16000053 | The ability is not on the top of the UI. |
82| 16000055 | Installation-free timed out. |
83
84**示例：**
85
86```ts
87  import { insightIntentDriver, insightIntent } from '@kit.AbilityKit';
88  import { hilog } from '@kit.PerformanceAnalysisKit';
89
90  function executeInsightIntentAsync() {
91    let param: insightIntentDriver.ExecuteParam = {
92      bundleName: 'com.ohos.intentexecutedemo',
93      moduleName: 'entry',
94      abilityName: 'EntryAbility',
95      insightIntentName: 'PlayMusic',
96      insightIntentParam: {
97        songName: 'City Of Stars',
98      },
99      executeMode: insightIntent.ExecuteMode.UI_ABILITY_FOREGROUND,
100    };
101
102    try {
103      insightIntentDriver.execute(param, (error, data: insightIntent.ExecuteResult) => {
104        if (error) {
105          hilog.error(0x0000, 'testTag', 'execute insight intent failed with %{public}s', JSON.stringify(error));
106        } else {
107          hilog.info(0x0000, 'testTag', '%{public}s', 'execute insight intent succeed');
108        }
109        hilog.info(0x0000, 'testTag', 'execute insight intent return %{public}d', data.code);
110        hilog.info(0x0000, 'testTag', 'execute insight intent result %{public}s', JSON.stringify(data.result));
111      })
112    } catch (error) {
113      hilog.error(0x0000, 'testTag', 'execute insight intent error caught %{public}s', JSON.stringify(error));
114    }
115  }
116```
117
118## insightIntentDriver.execute
119
120execute(param: ExecuteParam): Promise<insightIntent.ExecuteResult>
121
122执行意图调用的接口。使用Promise异步回调。
123
124**模型约束**：此接口仅可在Stage模型下使用。
125
126**系统接口**: 此接口为系统接口，三方应用不支持调用。
127
128**需要权限**: ohos.permission.EXECUTE_INSIGHT_INTENT
129
130**系统能力**：SystemCapability.Ability.AbilityRuntime.Core
131
132**参数：**
133
134  | 参数名 | 类型 | 必填 | 说明 |
135  | -------- | -------- | -------- | -------- |
136  | param | [ExecuteParam](#executeparam) | 是 | 执行意图调用的参数。 |
137
138**返回值：**
139
140| 类型 | 说明 |
141| -------- | -------- |
142| Promise<[insightIntent.ExecuteResult](js-apis-app-ability-insightIntent.md#executeresult)> | Promise对象，返回意图调用执行结果。 |
143
144**错误码**：
145
146以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。
147
148| 错误码ID | 错误信息 |
149| -------- | -------- |
150| 201      | Permission denied. |
151| 202      | Not system application. |
152| 401      | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
153| 16000001 | The specified ability does not exist. |
154| 16000002 | Incorrect ability type. |
155| 16000004 | Failed to start the invisible ability. |
156| 16000005 | The specified process does not have the permission. |
157| 16000006 | Cross-user operations are not allowed. |
158| 16000008 | The crowdtesting application expires. |
159| 16000009 | An ability cannot be started or stopped in Wukong mode. |
160| 16000010 | The call with the continuation flag is forbidden. |
161| 16000011 | The context does not exist.        |
162| 16000012 | The application is controlled.        |
163| 16000013 | The application is controlled by EDM.       |
164| 16000050 | Internal error. |
165| 16000053 | The ability is not on the top of the UI. |
166| 16000055 | Installation-free timed out. |
167
168**示例：**
169
170```ts
171  import { insightIntentDriver, insightIntent } from '@kit.AbilityKit';
172  import { hilog } from '@kit.PerformanceAnalysisKit';
173
174  async function executeSearchMusicIntentPromise() {
175    let param: insightIntentDriver.ExecuteParam = {
176      bundleName: 'com.ohos.intentexecutedemo',
177      moduleName: 'entry',
178      abilityName: 'EntryAbility',
179      insightIntentName: 'PlayMusic',
180      insightIntentParam: {
181        songName: 'City Of Stars',
182      },
183      executeMode: insightIntent.ExecuteMode.UI_ABILITY_FOREGROUND,
184    };
185
186    try {
187      let resultData: insightIntent.ExecuteResult = await insightIntentDriver.execute(param);
188      hilog.info(0x0000, 'testTag', 'execute insight intent return %{public}d', resultData.code);
189      hilog.info(0x0000, 'testTag', 'execute insight intent result %{public}s', JSON.stringify(resultData.result));
190    } catch (error) {
191      hilog.error(0x0000, 'testTag', 'execute insight intent error caught %{public}s', JSON.stringify(error));
192    }
193  }
194```
195