1# @ohos.app.ability.InsightIntentExecutor (意图调用执行基类)
2
3本模块提供意图调用执行基类，开发者通过意图调用执行基类对接端侧意图框架，实现响应意图调用的业务逻辑。开发者接入意图框架时，在意图配置文件中声明对接的意图名称、意图接入方式等，系统根据用户交互和开发者的意图配置文件进行意图调用，触发相应的意图调用执行回调。
4
5> **说明：**
6>
7> 本模块首批接口从API version 11开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
8>
9> 本模块接口仅可在Stage模型下使用。
10
11## 导入模块
12
13```ts
14import { InsightIntentExecutor } from '@kit.AbilityKit';
15```
16
17## 属性
18
19**模型约束**：此接口仅可在Stage模型下使用。
20
21**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。
22
23**系统能力**：SystemCapability.Ability.AbilityRuntime.Core
24
25| 名称 | 类型 | 只读 | 可选 | 说明 |
26| -------- | -------- | -------- | -------- | -------- |
27| context | [InsightIntentContext](js-apis-app-ability-insightIntentContext.md) | 否 | 否 | 意图调用执行上下文。 |
28
29## InsightIntentExecutor.onExecuteInUIAbilityForegroundMode
30
31onExecuteInUIAbilityForegroundMode(name: string, param: Record<string, Object>, pageLoader: window.WindowStage):
32  insightIntent.ExecuteResult | Promise<insightIntent.ExecuteResult>
33
34当意图调用是将UIAbility在前台显示时，触发该回调。支持同步返回和使用Promise异步返回。
35
36**模型约束**：此接口仅可在Stage模型下使用。
37
38**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。
39
40**系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore
41
42**参数：**
43
44| 参数名 | 类型 | 必填 | 说明 |
45| -------- | -------- | -------- | -------- |
46| name | string | 是 | 意图调用名称。 |
47| param | Record<string, Object> | 是 | 意图调用参数。 |
48| pageLoader | [window.WindowStage](../apis-arkui/js-apis-window.md#windowstage9) | 是 | 页面加载器。 |
49
50**返回值：**
51
52| 类型 | 说明 |
53| -------- | -------- |
54| [insightIntent.ExecuteResult](js-apis-app-ability-insightIntent.md#executeresult) | 意图调用执行结果。|
55| Promise<[insightIntent.ExecuteResult](js-apis-app-ability-insightIntent.md#executeresult)> | Promise对象，返回意图调用执行结果。 |
56
57**示例：**
58
59直接返回意图调用的结果，示例如下：
60  ```ts
61  import { InsightIntentExecutor, insightIntent } from '@kit.AbilityKit';
62  import { window } from '@kit.ArkUI';
63  import { hilog } from '@kit.PerformanceAnalysisKit';
64
65  export default class IntentExecutorImpl extends InsightIntentExecutor {
66    onExecuteInUIAbilityForegroundMode(name: string, param: Record<string, Object>, pageLoader: window.WindowStage): insightIntent.ExecuteResult {
67      let result: insightIntent.ExecuteResult;
68      if (name !== 'SupportedInsightIntentName') {
69        hilog.warn(0x0000, 'testTag', 'Unsupported insight intent %{public}s', name);
70        result = {
71          // decided by developer
72          code: 404,
73          result: {
74            message: 'Unsupported insight intent.',
75          }
76        };
77        return result;
78      }
79
80      // if developer need load content
81      pageLoader.loadContent('pages/Index', (err, data) => {
82        if (err.code) {
83          hilog.error(0x0000, 'testTag', 'Failed to load the content. Cause: %{public}s', JSON.stringify(err));
84        } else {
85          hilog.info(0x0000, 'testTag', '%{public}s', 'Succeeded in loading the content');
86        }
87      });
88
89      result = {
90        code: 0,
91        result: {
92          message: 'Execute insight intent succeed.',
93        }
94      };
95      return result;
96    }
97  }
98  ```
99
100使用Promise异步返回意图调用的结果，示例如下：
101  ```ts
102  import { InsightIntentExecutor, insightIntent } from '@kit.AbilityKit';
103  import { window } from '@kit.ArkUI';
104  import { hilog } from '@kit.PerformanceAnalysisKit';
105
106  async function executeInsightIntent(param: Record<string, Object>): Promise<insightIntent.ExecuteResult> {
107    return new Promise((resolve, reject) => {
108      let result: insightIntent.ExecuteResult = {
109        code: 0,
110        result: {
111          message: 'Execute insight intent succeed.',
112        }
113      };
114      resolve(result);
115    })
116  }
117
118  export default class IntentExecutorImpl extends InsightIntentExecutor {
119    async onExecuteInUIAbilityForegroundMode(name: string, param: Record<string, Object>, pageLoader: window.WindowStage): Promise<insightIntent.ExecuteResult> {
120      let result: insightIntent.ExecuteResult;
121      if (name !== 'SupportedInsightIntentName') {
122        hilog.warn(0x0000, 'testTag', 'Unsupported insight intent %{public}s', name);
123        result = {
124          // decided by developer
125          code: 404,
126          result: {
127            message: 'Unsupported insight intent.',
128          }
129        };
130        return result;
131      }
132
133      result = await executeInsightIntent(param);
134      return result;
135    }
136  }
137  ```
138
139## InsightIntentExecutor.onExecuteInUIAbilityBackgroundMode
140
141onExecuteInUIAbilityBackgroundMode(name: string, param: Record<string, Object>):
142    insightIntent.ExecuteResult | Promise<insightIntent.ExecuteResult>
143
144当意图调用是将UIAbility在后台拉起时，触发该回调。支持同步返回和使用Promise异步返回。
145
146**模型约束**：此接口仅可在Stage模型下使用。
147
148**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。
149
150**系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore
151
152**参数：**
153
154| 参数名 | 类型 | 必填 | 说明 |
155| -------- | -------- | -------- | -------- |
156| name | string | 是 | 意图调用名称。 |
157| param | Record<string, Object> | 是 | 意图调用参数。 |
158
159**返回值：**
160
161| 类型 | 说明 |
162| -------- | -------- |
163| [insightIntent.ExecuteResult](js-apis-app-ability-insightIntent.md#executeresult) | 意图调用执行结果。|
164| Promise<[insightIntent.ExecuteResult](js-apis-app-ability-insightIntent.md#executeresult)> | Promise对象，返回意图调用执行结果。 |
165
166**示例：**
167
168直接返回意图调用的结果，示例如下：
169  ```ts
170  import { InsightIntentExecutor, insightIntent } from '@kit.AbilityKit';
171
172  export default class IntentExecutorImpl extends InsightIntentExecutor {
173    onExecuteInUIAbilityBackgroundMode(name: string, param: Record<string, Object>): insightIntent.ExecuteResult {
174      let result: insightIntent.ExecuteResult = {
175        code: 0,
176        result: {
177          message: 'Execute insight intent succeed.',
178        }
179      };
180      return result;
181    }
182  }
183  ```
184
185使用Promise异步返回意图调用的结果，示例如下：
186  ```ts
187  import { InsightIntentExecutor, insightIntent } from '@kit.AbilityKit';
188
189  async function executeInsightIntent(param: Record<string, Object>): Promise<insightIntent.ExecuteResult> {
190    return new Promise((resolve, reject) => {
191      let result: insightIntent.ExecuteResult = {
192        code: 0,
193        result: {
194          message: 'Execute insight intent succeed.',
195        }
196      };
197      resolve(result);
198    })
199  }
200
201  export default class IntentExecutorImpl extends InsightIntentExecutor {
202    async onExecuteInUIAbilityBackgroundMode(name: string, param: Record<string, Object>): Promise<insightIntent.ExecuteResult> {
203      let result: insightIntent.ExecuteResult = await executeInsightIntent(param);
204      return result;
205    }
206  }
207  ```
208
209## InsightIntentExecutor.onExecuteInUIExtensionAbility
210
211onExecuteInUIExtensionAbility(name: string, param: Record<string, Object>, pageLoader: UIExtensionContentSession):
212  insightIntent.ExecuteResult | Promise<insightIntent.ExecuteResult>
213
214当意图调用是拉起UIExtensionAbility时，触发该回调。支持同步返回和使用Promise异步返回。
215
216**模型约束**：此接口仅可在Stage模型下使用。
217
218**系统能力**：SystemCapability.Ability.AbilityRuntime.Core
219
220**参数：**
221
222| 参数名 | 类型 | 必填 | 说明 |
223| -------- | -------- | -------- | -------- |
224| name | string | 是 | 意图调用名称。 |
225| param | Record<string, Object> | 是 | 意图调用参数。 |
226| pageLoader | [UIExtensionContentSession](js-apis-app-ability-uiExtensionContentSession.md) | 是 | 页面加载器。 |
227
228**返回值：**
229
230| 类型 | 说明 |
231| -------- | -------- |
232| [insightIntent.ExecuteResult](js-apis-app-ability-insightIntent.md#executeresult) | 意图调用执行结果。|
233| Promise<[insightIntent.ExecuteResult](js-apis-app-ability-insightIntent.md#executeresult)> | Promise对象，返回意图调用执行结果。 |
234
235**示例：**
236
237直接返回意图调用的结果，示例如下：
238  ```ts
239  import { InsightIntentExecutor, insightIntent, UIExtensionContentSession } from '@kit.AbilityKit';
240  import { hilog } from '@kit.PerformanceAnalysisKit';
241
242  export default class IntentExecutorImpl extends InsightIntentExecutor {
243    onExecuteInUIExtensionAbility(name: string, param: Record<string, Object>, pageLoader: UIExtensionContentSession): insightIntent.ExecuteResult {
244      let result: insightIntent.ExecuteResult;
245      if (name !== 'SupportedInsightIntentName') {
246        hilog.warn(0x0000, 'testTag', 'Unsupported insight intent %{public}s', name);
247        result = {
248          // decided by developer
249          code: 404,
250          result: {
251            message: 'Unsupported insight intent.',
252          }
253        };
254        return result;
255      }
256
257      // if developer need load content
258      pageLoader.loadContent('pages/Index');
259
260      result = {
261        code: 0,
262        result: {
263          message: 'Execute insight intent succeed.',
264        }
265      };
266      return result;
267    }
268  }
269  ```
270
271使用Promise异步返回意图调用的结果，示例如下：
272  ```ts
273  import { InsightIntentExecutor, insightIntent, UIExtensionContentSession } from '@kit.AbilityKit';
274  import { hilog } from '@kit.PerformanceAnalysisKit';
275
276  async function executeInsightIntent(param: Record<string, Object>): Promise<insightIntent.ExecuteResult> {
277    return new Promise((resolve, reject) => {
278      let result: insightIntent.ExecuteResult = {
279        code: 0,
280        result: {
281          message: 'Execute insight intent succeed.',
282        }
283      };
284      resolve(result);
285    })
286  }
287
288  export default class IntentExecutorImpl extends InsightIntentExecutor {
289    async onExecuteInUIExtensionAbility(name: string, param: Record<string, Object>, pageLoader: UIExtensionContentSession): Promise<insightIntent.ExecuteResult> {
290      let result: insightIntent.ExecuteResult;
291      if (name !== 'SupportedInsightIntentName') {
292        hilog.warn(0x0000, 'testTag', 'Unsupported insight intent %{public}s', name);
293        result = {
294          // decided by developer
295          code: 404,
296          result: {
297            message: 'Unsupported insight intent.',
298          }
299        };
300        return result;
301      }
302
303      result = await executeInsightIntent(param);
304      return result;
305    }
306  }
307  ```
308
309## InsightIntentExecutor.onExecuteInServiceExtensionAbility
310
311onExecuteInServiceExtensionAbility(name: string, param: Record<string, Object>):
312    insightIntent.ExecuteResult | Promise<insightIntent.ExecuteResult>
313
314当意图调用是拉起ServiceExtensionAbility时，触发该回调。支持同步返回和使用Promise异步返回。
315
316**模型约束**：此接口仅可在Stage模型下使用。
317
318**系统能力**：SystemCapability.Ability.AbilityRuntime.Core
319
320**参数：**
321
322| 参数名 | 类型 | 必填 | 说明 |
323| -------- | -------- | -------- | -------- |
324| name | string | 是 | 意图调用名称。 |
325| param | Record<string, Object> | 是 | 意图调用参数。 |
326
327**返回值：**
328
329| 类型 | 说明 |
330| -------- | -------- |
331| [insightIntent.ExecuteResult](js-apis-app-ability-insightIntent.md#executeresult) | 意图调用执行结果。|
332| Promise<[insightIntent.ExecuteResult](js-apis-app-ability-insightIntent.md#executeresult)> | Promise对象，返回意图调用执行结果。 |
333
334**示例：**
335
336直接返回意图调用的结果，示例如下：
337  ```ts
338  import { InsightIntentExecutor, insightIntent } from '@kit.AbilityKit';
339  import { hilog } from '@kit.PerformanceAnalysisKit';
340
341  export default class IntentExecutorImpl extends InsightIntentExecutor {
342    onExecuteInServiceExtensionAbility(name: string, param: Record<string, Object>): insightIntent.ExecuteResult {
343      let result: insightIntent.ExecuteResult;
344      if (name !== 'SupportedInsightIntentName') {
345        hilog.warn(0x0000, 'testTag', 'Unsupported insight intent %{public}s', name);
346        result = {
347          // decided by developer
348          code: 404,
349          result: {
350            message: 'Unsupported insight intent.',
351          }
352        };
353        return result;
354      }
355
356      result = {
357        code: 0,
358        result: {
359          message: 'Execute insight intent succeed.',
360        }
361      };
362      return result;
363    }
364  }
365  ```
366
367使用Promise异步返回意图调用的结果，示例如下：
368  ```ts
369  import { InsightIntentExecutor, insightIntent } from '@kit.AbilityKit';
370  import { hilog } from '@kit.PerformanceAnalysisKit';
371
372  async function executeInsightIntent(param: Record<string, Object>): Promise<insightIntent.ExecuteResult> {
373    return new Promise((resolve, reject) => {
374      let result: insightIntent.ExecuteResult = {
375        code: 0,
376        result: {
377          message: 'Execute insight intent succeed.',
378        }
379      };
380      resolve(result);
381    });
382  }
383
384  export default class IntentExecutorImpl extends InsightIntentExecutor {
385    async onExecuteInServiceExtensionAbility(name: string, param: Record<string, Object>): Promise<insightIntent.ExecuteResult> {
386      let result: insightIntent.ExecuteResult;
387      if (name !== 'SupportedInsightIntentName') {
388        hilog.warn(0x0000, 'testTag', 'Unsupported insight intent %{public}s', name);
389        result = {
390          // decided by developer
391          code: 404,
392          result: {
393            message: 'Unsupported insight intent.',
394          }
395        };
396        return result;
397      }
398
399      result = await executeInsightIntent(param);
400      return result;
401    }
402  }
403  ```