React开发者快速上手HarmonyOS：ArkUI声明式UI核心实战

很多从 React 转过来做 HarmonyOS 的朋友，第一次打开 DevEco Studio 看到 ArkUI 的代码时，第一反应往往是“这长得也太不像 React 了”。组件不是<div>标签，样式不是 className，状态管理也没有 hooks。但只要你把官方文档里那些“装饰器”和“链式调用”的壳扒掉，底层那套“状态驱动 UI、单向数据流、组件化复用”的思路，就是 React 声明式编程那套东西。

这篇是“玩转 React”系列开源教程的第三篇，前两篇我们搞清楚了 React 本身的核心机制，这一篇开始正式切换到 HarmonyOS 应用开发，目标只有一个：用 React 开发者的思维，快速拿下 ArkUI 声明式 UI 的入门。不讲虚的，直接拆核心概念、写实战 Demo、列踩坑记录，看完你就能自己动手写一个能跑的 HarmonyOS 应用页面。

1.1 这篇教程能解决什么问题

如果你正在从 Web/React 转鸿蒙开发，多半会遇到下面几个困惑：

• 看着 ArkUI 的语法一脸懵，不知道@State、@Component这些装饰器是干嘛的。
• 脑子里有 React 的 component 思维，但不知道在 ArkUI 里怎么组织页面和复用组件。
• 写了个界面，发现数据变更了 UI 不刷新，搞不清楚状态管理的边界。
• 想做一个列表页 + 表单交互的小应用，但不知道从哪下手。

这篇教程就是冲着这些痛点来的。我会先用“React 老哥都能听懂”的方式把 ArkUI 的核心机制讲明白，然后带着你从零写一个“今日待办”应用，最后把我实际开发中踩过的坑和排查思路整理成速查表。适合刚接触 HarmonyOS 开发、有 React 或其他声明式框架基础的开发者，就算你没有 React 基础，只要能理解“页面 = f(状态)”这句话，也能跟得下来。

1. 为什么 HarmonyOS 非要搞一套 ArkUI 声明式 UI

先聊点背景，不然你没法理解后面那些设计选择。HarmonyOS 从诞生那天起，就面临一个很现实的问题：UI 层到底怎么做？早期 HarmonyOS 用的其实是类 Java 的 UI 框架，写代码的体验大家心里都有数，控件多、回调嵌套多、状态一复杂就崩。华为后来痛定思痛，在 API 7 之后全面转向了声明式 UI 范式，也就是今天你看到的 ArkUI。

1.1 声明式和命令式的本质区别

声明式和命令式的区别，我用一个生活化的例子给你讲透。

命令式就像你下馆子直接冲进后厨，跟厨师说：“你先热锅，倒油，油温七成热的时候把洋葱放进去，炒三十秒，再加牛肉……”每一步怎么做你都交代得清清楚楚，锅铲动一下你管一下。这就是命令式，你关心过程，每一条指令都在操作“怎么一步步完成”。

声明式则是另一种方式：你坐在餐桌上，跟服务员说“我要一份洋葱炒牛肉”，剩下的交给厨房。你只管描述“我要什么”，至于怎么热锅、怎么颠勺，那是框架的事。你只关心结果，不关心过程。

放到 UI 开发里，命令式就是findViewById()、设置setText()、添加setOnClickListener()，每一步都在手动操作控件。声明式则是“我这个组件长什么样，取决于当前数据是什么”，数据变了，UI 自动跟着变。

ArkUI 就是典型的声明式框架。你在build()方法里描述“当前状态下 UI 应该长什么样”，框架负责把这份描述变成真实的界面。而 React 也是声明式框架，render()方法根据 state 返回 UI 描述，React 负责更新 DOM。两者的血缘关系在这里就体现出来了。

1.2 ArkUI 和 React 的底层思想对比

我整理了一张对照表，方便你快速建立认知。这张表你贴在工位上，写代码时经常用得到。

