1# 使用配置文件开发意图 2 3<!--Kit: Ability Kit--> 4<!--Subsystem: Ability--> 5<!--Owner: @zhangyafei-echo--> 6<!--Designer: @zhangyafei-echo--> 7<!--Tester: @lixueqing513--> 8<!--Adviser: @huipeizi--> 9 10## 简介 11从API version 11及以上版本，支持通过配置文件开发意图。主要包含两个环节： 12 131. 通过[insight_intent.json配置文件](#insight_intentjson配置文件说明)定义意图，声明意图执行器的代码路径、绑定的Ability组件等意图信息。 14 152. 通过[InsightIntentExecutor](../reference/apis-ability-kit/js-apis-app-ability-insightIntentExecutor.md#insightintentexecutor)实现意图执行逻辑。 16 17不同Ability组件类型需要配置的字段与需要实现的意图执行器，如下所示： 18 19| 组件类型 | 意图配置 | 意图执行器 | 20| --- | --- | --- | 21| UIAbility | 需要在`insight_intent.json`文件中配置"uiAbility"字段。 | 当"executeMode"字段为"foreground"时，实现`onExecuteInUIAbilityForegroundMode`，通过startAbility启动意图绑定的UIAbility组件。<br>当"executeMode"字段为"background"时，实现`onExecuteInUIAbilityBackgroundMode`，通过[Call调用](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md#后台通信能力)启动意图绑定的UIAbility组件。 | 22| UIExtensionAbility | 需要在`insight_intent.json`文件中配置"uiExtension"字段。 | 实现`onExecuteInUIExtensionAbility`。 | 23|<!--DelRow--> ServiceExtensionAbility | 需要在`insight_intent.json`文件中配置"serviceExtension"字段。 | 实现 `onExecuteInServiceExtensionAbility`。 | 24| 卡片(FormExtensionAbility) | 需要在`insight_intent.json`文件中配置"form"字段。 | 无需单独执行器。 | 25 26## 接口说明 27意图执行器实现需要继承[InsightIntentExecutor](../reference/apis-ability-kit/js-apis-app-ability-insightIntentExecutor.md#insightintentexecutor)，实现[onExecuteInUIAbilityForegroundMode](../reference/apis-ability-kit/js-apis-app-ability-insightIntentExecutor.md#onexecuteinuiabilityforegroundmode)等方法。开发者响应意图执行通过onExecuteInUIAbilityForegroundMode等接口实现，在不同的意图执行模式下，接口的触发时机也不同。针对不同意图执行模式的意图回调执行时机见各个回调的API说明。 28 29## 开发步骤 30### 意图绑定UIAbility组件 31 32通过DevEco Studio工具可视化创建意图，操作及开发步骤如下。 331. 选中模块或模块下的文件，右键单击`New` > `Insight Intent`，进入意图框架配置界面。 342. 选择意图垂域、意图框架入口代码文件名以及意图配置。意图配置包含意图名称和绑定的Ability组件。 353. 点击`Finish`，完成意图框架创建。 36 此时将在module目录 > src > main > resource > base > profile中，生成insight_intent.json文件，可在该文件查看当前意图框架配置的相关信息。 37 38 ```json 39 { 40 "insightIntents": [ 41 { 42 "domain": "MusicDomain", 43 "intentName": "PlayMusic", 44 "intentVersion": "1.0.1", 45 "srcEntry": "./ets/insightintents/PlayMusicExecutor.ets", 46 "uiAbility": { 47 "ability": "MusicPlayerAbility", 48 "executeMode": [ 49 "foreground", 50 "background" 51 ] 52 } 53 } 54 ] 55 } 56 ``` 57 584. 在module目录 > src > main > ets > insightintents目录下生成入口代码文件。开发者在意图执行函数中实现意图的功能代码。 59 60 ```ts 61 // 本示例对应意图配置中的"srcEntry"字段对应的文件 62 import { InsightIntentExecutor, insightIntent } from '@kit.AbilityKit'; 63 import { window } from '@kit.ArkUI'; 64 65 export default class PlayMusicExecutor extends InsightIntentExecutor { 66 // 由于意图配置中"executeMode"配置了"foreground"前台模式执行，故需要实现该接口 67 async onExecuteInUIAbilityForegroundMode(intentName: string, params: Record<string, Object>, 68 windowStage: window.WindowStage): Promise<insightIntent.ExecuteResult> { 69 // 实现播放逻辑 70 const result: insightIntent.ExecuteResult = { 71 code: 0 72 }; 73 return Promise.resolve(result); 74 } 75 76 // 由于意图配置中"executeMode"配置了"background"后台模式执行，故需要实现该接口 77 async onExecuteInUIAbilityBackgroundMode(intentName: string, 78 params: Record<string, Object>): Promise<insightIntent.ExecuteResult> { 79 // 后台控制逻辑 80 const result: insightIntent.ExecuteResult = { 81 code: 0 82 }; 83 return Promise.resolve(result); 84 } 85 } 86 ``` 87 88> **说明：** 89> 90> 配置文件范式仅提供基础执行能力，参数格式需开发者与系统入口协商。 91 92开发者也可以选择按规范手动创建意图配置文件和意图执行器。需要关注如下注意点： 93- 必须声明绑定的Ability组件和支持的意图执行模式。 94- 配置文件必须命名为"insight_intent.json"。 95- 配置文件存放路径为"resources/base/profile"。 96- 配置文件关键字段遵循相应的约束。 97 98### 意图绑定UIExtensionAbility组件 99 100参考[意图绑定UIAbility组件](#意图绑定uiability组件)完成工程创建。 101 102意图配置示例： 103 104```json 105{ 106 "insightIntents": [ 107 { 108 "domain": "MusicDomain", 109 "intentName": "PlayMusic", 110 "intentVersion": "1.0.1", 111 "srcEntry": "./ets/insightintents/ExtensionExecutor.ets", 112 "uiExtension": { 113 "ability": "MusicExtensionAbility" 114 } 115 } 116 ] 117} 118``` 119 120意图执行器实现： 121 122```ts 123import { InsightIntentExecutor, insightIntent, UIExtensionContentSession } from '@kit.AbilityKit'; 124 125export default class IntentExecutorImpl extends InsightIntentExecutor { 126 // 由于意图配置了uiExtension，故需要实现该接口 127 async onExecuteInUIExtensionAbility(name: string, param: Record<string, Object>, 128 pageLoader: UIExtensionContentSession): Promise<insightIntent.ExecuteResult> { 129 const result: insightIntent.ExecuteResult = { 130 code: 0 131 }; 132 return Promise.resolve(result); 133 } 134} 135``` 136 137系统入口通过UIExtensionComponent组件执行该意图。 138 139<!--Del--> 140### 意图绑定ServiceExtensionAbility组件 141 142参考[意图绑定UIAbility组件](#意图绑定uiability组件)完成工程创建。 143 144意图配置示例： 145 146```json 147{ 148 "insightIntents": [ 149 { 150 "domain": "MusicDomain", 151 "intentName": "PlayMusic", 152 "intentVersion": "1.0.1", 153 "srcEntry": "./ets/insightintents/DownloadExecutor.ets", 154 "serviceExtension": { 155 "ability": "DownloadService" 156 } 157 } 158 ] 159} 160``` 161 162意图执行器实现： 163 164```ts 165import { InsightIntentExecutor, insightIntent } from '@kit.AbilityKit'; 166 167export default class IntentExecutorImpl extends InsightIntentExecutor { 168 // 由于意图配置了serviceExtension，故需要实现该接口 169 async onExecuteInServiceExtensionAbility(name: string, 170 param: Record<string, Object>): Promise<insightIntent.ExecuteResult> { 171 const result: insightIntent.ExecuteResult = { 172 code: 0 173 }; 174 return Promise.resolve(result); 175 } 176} 177``` 178 179系统入口通过[startServiceExtensionAbility](../reference/apis-ability-kit/js-apis-inner-application-serviceExtensionContext-sys.md#serviceextensioncontextstartserviceextensionability)方式执行该意图。 180<!--DelEnd--> 181 182### 意图绑定卡片 183 184参考[意图绑定UIAbility组件](#意图绑定uiability组件)完成工程创建。 185 186意图配置示例： 187 188```json 189{ 190 "insightIntents": [ 191 { 192 "domain": "MusicDomain", 193 "intentName": "PlayMusic", 194 "intentVersion": "1.0.1", 195 "srcEntry": "./ets/insightintents/WidgetExecutor.ets", 196 "form": { 197 "ability": "PlayerWidgetAbility", 198 "formName": "mini_player" 199 } 200 } 201 ] 202} 203``` 204 205系统入口通过FormComponent组件展示卡片内容。 206 207## insight_intent.json配置文件说明 208意图配置文件insight_intent.json位于工程的"resources/base/profile"目录，用于声明意图配置信息。其中，"insightIntents"数组包含通过配置文件开发的所有意图配置信息，数组中的属性如下： 209 210| 属性名称 | 含义 | 数据类型 | 是否可缺省 | 211| --- | --- | --- | --- | 212| intentName | 表示意图名称，是意图的唯一标识。取值为首字母大写、包含字母和数字的字符串。 | 字符串 | 否 | 213| domain | 表示意图垂域名称，用于将意图按具体领域分类（例如：视频、音乐、游戏）。<!--RP1--><!--RP1End--> | 字符串 | 否 | 214| intentVersion | 表示意图版本号。当意图能力演进时，可通过版本号进行区分和管理。支持用点分隔开的三段数据序列，例如"1.0.1"。 | 字符串 | 否 | 215| srcEntry | 表示意图执行文件相对路径。取值为长度不超过127字节的字符串。 | 字符串 | 否 | 216| uiAbility | 表示意图绑定的UIAbility组件信息。包含"ability"字段和"executeMode"字段。<br>- ability：必选字段，表示UIAbility组件名称，取值与module.json5配置文件[abilities标签](../quick-start/module-configuration-file.md#abilities标签)的"name"字段保持一致。<br>- executeMode：必选字段，表示执行模式，取值范围是"foreground"和"background"。<br> - 取值为"foreground"，表示支持在UIAbility组件前台启动时执行意图逻辑。<br> - 取值为"background"，表示支持在UIAbility组件后台启动时执行意图逻辑。 | 对象 | 是 | 217| <!--DelRow--> serviceExtension | 表示意图绑定的ServiceExtensionAbility组件信息。仅包含"ability"必选字段，表示ServiceExtensionAbility组件名称，取值与module.json5配置文件[extensionAbilities标签](../quick-start/module-configuration-file.md#extensionabilities标签)的"name"字段保持一致。 | 对象 | 是 | 218| uiExtension | 表示意图绑定的UIExtensionAbility组件信息。仅包含"ability"必选字段，表示UIExtensionAbility组件名称，取值与module.json5配置文件[extensionAbilities标签](../quick-start/module-configuration-file.md#extensionabilities标签)的"name"字段保持一致。 | 对象 | 是 | 219| form | 表示意图绑定的卡片信息。包含"ability"字段和"formName"字段。<br>- ability：必选字段，表示FormExtensionAbility组件名称，取值与module.json5配置文件[extensionAbilities标签](../quick-start/module-configuration-file.md#extensionabilities标签) 的"name"字段保持一致。<br>- formName：必选字段，表示卡片名称，取值与[卡片配置](../form/arkts-ui-widget-configuration.md#卡片配置)的"name"字段保持一致。 | 对象 | 是 | 220| displayName | 表示意图显示名称。 | 字符串 | 是 | 221| displayDescription | 表示意图显示描述。 | 字符串 | 是 | 222| icon | 表示意图图标。支持网络资源和本地资源。 | 字符串 | 是 | 223| keywords | 表示意图的搜索关键字。 | 字符串数组 | 是 | 224| inputParams | 表示意图参数的数据格式声明，用于意图调用时定义入参的数据格式。 | 对象 | 是 | 225| outputParams | 表示意图调用返回结果的数据格式声明，用于定义意图调用返回结果的数据格式。 | 对象 | 是 | 226| entities | 表示意图实体定义，用于数据传递。 | 对象 | 是 | 227