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