你会发现，ArkUI 在“声明式”这条路上走得更彻底。React 虽然有 hooks 和函数式组件，但状态更新背后还有 reconcile、diff、commit 这些复杂的调度机制。ArkUI 的状态管理则直接跟 UI 绑定，@State变量一旦变化，框架直接精准刷新依赖它的组件，没有虚拟 DOM 那一层中间环节。这也是 ArkUI 在性能上的一大底气。

1.3 快速上手：ArkUI 最小可运行结构

看再多理论不如跑一个 Hello World。一个最简单的 ArkUI 页面长这样，你新建一个 HarmonyOS 工程时，默认生成的Index.ets文件里就是这套结构：

// entry/src/main/ets/pages/Index.ets @Entry @Component struct Index { @State message: string = 'Hello ArkUI' build() { Row() { Column() { Text(this.message) .fontSize(50) .fontWeight(FontWeight.Bold) } .width('100%') } .height('100%') } }

这代码乍看奇怪，拆开看就清晰了。

@Entry表示这是页面的入口组件，一个页面中只能有一个。@Component表示这是一个可复用的自定义组件。struct Index是组件本体，里面的@State message是状态变量，build()方法返回 UI 描述。

Row和Column是布局容器，有点像 CSS 里的 flexbox 布局，Row 是横向排列，Column 是纵向排列。Text 就是文本组件，后面的.fontSize(50)、.fontWeight(FontWeight.Bold)都是链式属性调用，相当于给 Text 设置 CSS 样式。

React 老哥看到Text(this.message)应该很亲切，这不就是{this.message}的另一种写法嘛。对，就是这回事。

2. 装饰器体系：ArkUI 最核心的状态驱动基建

ArkUI 和 React 最不一样的地方，就在这堆装饰器上。React 里你想让一个组件响应数据变化，要么 useState、要么 useReducer、要么用 MobX/Redux 这些外部库；ArkUI 则把这些能力直接内建到了语言层，用装饰器来声明变量和 UI 的关系。

2.1 @State：组件内部状态

@State是组件内部状态，等价于 React 的useState。它有一个重要特性：被@State修饰的变量，在值发生变化时，会自动触发依赖该变量的 UI 部分重新渲染。

@Entry @Component struct CounterPage { @State count: number = 0 build() { Column({ space: 20 }) { Text(`当前计数：${this.count}`) .fontSize(24) Button('点击 +1') .onClick(() => { this.count++ }) } .width('100%') .padding(20) } }

这里this.count++执行之后，Text组件会自动显示最新值，完全不用你手动操作 DOM。你不需要在任何地方调用类似setData()或者update()的方法，变量一变，UI 自己动起来。

这是整个 ArkUI 声明式 UI 的地基。后面的所有内容，本质上都是围绕“状态变化如何驱动 UI 刷新”这个核心展开的。

2.2 @Prop 与 @Link：父子组件数据互通

实际开发中，你不会把所有内容都堆在一个组件里。一个页面拆成多个自定义组件，父子之间怎么传数据？

父传子，用@Prop。它相当于 React 的 props，但有一个区别：@Prop修饰的变量是单向的，父组件传给子组件之后，子组件内部如果要改，必须通过事件回调通知父组件改，或者让父组件重新传值。

@Component struct TodoItem { @Prop title: string @Prop done: boolean build() { Row({ space: 10 }) { if (this.done) { Text('✓ ' + this.title) } else { Text('○ ' + this.title) } } } }

子传父，或者需要父子双向同步时，用@Link。@Link修饰的变量会和父组件中对应的状态建立双向绑定，两边任意一边修改，另一边都会同步更新。

