HarmonyOS 6 实战：首页标题栏右上角智能体入口接入指南

在 HarmonyOS 6 中，为应用首页标题栏右上角接入智能体入口，可以显著提升用户交互体验。本文基于一个真实项目，详解从初始化、能力检测到组件渲染、事件清理的完整流程，并提供最小接入步骤，助你快速集成。

功能概述与效果

这个接入点位于首页标题栏最右侧，具备三个鲜明特点：位置固定，始终显示在应用标题右边；按能力显示，仅在设备支持且控制器初始化成功时才渲染；生命周期完整，页面进入时初始化，离开时移除监听。如下图所示：

核心逻辑集中在 entry/src/main/ets/pages/MainMenu.ets 文件中，页面自身完成了状态声明、能力检测、组件渲染和事件解绑，结构清晰，非常适合作为独立教程。

引入智能体组件相关能力

在首页文件顶部，需要引入三项核心内容：

import { common } from '@kit.AbilityKit'
import { BusinessError } from '@kit.BasicServicesKit'
import { FunctionComponent, FunctionController } from '@kit.AgentFrameworkKit'

• FunctionComponent：真正显示在页面上的智能体入口组件。
• FunctionController：负责控制组件，并监听打开、关闭等事件。
• common.UIAbilityContext：能力检测时所需的上下文对象。

这里直接使用系统 Kit，无需额外添加第三方依赖，保证了项目的轻量性和兼容性。

页面内声明状态与控制器

在 MainMenu 页面中，与智能体相关的成员只有三个：

@State isAgentSupport: boolean = false
private agentController: FunctionController | null = null
private agentId: string = 'your_agent_id_here'

• isAgentSupport：标记当前设备和环境是否支持该智能体能力。
• agentController：智能体组件的控制器实例。
• agentId：接入的智能体标识（占位符，需替换为实际 ID）。

⚠️ 在你的项目中，只需将 your_agent_id_here 替换为真实的智能体 ID 即可。这种设计使得状态管理非常集中，便于后续维护和扩展。

页面出现时初始化智能体能力

该功能并未在页面创建时直接渲染，而是先进行设备判断，再决定是否初始化：

aboutToAppear(): void {
const is2In1 = is2In1Device()
if (!is2In1) {
this.agentController = new FunctionController()
this.initAgentListeners()
this.checkAgentSupport()
} else {
this.agentController = null
this.isAgentSupport = false
hilog.info(DOMAIN, TAG, 'Agent entry disabled on 2in1 device')
}
}

这里有两个关键点：

1. 设备适配：代码明确对 2in1 做了排除处理。如果当前设备不适合该能力，直接关闭入口，避免无用渲染。
2. 初始化顺序：固定为“创建控制器 → 注册监听事件 → 检查能力支持”。这样只有在能力确认可用后，页面才会显示右上角入口，避免空白占位或点击无响应。

这种按需初始化的模式，在 TypeScript 和 JavaScript 项目中都非常常见，能够有效提升性能表现。

补全打开与关闭事件监听

当前实现为智能体组件添加了两个事件监听：

private initAgentListeners(): void {
this.agentController?.on('agentDialogOpened', this.onAgentOpenedCallback)
this.agentController?.on('agentDialogClosed', this.onAgentClosedCallback)
}
private readonly onAgentOpenedCallback = () => {
hilog.info(DOMAIN, TAG, 'agent dialog opened callback')
}
private readonly onAgentClosedCallback = () => {
hilog.info(DOMAIN, TAG, 'agent dialog closed callback')
}

这部分逻辑虽简单，但非常必要。智能体入口往往不仅是一个普通按钮，它可能拉起对话框或服务面板。接入监听后，后续需要统计打开次数、补充埋点、做页面联动时，都可以直接在这两个回调中扩展。当前项目中，这两个回调先只做日志记录，属于稳妥的写法：先接通链路，再逐步增加业务逻辑。

✅ 渲染前做能力检测

是否显示入口，并非靠硬编码布尔值，而是通过 checkAgentSupport() 动态判断：

private async checkAgentSupport(): Promise<void> {try {const context = this.getUIContext()?.getHostContext() as common.UIAbilityContext | undefinedif (!context) {this.isAgentSupport = falsehilog.warn(DOMAIN, TAG, 'UIAbilityContext is unavailable when checking agent support')return}if (!this.agentController) {this.isAgentSupport = falsereturn}this.isAgentSupport = await this.agentController.isAgentSupport(context, this.agentId)hilog.info(DOMAIN, TAG, `Agent support: ${this.isAgentSupport}`)} catch (error) {const err = error as BusinessErrorthis.isAgentSupport = falsehilog.error(DOMAIN, TAG, `Failed to check agent support: code=${err.code}, message=${err.message}`)}}

