在智能设备的交互中，如何准确理解并及时响应用户需求，成为提升用户体验的关键。HarmonyOS Next 的意图框架服务（Intents Kit）为这一目标提供了强大的技术支持。本文将通过一个项目实现的示例，展示如何使用意图框架服务，实现意图共享与调用的功能，推动智慧分发的应用。
一、项目背景与目标
1. 意图框架介绍
Intents Kit（意图框架服务）是HarmonyOS级的意图标准体系 ，意图连接了应用/元服务内的业务功能。意图框架能帮开发者将应用/元服务内的业务功能，智能分发到各系统入口，这个过程即智慧分发。其中系统入口包括：小艺对话、小艺搜索、小艺建议等。
系统入口、意图框架、鸿蒙生态的关系如下：
利用HarmonyOS的大模型、多维设备感知等AI能力，准确且及时地获取到用户显性、潜在意图，从而实现个性化、多模态、精准的智慧分发。
HarmonyOS、应用/元服务的交互中，意图运行方式分为意图调用和意图共享：
| 方式 | 发起者 | 定义 |
|---|---|---|
| 意图共享 | 应用/元服务 | 指应用/元服务主动向HarmonyOS共享意图，可用于HarmonyOS构建本地内容索引、学习用户的行为规律，以支持本地搜索和主动建议。意图共享包含动作和实体两个部分。动作支持完成时和将来时两种机制： - 完成时：用户意图已执行，共享的数据可用于本地搜索和系统建议。- 将来时：意图是基于用户行为预测的，共享的数据可用于本地搜索。 意图框架还支持开发者向系统进行辅助实体共享，例如位置信息等，用于场景推荐和其他智慧分发功能的增强。 |
| 意图调用 | HarmonyOS | 指HarmonyOS主动调用应用/元服务的功能。 用户在系统入口输入信息或者系统主动推荐后，系统可向应用/元服务发起意图调用，例如播放音乐、查看旅游攻略、搜索视频等。 |
2. 项目目标
本项目的目标是展示如何在HarmonyOS中利用意图框架服务实现智能分发，准确匹配用户需求。通过@kit.IntentsKit进行意图共享，使用@kit.AbilityKit的InsightIntentExecutor实现意图调用，用户的需求将能够被智能解析并传递到相关服务或应用中。
具体来说，本示例包括两个主要部分：
- 意图共享：通过意图共享机制，将用户的需求从一个模块传递到其他模块，实现跨应用的需求匹配。
- 意图调用：在共享意图之后，通过意图调用机制，将数据回传至调用端，并根据需求执行相应操作。
本示例仅支持标准系统上运行，支持设备：华为手机、华为平板。
- HarmonyOS系统：HarmonyOS NEXT Developer
- Beta1及以上。 DevEco Studio版本：DevEco Studio NEXT Developer Beta1及以上。
- HarmonyOS SDK版本：HarmonyOS NEXT Developer Beta1 SDK及以上。
二、项目实现
1. 项目目录结构
本项目的目录结构如下所示：
entry/src/main/
| --- ets
| | --- entryability
| | | --- EntryAbility.ets // 共享界面Ability
| | | --- InsightIntentExecutorImpl.ets // 意图调用逻辑
| | --- pages
| | | --- Index.ets // 共享界面UI
| | --- utils
| | | --- ... // 工具类
主要功能分布如下：
EntryAbility.ets：负责展示意图共享界面。InsightIntentExecutorImpl.ets：处理意图调用的逻辑。Index.ets：显示共享界面的UI，包含获取和展示示范数据的功能。
2. 意图共享实现
意图共享是实现智能分发的基础。我们通过@kit.IntentsKit来共享数据，确保用户需求能够跨应用或模块传递。
- 获取示范数据：用户点击获取
insightIntent示例数据后，示范数据将展示在共享界面上方的输入框内。
@kit.IntentsKit.getInsightIntents().then((data) => {// 处理获取到的示范数据updateUI(data);
});
- 共享数据：用户点击“分享意图”按钮后，数据将通过
@kit.IntentsKit.shareIntent()共享，结果将展示在共享界面的下方结果栏内。
@kit.IntentsKit.shareIntent(intentData).then((result) => {// 显示共享结果updateResult(result);
});
3. 意图调用实现
意图调用功能允许在共享的意图处理后，返回调用端并执行相应操作。通过使用小艺建议的模板卡片，我们可以展示共享的意图，并通过点击卡片触发相应的跳转和操作。
- 小艺建议展示模板卡片：我们使用音乐类模板卡片来展示共享意图。在点击卡片后，触发与共享界面跳转并执行意图调用逻辑。
@kit.AbilityKit.InsightIntentExecutor.execute(intent).then((result) => {// 处理执行结果，并展示在共享界面下方updateResult(result);
});
- SID管理：项目中还实现了SID的获取和刷新功能，确保每次操作都能获取最新的会话标识。
@kit.AbilityKit.getSid().then((sid) => {updateSid(sid);
});@kit.AbilityKit.getSidRenew().then((newSid) => {updateSid(newSid);
});
4. 实现结果
-
意图共享界面展示：用户可以查看共享意图的数据，并通过“获取示范数据”和“分享意图”按钮进行交互，数据将在共享界面的输入框和结果栏中显示。
-
意图调用逻辑展示：点击小艺建议模板卡片后，意图将被调用并返回结果，展示在共享界面的结果栏中。用户可以通过点击“获取SID”或“刷新SID”来管理会话状态。
三、核心代码解析
接下来，我们详细解析**InsightIntentExecutorImpl.ets**中的核心代码，重点展示如何通过InsightIntentExecutor类实现意图的执行与分发。
1. 引入模块和定义常量
首先，引入所需的模块：
import { Logger } from '../utils/Logger';
import { insightIntent, InsightIntentExecutor } from '@kit.AbilityKit';
import { window } from '@kit.ArkUI';
import type { BusinessError } from '@kit.BasicServicesKit';
- Logger：用于记录执行日志，帮助开发者调试和跟踪意图执行过程。
- insightIntent, InsightIntentExecutor：
InsightIntentExecutor是基类，提供了意图执行的接口方法。insightIntent包含了定义意图及其执行结果的类型。 - window：
window.WindowStage用于管理UI窗口，允许我们在界面中展示意图的执行结果。 - BusinessError：用于描述在意图执行过程中可能遇到的业务错误。
接着，我们定义常量：
private static readonly PLAY_MUSIC = 'PlayMusic';
private static readonly PLAY_MUSIC_LIST = 'PlayMusicList';
这两个常量分别代表两个不同的意图：播放单曲（PlayMusic）和播放音乐列表（PlayMusicList）。这些常量将用于后续的意图分发和执行。
2. 重写核心方法
下面，重写onExecuteInUIAbilityForegroundMode方法：
onExecuteInUIAbilityForegroundMode(name: string, param: Record<string, Object>, pageLoader: window.WindowStage):Promise<insightIntent.ExecuteResult> {Logger.info(TAG, `onExecuteInUIAbilityForegroundMode name: ${name}, param: ${JSON.stringify(param)}`);switch (name) {case InsightIntentExecutorImpl.PLAY_MUSIC:return this.playMusic(param, pageLoader);case InsightIntentExecutorImpl.PLAY_MUSIC_LIST:return this.playMusicList(param, pageLoader);default:break;}return Promise.resolve({code: -1,result: {message: 'unknown intent'}} as insightIntent.ExecuteResult)
}
-
onExecuteInUIAbilityForegroundMode：这是InsightIntentExecutor中的核心方法，负责根据意图名称（name）执行对应的操作，并返回执行结果。此方法首先记录日志，展示接收到的意图名称和参数。然后，根据意图名称分发处理逻辑。 -
播放音乐：如果接收到的意图是
PlayMusic，则调用playMusic方法，执行播放音乐的逻辑。 -
播放音乐列表：如果接收到的意图是
PlayMusicList，则调用playMusicList方法，执行播放音乐列表的逻辑。 -
未知意图：如果接收到的意图未知，返回一个错误信息。
3. 播放音乐方法实现
playMusic方法实现
private playMusic(param: Record<string, Object>, pageLoader: window.WindowStage): Promise<insightIntent.ExecuteResult> {// 处理播放音乐的逻辑Logger.info(TAG, `Playing music with parameters: ${JSON.stringify(param)}`);// 假设这是一个简单的模拟逻辑，实际中可能调用外部音乐播放APIreturn Promise.resolve({code: 0,result: {message: 'Music is playing successfully!'}});
}
playMusic：此方法模拟播放音乐的操作。在实际应用中，您可以根据传入的参数（如歌曲名称、歌手等）调用外部API来实现播放。这里，我们简单地记录日志并返回成功的结果。
playMusicList方法实现：
private playMusicList(param: Record<string, Object>, pageLoader: window.WindowStage): Promise<insightIntent.ExecuteResult> {// 处理播放音乐列表的逻辑Logger.info(TAG, `Playing music list with parameters: ${JSON.stringify(param)}`);return Promise.resolve({code: 0,result: {message: 'Music list is playing successfully!'}});
}
playMusicList：与playMusic类似，但它是用于处理音乐列表播放的逻辑。在实际应用中，您可以将多个歌曲信息传递给该方法并调用相应的播放服务。
4. 错误处理
return Promise.resolve({code: -1,result: {message: 'unknown intent'}
} as insightIntent.ExecuteResult);
如果接收到一个未知的意图，该方法将返回一个错误信息，表示无法识别该意图。
四、效果预览
1. 意图共享
共享界面展示：
按获取insightIntents获取insightIntent示例数据，获取的示范数据将显示在共享界面上方输入框内。
按shareIntent进行数据共享，并在共享界面下方的结果栏内获取意图共享结果。
2. 意图调用
待共享的意图完成处理后，将会在小艺建议的卡片内展示共享的意图，点击展示的对应卡片，执行意图调用逻辑。
使用小艺建议模板卡片实现意图调用
小艺建议展示模板卡片，此项目内使用音乐类模板卡片。
点击模板卡片，按照意图注册配置内逻辑，执行对应跳转。此项目内跳转至共享界面，并在共享界面下方结果栏内展示意图调用回传参数
3. SID获取
点击getSid获取SID，并在结果栏内展示（优先获取缓存）。
点击getSidRenew强制获取新的SID，并在结果栏内展示。
五、总结
通过本项目，我们展示了如何利用HarmonyOS的意图框架服务（Intents Kit）实现智能分发功能，精准理解并响应用户需求。通过意图共享和调用机制，用户的需求得以在不同应用和模块之间流转，进而提供更加个性化、智能化的服务。这种基于AI和系统感知的智慧分发，极大提升了用户交互体验，并为开发者提供了更加灵活和高效的应用开发方式。
通过本示例，开发者可以学习到如何在实际项目中使用意图框架服务，并将其应用于自己的HarmonyOS应用中，打造更加智能、个性化的用户体验。