@Component struct TodoItem { @Link done: boolean build() { Checkbox() .select(this.done) .onChange((value: boolean) => { this.done = value // 直接修改，父组件里对应的状态同步更新 }) } }

这里面有个很容易踩的坑：@Prop只支持一层拷贝，如果你传进来的对象内部嵌套了好几层class对象，修改深层的属性，@Prop不会感知到变化。这种情况得用@Observed + @ObjectLink组合解决，后面问题排查部分我会细说。

2.3 @Builder：复用 UI 片段的利器

@Builder是 ArkUI 独有的一种函数式 UI 复用机制，你可以把它理解为 React 里的渲染函数或者 JSX 片段。当一个组件内部有多处相同结构的 UI 时，用@Builder抽出来，避免一处代码粘五遍。

@Component struct DemoPage { @Builder itemRow(title: string, desc: string) { Row({ space: 12 }) { Text(title) .fontSize(18) .fontWeight(FontWeight.Bold) Text(desc) .fontSize(14) .fontColor('#888') } .padding(16) .width('100%') .backgroundColor('#F5F5F5') .borderRadius(8) .margin({ bottom: 8 }) } build() { Column() { this.itemRow('标题一', '这是描述文本') this.itemRow('标题二', '这是描述文本') this.itemRow('标题三', '这是描述文本') } .padding(16) } }

这个特性好处是：UI 结构复用逻辑清晰，代码量肉眼可见地减少，而且@Builder还可以传参数，动态控制渲染内容，非常灵活。

2.4 build() 方法里的组件语法

ArkUI 的build()方法里不是 JSX，但它有自己的一套规则，理解了这套规则，看任何 ArkUI 代码都不再发怵。

组件通过构造方法创建，比如Text('字符串')、Button('点击')、Image(this.imgUrl)。组件属性用链式调用设置，比如.fontSize()、.width()、.height()、.onClick()。事件回调用小箭头函数传入，比如.onClick(() => { ... })。

条件渲染直接用if / else，不需要像 React 那样写三元表达式或逻辑与。列表渲染用ForEach组件，遍历数组生成一组子组件。ForEach接收两个参数：数据源数组和 item 渲染函数，第二个参数是item索引和当前数组对象引用。

我见过不少从 React 转过来的朋友在build()里写map()，结果编译直接报错。ArkUI 的build()里不能用任意 JS 表达式，必须用ForEach这种声明式组件语法。这个差异记住之后，能帮你少报 20 个错。

3. 实战：从零编写一个“今日待办”应用

理论铺垫完毕，下面进入正题。我们做一个带输入、添加、勾选完成、删除、统计功能的待办应用。麻雀虽小五脏俱全，它能覆盖 ArkUI 入门必须掌握的所有核心知识点。

3.1 需求拆解与页面结构设计

页面需要分成三个区域：顶部的标题和统计信息、中间的可输入区域、下面的待办列表。

• 标题区：显示“今日待办”和未完成数量。
• 输入区：一个TextInput输入框 + 一个“添加”按钮。
• 列表区：用ForEach遍历待办数组，每项显示一个Checkbox勾选框、待办文本、删除按钮。

组件拆分上，我会把待办列表项抽成一个独立的TodoItem子组件，父组件（页面主体）负责维护整个列表的状态，子组件只管渲染单行待办并通过事件回调把操作结果抛给父组件。这套交互方式跟 React 的“状态提升”如出一辙。

3.2 待办数据模型定义

先定义数据类型。ArkTS（HarmonyOS 的 TypeScript 超集）里定义 class：

class Todo { id: number = 0 title: string = '' done: boolean = false constructor(id: number, title: string, done: boolean) { this.id = id this.title = title this.done = done } }

用 class 而不是 interface 的原因在于：ArkUI 的状态管理对 class 类型有特殊的观测能力，配合装饰器能精确追踪属性变化。用 interface 定义的纯结构体，在某些场景下状态更新会不到位。这个属于个人实践中总结的经验，非官方强制要求。

3.3 列表数据状态管理与增删操作

页面主体的状态变量：

@Entry @Component struct TodoApp { @State todos: Todo[] = [] @State inputValue: string = '' private nextId: number = 1 }

添加待办：读取输入框的值，非空则追加到数组。注意这里有一个 ArkUI 状态管理的经典细节：你不能用this.todos.push(newTodo)这种原生数组方法来更新被@State修饰的数组。为什么？因为@State监听的是变量引用变化，不是数组内部变化。你 push 之后，数组的引用没有变，框架感知不到数据变化，UI 不刷新。

正确做法是重新创建一个数组，让引用发生变化：

addTodo() { const title = this.inputValue.trim() if (!title) { return } const newTodo = new Todo(this.nextId++, title, false) this.todos = [...this.todos, newTodo] // 创建新数组，触发 UI 刷新 this.inputValue = '' }

删除待办同理，用filter或者splice之后重建数组，反正要让@State记住“数组变了”：

removeTodo(id: number) { this.todos = this.todos.filter(item => item.id !== id) }

勾选完成状态的切换，我放在子组件里通过@Link双向绑定实现。子组件修改done属性时，父组件数组里对应对象的状态也会同步变化。

不过这里有个隐藏问题：Todo是数组里的对象，子组件用@Link绑定的是todos数组里某个元素的属性。ArkUI 新版本（API 12+）对@Link绑定数组元素的属性做了支持，旧版本里这么写可能是失效的。所以稳妥起见，我换了方案：子组件不直接绑定父组件数据结构，而是通过回调函数通知父组件修改。

3.4 子组件 TodoItem 设计与事件回调

子组件只负责渲染，不直接修改数据：

@Component struct TodoItem { @Prop title: string @Prop done: boolean onToggle?: (newDone: boolean) => void onDelete?: () => void build() { Row({ space: 12 }) { Checkbox() .select(this.done) .onChange((value: boolean) => { if (this.onToggle) { this.onToggle(value) } }) Text(this.title) .fontSize(16) .decoration({ type: this.done ? TextDecorationType.LineThrough : TextDecorationType.None, color: '#999' }) .fontColor(this.done ? '#999' : '#333') Blank() Button('删除') .fontSize(12) .backgroundColor('#E84026') .onClick(() => { if (this.onDelete) { this.onDelete() } }) } .padding(12) .width('100%') .backgroundColor('#FFFFFF') .borderRadius(8) .margin({ bottom: 8 }) } }

父组件在ForEach里声明子组件时，把回调函数传进去：

ForEach(this.todos, (item: Todo) => { TodoItem({ title: item.title, done: item.done, onToggle: (newDone: boolean) => { item.done = newDone this.todos = this.todos.map(t => t.id === item.id ? item : t) }, onDelete: () => { this.removeTodo(item.id) } }) }, item => `${item.id}`)

这里onToggle里我把item.done改了之后，重新给this.todos赋了一个新数组，目的就是为了让@State感知到数组变化，从而驱动 UI 刷新。

ForEach的第三个参数是 key 生成函数，我传了item.id。这个 key 的作用跟 React 里列表渲染时key={item.id}完全一样，用来帮助框架在列表增删时精准定位需要更新的节点，避免整个列表全部重渲染。不给 key 或者用不稳定的 key（比如数组索引），在列表频繁操作时会出现状态错乱或闪烁的问题。

3.5 输入区实现与键盘交互

输入区是 TextInput 组件，绑定的还是@State inputValue。注意 TextInput 的onChange事件会持续触发，每次输入变化都更新状态变量：

TextInput({ placeholder: '输入待办内容', text: this.inputValue }) .layoutWeight(1) .height(40) .backgroundColor('#F0F0F0') .borderRadius(8) .padding({ left: 12, right: 12 }) .onChange((value: string) => { this.inputValue = value }) Button('添加') .height(40) .margin({ left: 8 }) .onClick(() => { this.addTodo() })

layoutWeight(1)的作用是让输入框占满剩余宽度，按钮只占自身内容宽度。这相当于 CSS flex 布局里的flex: 1。

键盘交互里有一个细节：在模拟器里，输入法弹出后会遮挡页面底部内容，输入框可能被盖住。解决办法是给页面最外层容器加上.expandSafeArea([SafeAreaType.KEYBOARD])或者用.keyboardAvoidMode(KeyboardAvoidMode.OFFSET)调整避让行为，具体看你的 HarmonyOS 版本支持。这个坑调试的时候很隐蔽，不留意根本想不到是键盘遮挡问题。

3.6 完整页面代码与效果预览

把页面主体代码拼在一起，完整的功能页面就出来了：

@Entry @Component struct TodoApp { @State todos: Todo[] = [] @State inputValue: string = '' private nextId: number = 1 get unfinishedCount(): number { return this.todos.filter(item => !item.done).length } addTodo() { const title = this.inputValue.trim() if (!title) { return } const newTodo = new Todo(this.nextId++, title, false) this.todos = [...this.todos, newTodo] this.inputValue = '' } removeTodo(id: number) { this.todos = this.todos.filter(item => item.id !== id) } build() { Column() { Row() { Text('今日待办') .fontSize(24) .fontWeight(FontWeight.Bold) Blank() Text(`${this.unfinishedCount} 项未完成`) .fontSize(14) .fontColor('#888') } .width('100%') .padding({ top: 16, bottom: 16 }) Row() { TextInput({ placeholder: '输入待办内容', text: this.inputValue }) .layoutWeight(1) .height(40) .backgroundColor('#F0F0F0') .borderRadius(8) .padding({ left: 12, right: 12 }) .onChange((value: string) => { this.inputValue = value }) Button('添加') .height(40) .margin({ left: 8 }) .onClick(() => { this.addTodo() }) } .width('100%') .margin({ bottom: 16 }) List() { ForEach(this.todos, (item: Todo) => { ListItem() { TodoItem({ title: item.title, done: item.done, onToggle: (newDone: boolean) => { item.done = newDone this.todos = this.todos.map(t => t.id === item.id ? item : t) }, onDelete: () => { this.removeTodo(item.id) } }) } }, item => `${item.id}`) } .layoutWeight(1) .width('100%') if (this.todos.length === 0) { Text('暂无待办，赶紧添加一条吧') .fontSize(14) .fontColor('#BBB') .margin({ top: 40 }) } } .width('100%') .height('100%') .padding({ left: 16, right: 16 }) } }

这里我用List+ListItem包裹ForEach。性能和滚动体验上，List天然支持滚动，而且ListItem在列表数据多的时候有复用优化机制，数据量大了也不会卡顿。你要是用Column硬怼几十条数据，滚动和渲染性能都会有肉眼可见的下降。

运行起来的效果：顶部显示标题和未完成数量，中间是输入框和添加按钮，下面按顺序排列待办项。每项左侧是可勾选的复选框，勾选后文字出现删除线并变灰，右侧是删除按钮。待办做完了可以点复选框勾掉，不想要的可以点删除清掉。

3.7 从 React 视角看这个待办应用的架构

如果你把这个完整的 ArkUI 代码跟一个 React 实现做对比，结构上的翻译关系非常清晰。

React 的TodoList组件对应 ArkUI 的TodoItem子组件。React 的useState<Todo[]>([])对应 ArkUI 的@State todos: Todo[]。React 的onChange={e => setInputValue(e.target.value)}对应 ArkUI 的.onChange((value: string) => { this.inputValue = value })。React 的setTodos([...prev, newTodo])对应 ArkUI 的this.todos = [...this.todos, newTodo]。React 的todos.map(item => <TodoItem key={item.id} .../>)对应 ArkUI 的ForEach(this.todos, item => { TodoItem(...) }, item => item.id)。

思想完全一致，只是表达语法换了外套。你既然已经在“玩转 React”系列前两篇里吃透了 React 的模式，到 ArkUI 这里唯一要做的事情，就是熟悉这些语法糖和状态管理的边界条件。

4. 常见问题与排查技巧实录

我在这套待办应用和周边项目上踩过不少坑，每一个都是从“编译不过/运行不对”到“终于搞明白”的过程。挑几个高频问题列出来，给你省点时间。

4.1 常见问题速查表

4.2 踩坑一：@State 数组内容变更，UI 纹丝不动

这是 ArkUI 新手最经典的一个坑。原因我刚才提到过：@State是浅观察，它只知道“变量本身的引用有没有变”，不知道“变量内部的内容有没有变”。你push、splice或者修改数组里某个对象的属性，引用都没变，所以 UI 不会刷新。

我曾经在这个问题上卡了大半天，老是觉得 UI 怎么不更新，仔细排查才发现是this.todos.push()的问题。换成创建新数组整体赋值之后，所有问题迎刃而解。

4.3 踩坑二：@Prop 传入复杂对象，深层次修改无响应

@Prop的多层嵌套问题在开发中非常容易出现。

@Prop本质上是一个单向的“快照”传值，父组件状态变化后会重新把值推给子组件，但子组件内部修改这个对象时，ArkUI 并不知道父组件的数据也变了。尤其是在对象嵌套场景下，@Prop对深层次属性变化的追踪能力非常有限。

如果你确实需要父子组件同步一个多层嵌套对象，建议用@Observed修饰 class，子组件用@ObjectLink接收。@Observed的作用是让框架能观测到 class 实例内部属性的变化，@ObjectLink则让子组件精确绑定到这个被观测对象的某个属性上。这套组合拳，才是处理复杂数据结构的正解。

4.4 踩坑三：ForEach 不写 key，列表状态错乱

在 React 里写列表不写 key，控制台会警告，但功能大概率还能用。在 ArkUI 里，ForEach 不写 key，问题是实打实的，尤其是在列表项有状态的情况下。

举个例子，待办列表里如果每个 TodoItem 内部有@State管理的局部 UI 状态（比如展开/折叠、编辑模式），你删掉一条后，后面的项可能会错误地保留被删项的状态。这个跟 React 列表 diff 算法里的 key 作用是一个道理。反正 Reactive 生态里，写列表不写 key 就是给自己埋雷。

4.5 踩坑四：build() 方法里到处塞表达式

从 React 转过来的朋友，习惯了在 JSX 里写{arr.map()}、{condition && ...}。到了 ArkUI 的build()里，这些写法要么编译不过，要么行为诡异。

ArkUI 的build()方法有自己严格的语法约束，官方文档叫“UI 描述语法”，只能调用内置组件、自定义组件、if/else、ForEach、LazyForEach这些声明式结构。任何计算逻辑、函数调用、数据加工，请提到build()外面的 getter 或者普通方法里去完成。

我把计算未完成数量的逻辑写到了get unfinishedCount()这个 getter 里，这个 getter 在 build() 里被调用时，如果内部依赖的@State变量发生变化，ArkUI 也会自动触发重新计算和 UI 刷新。所以记住这个套路：build() 里只做 UI 描述，其他活都外置。

4.6 踩坑五：自定义组件事件回调里this丢失

在 ArkUI 里写箭头函数基本不会遇到this指向问题，但如果你把回调函数抽到了组件外部，或者用普通函数而非箭头函数定义方法并传参时，this指向就可能出问题。

我建议所有事件回调、定时器回调、异步函数里，统一使用箭头函数。这是 React 时代老兵们都懂的习惯，在 ArkUI 里同样适用。不要问为什么，问就是 JavaScript 的this就是这么任性。

5. 实测总结与个人经验

ArkUI 开发下来，我最深的体会是：它确实不是一个“换皮 React”，而是一套吸收了声明式 UI 思想、融合了 TS/JS 生态、但带着自己强约束的框架。这些约束有时候让你觉得不自由，但适应之后你会感激它们帮你少犯了很多低级错误，尤其是在渲染性能这个层面上。

最后分享一个建议：学习 ArkUI 的过程中，不用太纠结语法和 React 的差异导致的各种“支棱不起来”。记住一个核心心智模型——@State数据一变，UI 自动跟着变——然后把它拆解到每个组件、每个变量、每条渲染分支里。把“状态驱动”这四个字刻进脑子，你就能在 HarmonyOS 开发里越来越顺手。

下一篇我会继续深入，把 ArkUI 的页面路由、组件生命周期、自定义弹窗这些更贴近真实业务的模块讲透。如果你在照着这篇文章写代码时遇到了问题，欢迎在评论区把报错日志贴出来，我会挑有代表性的逐条解答。