建议重点理解以下三点：

• 检测依赖页面上下文：这里不是直接调用 isAgentSupport()，而是先从页面中获取 UIAbilityContext。若上下文拿不到，立即返回，并将状态设为 false。
• 检测结果直接驱动 UI：isAgentSupport 是 @State 变量，检测完成后页面自动刷新，无需手动控制标题栏重绘。
• 错误场景兜底：若检测异常，当前实现会将 isAgentSupport 置为 false 并记录错误日志。这样接入失败时，页面仍可正常使用，不会影响首页其他功能。

类似的能力检测模式，在 C++ 和 Go 的插件化架构中也经常出现，体现了良好的容错设计。

️ 将智能体入口放到标题栏右上角

UI 布局非常直接：左侧是应用标题，右侧是智能体入口。关键代码如下：

Row({ space: 12 }) {
Column() {
Text('左左右右')
.fontSize(36)
.fontWeight(FontWeight.Bold)
.fontColor('#FF6B35')
}
.height(44)
.justifyContent(FlexAlign.Center)
.alignItems(HorizontalAlign.Start)
.layoutWeight(1)
if (this.isAgentSupport && this.agentController) {
Column() {
FunctionComponent({
agentId: this.agentId,
onError: (err: BusinessError) => {
hilog.error(DOMAIN, TAG, `Agent component error: code=${err.code}, message=${err.message}`)
},
controller: this.agentController
})
}
.padding(6)
.backgroundColor(getThemeManager().isDark() ? '#1F2A3A' : '#FFFFFF')
.borderRadius(20)
.shadow({ radius: 6, color: '#00000014', offsetY: 2 })
}
}
.width('90%')
.alignItems(VerticalAlign.Center)
.padding({ top: 30, bottom: 20 })

可以从两个层面理解：

• 布局层：左侧标题区域使用了 .layoutWeight(1)，右侧智能体入口自然被“挤”到最右边。外层 Row({ space: 12 }) 控制标题和入口之间的间距，无需额外编写 Blank()，直接用 layoutWeight(1) 就足够。
• 组件层：真正的智能体接入只有一行核心代码：

FunctionComponent({
agentId: this.agentId,
onError: (err: BusinessError) => {
hilog.error(DOMAIN, TAG, `Agent component error: code=${err.code}, message=${err.message}`)
},
controller: this.agentController
})

最重要的三个参数是：

• agentId：指定接入哪个智能体。
• controller：传入前面创建好的控制器。
• onError：兜底处理组件异常。

外层用 Column 包裹，并补上 padding、圆角和阴影，使右上角入口更像一个完整的小卡片，而不是生硬地贴在标题旁边。

页面离开时移除监听

这个细节很容易被忽略，但当前项目已经完善：

aboutToDisappear(): void {
this.agentController?.off('agentDialogOpened')
this.agentController?.off('agentDialogClosed')
}

为什么要写这一步？原因很简单：

• 首页可能被重复进入，如果监听不解绑，重复注册后可能出现多次回调。
• 长期来看，不利于页面生命周期管理。

所以，完整接入不只是“显示出来”，还要把退出阶段的清理动作一起做完。在 Python 的上下文管理器或 JavaScript 的 useEffect 清理函数中，这种模式同样被广泛使用。

最小接入步骤总结

如果你也要在 HarmonyOS 页面右上角添加智能体入口，最小接入步骤如下：

1. 在页面中引入 FunctionComponent、FunctionController。
2. 声明 isAgentSupport、agentController、agentId。
3. 在 aboutToAppear() 中创建控制器并调用 checkAgentSupport()。
4. 在标题栏右侧通过 FunctionComponent 渲染入口。
5. 在 aboutToDisappear() 中移除监听。

按照这套结构接入，逻辑完整且不会把首页写乱。 [AFFILIATE_SLOT_1]

小结

首页右上角智能体接入，本质上只做了三件事：

• 先判断能不能用：通过 isAgentSupport() 控制显隐。
• 再把组件放到标题栏右侧：通过 layoutWeight(1) 留出右侧空间。
• 最后把生命周期补完整：进入时初始化，离开时解绑事件。

这类功能看似只是页面右上角多了一个入口，但真正稳定的关键，不在于“放上去”，而在于能力检测、错误兜底、事件监听和退出清理都要一起做好。当前项目中的实现已经串通了这条链路，直接按此结构复用即可。 [AFFILIATE_SLOT_2]