从鸿蒙 AI 聊天 Demo 学习 ArkUI V2：第一天上手记录

前言

最近正式接触 HarmonyOS NEXT 与 ArkUI V2。

公司项目中已有一套 AI 聊天业务，面对全新框架。我没有选择直接死啃官方文档，而是采用 业务驱动 + Demo 验证 的方式学习。怎么说呢，

今天的任务主要有两件事：

• 拆解 AI 聊天业务整体数据流
• 自己动手实现 ArkUI V2 Demo。练习主要语法

下面内容记录了我在学习过程中的关键收获与痛点。

一、先理解 AI 聊天业务整体结构

痛点：刚接触项目时页面层级深、Builder 众多、状态繁杂，根本不知道从哪里下手。

ChatPage
├── Provider
├── ChatConfig
├── Builder
│ ▼ ChatComponent
│ ├── vm
│ ├── InputBar
│ ├── MessageList
│ └── Controller

把这些碎片化的模块视作「功能块」而非「代码堆」，可以快速定位自己需要实现或调试的部分。

二、真正理解 AI 聊天数据流

痛点：面对「使用者输入 → 发送 → AI 返回」的流程。我常常在状态同步上踩坑，导致 UI 不刷新或消息丢失。按理说，

整体流程

使用者输入
↓ 输入框双向绑定状态
↓ 点击发送
↓ Controller.sendMessage
↓ 创建使用者消息 → push 到 chatHistory
↓ 请求 AI
↓ 流式返回 → push AI 消息 / 卡片
↓ MessageList 自动刷新

本质：整个聊天场景就是「状态驱动 UI」。唯一需要关注的状态就是 chatHistory。

三、vm终于看懂了

痛点：vmviewModel 这类概念一直模糊不清，导致状态管理混乱。其实，

vm 的本质是统一状态中心

• 输入框修改：vm.userInput = 'Hello'
• 消息列表读取：vm.chatHistory
• Controller 操作：push 到 vm.chatHistory
• MessageList 自动刷新： 因为它监听了同一个响应式对象。

This is essentially a reactive shared state mechanism.

四、Builder 插槽——解耦 UI 与业务的关键利器

痛点：项目里出现大量 xxxBuilder。完全不懂它们的作用，一度以为是「自定义控件」而浪费大量时间去阅读源码。

再看本质。UI 插槽机制

外层页面
├── 普通卡片 Builder
├── 混合卡片 Builder
└── Loading Builder
聊天组件根据公开信息类型调用不同 Builder 渲染 UI

The chat component itself only cares about:

• 状态管理
• 消息流转
• 生命周期控制
• 消息调度逻辑

The actual UI is injected from outside—just like Vue slots or React render props.

五、@BuilderParam——把 UI 当参数传递的技巧

痛点：@BuilderParam 看起来像普通装饰器，却不知道何时使用，导致组件复用受限。

@BuilderParam content: => void
// “外部传一段 UI 给我”
...
this.content // 渲染外部传进来的 UI

This design enables clean separation of logic and presentation,especially for large reusable components.

六、正式上手 ArkUI V2 基础语法

• @ComponentV2 — 声明组件入口
• @Local — 定义组件内部响应式属性
• @Param — 接收父组件传值
• @ObservedV2 — 监听属性变化
• @Trace — 调试生命周期
• @Builder / @BuilderParam — 实现插槽化 UI

@Local 示例

@Local keyword: string = ''

@Param 示例

@Param title: string = ''
// 父组件调用方式：
Child

@Builder & @BuilderParam 示例

@BuilderProductRow { /* …*/ }
@BuilderParam content: => void
// 调用：
this.content

七、HarmonyOS 布局程序快速上手

痛点："ColumnRowStack" 看起来抽象难懂，导致布局总是写错层级。

• COLUMN： 上下垂直排列。 例：Column { Text;Text }

ROW: 左右水平排列。例：

STACK: 图层叠加后面的覆盖前面的。例：

ts

Stack { Image Text }

上述代码中。Text 会覆盖在 Image 上方，实现浮层效果。

---

九 、商品管理 Demo 实战

为了巩固 ArkUI V2 的使用，我实现了一个完整的商品管理 Demo。说到功能包括，

• 商品列表展示
• 搜索过滤
• 新增/删除/修改商品
• 手势交互
• 生命周期演示

关键代码片段

ts @ObservedV4 // 观察数据变化自动刷新 UI class ProductPage extends Component { @Local products: Array = @Local filterKey: string = ''

// 搜索过滤逻辑 get filteredProducts { return this.products.filter) }

// 长按删除手势 onLongPress { this.products = this.products.filter } }

十 、Diff 与 key 的深度剖析

痛点回顾的观点是。

“数据变化却不触发 UI 更新” 是新手最常见的问题。根源在于 ForEach 的 key 没有正确设置。

正确使用 key 的原则

ts ForEach => `${item.id}-${item.name}`)

只要 key 因为数据唯一性变化。就会强制框架重新渲染对应节点，避免旧节点复用导致的 UI 静止。

---

十一 、Gesture 手势交互入门

说到常见手势示例。

ts .button.gesture)

配合列表项使用，可实现 长按删除 等交互，让移动端体验更丰富。

十二 、已掌握知识点概览

分类	内容
ArkUI V2	@ComponentV2、@Local、@Param、@ObservedV2、@Trace、@Builder、@BuilderParam
布局	Column、Row、Stack
列表	ForEach、Diff、key机制
生命周期	aboutToAppear、aboutToDisappear
手势	LongPressGesture
状态驱动	vm、chatHistory、响应式刷新

十三 、最大的感受

再看痛点。

1️⃣ 官方文档虽全，但缺乏业务场景联想，容易产生“学了却不会用”的尴尬。2️⃣ 面对复杂页面时一味追逐 API，会陷入“找不到入口”的循环。

我的实战方法的观点是。

业务需求 → 遇到未知 → 查文档 → 编写最小 Demo 验证 → 回归业务

这种闭环学习让概念与实践同步提高，大幅缩短摸索时间。

十四 、接下来计划

• 深入聊天消息列表渲染细节
• 探索 Drawer 与 transition 动画实现
• Builder 的嵌套组合方案
• 学习路由程序与 MVVM 架构完整落地

虽然还有许多细节待攻克，但已经掌握了：

• 状态如何流动
• UI 如何响应更新
• 组件之间如何通信还有 Builder 如何解耦

这标志着我正式迈入 HarmonyOS 开发的大门。

---