【手机编程】10 ArkTS 与鸿蒙应用开发入门:从 TypeScript 到声明式 UI 的完整上手路径
文章目录
如果你已经会 TypeScript,看到 ArkTS 的第一反应大概是“这不就是加了装饰器的 TS 吗”。
这个判断对了一半。语法确实高度相似,但对齐到工程上会发现:它可以限制比标准 TS 更严、它的状态管理是一套独立的机制、它的并发模型和 JS 完全不同。把 ArkTS 当“TS 换皮”来写,最容易踩的坑恰恰都在这些“不像 TS”的地方。
这篇按“从写第一个页面到能解释它为什么这样跑”的顺序展开:语言定位、声明式 UI 的语法、V1 与 V2 两代状态管理、TaskPool 并发、以及几个从 Android 转过来必须改掉的直觉。
1 ArkTS 是什么,不是什么
1.1 第三条原生路线
移动端有三条原生路线:Android 的 Kotlin + Jetpack Compose、iOS 的 Swift + SwiftUI、鸿蒙的 ArkTS + ArkUI。
前两条在第 6、8 篇已经讲过,这里说第三条的定位差异。鸿蒙强调的不是“再做一遍手机系统”,而是多设备协同——手机、平板、PC、车机、穿戴设备用一套分布式能力打通。ArkTS 作为这条路线上的语言,天然要服务于“一套代码适配多种屏幕形态”这个目标。
这也是为什么它的 UI 体系从一开始就是声明式的:声明式天然适合“同一份描述在不同尺寸上重新求值”。
1.2 与 TypeScript 的关系
官方定义很明确:ArkTS 是 HarmonyOS 应用开发的官方高级语言,在 TypeScript 生态基础上做了扩展,保持 TS 的基本风格,同时通过规范定义强化开发期静态检查和分析,以提升代码健壮性和运行稳定性 [1]。
这句话有三个可操作的要点。
第一,它保留 TS 的类型系统。接口、泛型、类型别名、联合类型都能用,所以写过 TS 的人迁移成本主要在“新机制”而不是“新语法”。第二,它做了限制。标准 TS 里一些灵活但会阻碍优化的写法被禁掉了,换来的是更强的静态信息和更好的运行性能。第三,它支持和 TS/JS 互操作 [1],这意味着存量 JS 生态不是完全割裂的。
1.3 .ets 文件不是 .ts
ArkTS 的源码文件扩展名是 .ets,不是 .ts。这个差别不只是后缀。
.ets 里可以用声明式 UI 的语法(以 build() 方法描述界面),而标准 TS 文件里不行。所以在工程里会看到两种文件并存:纯逻辑用 .ts,带界面的用 .ets。
一个实际约束:TaskPool 的任务函数必须用 @Concurrent 标注,且仅支持在 .ets 文件中使用 [9]。这类“只能在特定文件类型里用”的限制,是 ArkTS 工程结构的隐性约束,写之前要先知道。
1.4 编译侧:ArkCompiler
ArkTS 由方舟编译运行时(ArkCompiler)负责编译,它同时支持 ArkTS、TS、JS 的编译运行,并且支持 AOT [1]。
这条事实解释了“为什么 ArkTS 要限制 TS 的写法”。AOT 需要在编译期就知道尽可能多的事情:对象布局不能变、类型不能随便改、某些运算符语义要确定。限制越多,编译期能做的优化就越激进。
所以“ArkTS 比 TS 严格”不是设计者的偏好,而是为 AOT 付的代价,换回来的是启动速度和执行效率。
这条链路里最值得记住的是第二节:语言层和 UI 层是两套东西。ArkTS 是语言,ArkUI 是 UI 框架,前者编译,后者渲染。
1.5 静态检查强在哪,代价是什么
ArkTS 相对标准 TS 的强化,落在两个具体层面。
一是要求类型明确。标准 TS 允许大量隐式 any、允许运行期给对象加属性、允许用 arguments 之类的动态手段。这些写法在 ArkTS 里被限制或禁止,因为它们让编译期拿不到确定的类型信息。
二是限制运行期改对象布局。你在 JS 里可以随时给对象挂新字段,这会让隐藏类频繁重建。ArkTS 把这条路堵上,换来的是对象布局固定、字段访问可以走固定偏移。
代价是很实在的:一些“写得快”的灵活写法不能用了。比如动态拼装对象、用字符串索引访问属性。这些在 TS 项目里很常见,迁过来需要改结构。
判断标准很简单:如果一个写法依赖“运行时才知道结构”,它在 ArkTS 里大概率行不通。
1.6 和 TS/JS 的互操作
ArkTS 支持和 TS/JS 高效互操作 [1]。这条能力的实际含义是:存量 JS 代码可以作为模块直接引入,不必全部重写。
但“能引入”和“好用”是两件事。引入的 JS 模块失去了 ArkTS 的静态检查,也拿不到 AOT 的优化收益。所以合理的用法是:把它当过渡手段,新代码用 ArkTS,老代码逐步替换。
一条实践建议:把 JS 模块包在 ArkTS 的适配层后面。这样以后替换实现时,调用方不用动。
2 第一个页面:结构比语法重要
2.1 工程骨架
DevEco Studio 建出来的工程有一个固定结构:entry 是主模块,entry/src/main/ets 放代码,pages 放页面,resources 放资源。
这个结构和 Flutter 的 lib/、Android 的 src/main/java 是同一个思路:约定大于配置。所以上手时不需要纠结“文件该放哪”,按默认结构写就行。
2.2 @Entry 与 @Component
一个页面的最小骨架是两行装饰器:
@Entry
@Component
struct Index {
build() {
Column() {
Text('Hello HarmonyOS')
}
}
}
@Entry 标记“这是页面入口”,@Component 标记“这是可复用组件”。两者可以叠加,也可以分开:@Component 单独用就是普通组件。
struct 是 ArkTS 里自定义组件的声明关键字。它和类不同——struct 不能继承,实例由框架管理。这个设计让组件的生命周期完全交给框架,开发者不用管创建与销毁。
2.3 build 是“描述”不是“执行”
build() 方法里写的不是“创建控件”的指令,而是“界面长什么样”的描述。
这个区别决定了三件事:build 可以被调用很多次;build 里不能有副作用;build 里创建的对象会被丢弃重建。
和第 8 篇 SwiftUI 的 body、第 15 篇要讲的 Compose 一样,这是声明式框架的共同前提。
2.4 容器与子组件的嵌套
ArkUI 的组件分两类:容器(Column、Row、Stack、List)和叶子(Text、Image、Button)。
布局就是容器的嵌套。Column 是纵向排列,Row 是横向,Stack 是层叠。这三者组合基本能覆盖绝大多数界面。
和第 14 篇要讲的 Android 布局演进做个对照:ArkUI 没有 XML,也没有 ConstraintLayout 那种约束求解器,它靠“容器 + 属性”做布局。风格上更接近 SwiftUI。
2.5 生命周期钩子
一个自定义组件从创建到销毁有几个关键节点:aboutToAppear(即将出现)、aboutToDisappear(即将销毁)、onPageShow / onPageHide(页面级显隐)。
它们的用法和 Android 的 onCreate/onDestroy 类似,但语义更窄:只在这几个时机做“与界面相关的一次性动作”,比如初始化数据、释放资源。
一个实操原则:不要在 aboutToAppear 里做重活。它发生在首帧之前,做重活会直接拉长首屏时间。重活应该丢给 TaskPool,或者延后到首帧之后。
2.6 页面间怎么传参
ArkUI 的页面跳转通过路由完成,参数随跳转一起传,返回时也可以带值回来。
这个机制和 Android 的 Intent 相比更轻:不需要声明组件,不需要在清单里注册。代价是没有 Intent 那样的跨应用能力——跨应用要走的另一套入口机制。
一个实操细节:路由参数是序列化的,所以传对象时要能序列化。这一点和 Sendable 的引用传递不是一回事,别混。
3 声明式 UI 的语法特征
3.1 组件调用就是
在 ArkUI 里写 Text('hi') 看起来像函数调用,实际语义是“在当前位置挂一个 Text 组件”。
官方把这种写法称为声明式开发范式:用描述性的语法构建界面,把“怎么画”交给框架 [7]。这个语法糖的关键是位置即归属:写在哪个容器的花括号里,就属于哪个容器。没有 addView,没有 parent 参数。
好处是结构一眼可见,坏处是不能动态决定父子关系——你要改层级,只能改代码结构,不能运行时拼。
3.2 属性方法是链式调用
组件的属性通过链式方法设置:
Text('标题')
.fontSize(20)
.fontWeight(FontWeight.Bold)
.fontColor('#1a1a1a')
每个方法返回组件本身,所以可以一直链下去。这个风格和 SwiftUI 的修饰符链、Compose 的 Modifier 是同一类设计。
一个实操提醒:链式调用的顺序在部分属性上是有意义的(比如内外边距、背景与裁剪的关系)。不是所有属性都可交换,遇到“效果和预期不符”先检查顺序。
3.3 状态变化怎么变成界面变化
声明式框架的核心机制是“状态驱动重建”。ArkUI 的做法是:状态变量被装饰器标记 → 框架建立依赖关系 → 变量变化时通知依赖它的组件重建。
这套机制的关键是依赖关系的粒度。粒度粗,改一个字段整页重建;粒度细,只重建用到该字段的那一小块。第 4、5 章的 V1/V2 之争,本质就是粒度之争。
3.4 三种声明式的对照
把 ArkUI 和已经讲过的两套放在一起,能看清它们的共性与差异。
| 维度 | ArkUI(ArkTS) | SwiftUI | Compose |
|---|---|---|---|
| 组件声明 | struct + build() | struct + body | @Composable 函数 |
| 状态标记 | 装饰器(@State/@Local) | 属性包装器(@State) | mutableStateOf |
| 深度观测 | @ObservedV2 + @Trace | @Observable | SnapshotState |
| 布局方式 | 容器嵌套 | 容器嵌套 | 容器 + Modifier |
| 重建单位 | 组件 | 视图 | 可组合函数 |
三者的共同点是“状态变 → 函数重跑 → 界面更新”。差异在于如何知道哪一块该重跑——ArkUI 用装饰器显式标注,SwiftUI 用属性包装器加依赖追踪,Compose 用快照系统自动记录读取。
3.5 组件复用的现状
@ComponentV2 有一个明确的限制:暂不支持组件复用[2]。而 V1 的 @Component 是支持复用的(比如列表滚动时复用离屏组件)。
这条限制对长列表的影响最大,而且它出现的时机很隐蔽:项目初期列表只有二十项时完全看不出来:如果列表要滚动几百项,用 V2 组件可能拿不到复用带来的收益,滚动时的创建开销会上升。
这不是“V2 不好”,而是它还在演进。官方把它写成“暂不支持”,意味着后续会补。选型时要知道这条边界:极端长的列表场景,V1 目前仍有优势。
3.6 事件绑定写在组件上
ArkUI 的事件通过组件方法绑定,比如 .onClick(() => { ... })。
这个写法有两个实际约束。一是事件回调里不要做重活,因为它在 UI 线程执行。二是回调里改状态是安全的,框架会在合适的时机合并更新。
和第 21 篇要讲的手势系统相比,ArkUI 的事件模型更简单:它没有触摸事件分发的三层拦截,只有“组件自己处理”。简单换来的是可预测性,代价是复杂手势要自己实现。
4 状态管理 V1:够用,但有盲区
4.1 @State 是组件内部状态
@State 标记的变量是组件自己的状态,变化会触发该组件重建。它是 V1 里最基础的一个装饰器。
用起来很直接:@State count: number = 0,改 count 界面就更新。
但它的能力边界也很明确:只能观测到“这个变量被重新赋值”。如果变量是个对象,改对象内部的字段,@State 不一定能感知。
4.2 @Prop 与 @Link:父子传值
V1 里父子组件传值有三种方式:@Prop 单向传值(值拷贝)、@Link 双向同步(引用)、@Provide/@Consume 跨层级。
这套设计的问题不在功能,在心智负担:三个装饰器语义相近但行为不同(拷贝还是引用、单向还是双向),选错就会出“改了不生效”或“改了不该改的也变了”。
官方在 V2 的设计说明里承认了这个问题:V2 用 @Param 统一了 V1 中 @Prop、@Link 等复杂的传参逻辑 [4]。
4.3 @Watch 的盲区
@Watch 用来监听变量变化。它的盲区是官方明确写出来的:V1 无法实现对对象、数组中某一单个属性或数组项变化的监听,且无法获取变化前的值 [4]。
这两条限制在实际开发里的后果很具体。
改一个对象数组里第 37 项的某个字段,@Watch 只会告诉你“这个数组变了”,不会告诉你是哪一项、哪个字段,也不告诉你从什么变成什么。于是你只能整表重建。
这就是 V1 的粒度问题的根源:不是不想细,是没有信息做细。
4.4 一个量化
我把这件事做了个简单的模型:100 个列表项,每次只改一项的一个字段。

V1 的方案下,单次更新要重建 100 个子组件,按单项 0.06 毫秒的假设,单次 6 毫秒;换成 V2 的属性级观测,只重建 1 个,0.06 毫秒。

单次 6 毫秒看起来还好(60Hz 的帧预算是 16.6 毫秒,它只吃掉 36%)。但这个模型里更值得注意的是连续更新的累计效应:价格跳动、滚动加载这类场景,30 次更新累计 V1 是 180 毫秒,V2 是 1.8 毫秒。
这里的结论不是“V1 不能用”,而是V1 的代价是随更新频率放大的。低频更新没问题,高频更新必然掉帧。
4.5 一套完整的 V1 装饰器清单
官方在状态管理总览里把两代装饰器并列成对照表 [3],所以“这个项目用的是 V1 还是 V2”,看它用了哪些装饰器就够了。V1 的核心集合是:@Component、@State、@Prop、@Link、@Provide、@Consume、@Observed、@Track、@Watch、@StorageLink、@StorageProp。
其中 @StorageLink / @StorageProp 是配合 LocalStorage 做持久化的,这也是 V2 目前不支持的能力之一 [2]。
把清单摆出来的价值在于:迁移时要逐个对照,而不是凭印象改。漏一个就会在编译期暴露,但你可能先花半小时怀疑别的地方。
4.6 V1 时代的“继承式”状态
V1 里有一个常见做法:把状态放在父组件,子组件通过 @Link 拿到引用,直接改。
这个做法的好处是“少写一层回调”,坏处是数据流向不可追踪:任何一个子组件都能改父组件的状态,出问题时无从定位。
V2 的 @Param 不可写,正是为了堵住这条路 [6]。所以迁移时遇到“子组件直接改父状态”的代码,不能简单换成 @Param,要改成 @Event 回调。
这类改动的工作量往往比换装饰器更大,迁移计划要把它算进去。
5 状态管理 V2:把粒度做细
5.1 @ComponentV2 是另一套体系
V2 的入口是 @ComponentV2。它从 API version 12 开始支持,且有三个硬约束:只能配 V2 装饰器使用、不能与 @Component 装饰同一个 struct、暂不支持组件复用与 LocalStorage 等 V1 能力 [2]。
最后一条要特别注意:V1 和 V2 不是“新旧版本可以混用”,而是两套并行体系。混用会直接编译不过。
它还有一个可选参数 freezeWhenInactive,用于实现组件冻结——组件不可见时暂停状态更新,省掉无效的重建 [2]。
5.2 @Local 与 @Param 的分工
V2 把“组件内部状态”和“外部传入状态”彻底分开了。
@Local 是组件内部状态,无法从外部初始化 [8]。@Param 是组件输入,可以从外部传入并同步 [8]。
这个划分比 V1 清爽的地方在于:看一眼装饰器就知道这个值归谁管。V1 的 @State 既可内部也可外部初始化,边界模糊。
5.3 @Once、@Event 与 @Provider
补上三个配角。
@Once 修饰的变量只在初始化时同步一次,必须和 @Param 一起用 [8]。它适合“父组件给个初始值,之后各管各的”这种场景。
@Event 修饰方法类型,作为组件输出,用来影响父组件的变量 [8]。它就是“回调”的声明式写法。
@Provider / @Consumer 用于跨组件层级的双向同步 [8],相当于 V1 的 @Provide/@Consume。
5.4 @ObservedV2 与 @Trace 是深度观测的组合
要让“对象内部字段变化”被感知,需要一对装饰器:@ObservedV2 装饰类,@Trace 装饰类里的属性,两者配合才能实现深度观测 [8]。
这个组合是 V2 相比 V1 最实质的改进:观测粒度从“变量”下沉到“属性”。
代价是它要求你显式标注到属性级。也就是说,深度观测不是自动的,是“你标了才有”。这一点和 Swift 的 @Observable 很像——自动追踪的是“被读取的属性”,而 Dart、Java 没有等价机制。
5.5 @Monitor 能拿到变化前后的值
@Monitor 是 V2 的监听器,它解决了 V1 @Watch 的两个盲区:可以深度监听,且能拿到变化前后的值 [4]。
用法上,它接受一个路径字符串(如 'info.message'),回调里通过 monitor.value() 取 before 和 now。
它还有一个时机细节值得记:定义在 @ComponentV2 里时,@Monitor 在状态变量初始化完成之后才生效,组件销毁时失效 [5]。所以构造函数里改值,它监听不到——这不是 bug,是设计。
5.6 @Computed 避免重复计算
@Computed 修饰的方法是计算属性,只在依赖的值变化时计算一次 [8]。
它解决的问题很具体:同一个派生值在 UI 里被多处使用,每次读都重算一遍。加了 @Computed 之后,一帧内只算一次。
这个思路和 SwiftUI 里“把派生值放在 body 之外”、Compose 里 derivedStateOf 是同一个动机:把重复计算收敛成缓存。
5.7 V2 的装饰器全貌
V2 这一套的完整清单是:@ComponentV2、@Local、@Param、@Once、@Event、@Monitor、@Provider、@Consumer、@Computed、@ObservedV2、@Trace,外加 !! 双向绑定语法糖 [8]。
与 V1 对比,最值得注意的是数量并没有变少。V2 不是“简化装饰器数量”,而是“让每个装饰器的职责更单一”:内部状态就是内部状态,外部输入就是外部输入,输出就是输出。
这个改进方向和第 13 篇要讲的架构模式是同一条逻辑:职责单一比数量少更重要。
5.8 一个 V2 的最小闭环
把 V2 的装饰器串起来,一个组件的最小完整形态是这样:
@ObservedV2
class Item {
@Trace price: number = 0;
}
@ComponentV2
struct Row {
@Param item: Item = new Item();
@Event onTap: () => void = () => {};
@Monitor('item.price')
onPriceChange(mon: IMonitor) {
// 这里能拿到 mon.value().before 与 mon.value().now
}
build() { /* 用 this.item.price 渲染 */ }
}
这段代码里四件事同时在起作用:@ObservedV2 + @Trace 让属性可观测,@Param 接收外部对象,@Monitor 监听路径变化,@Event 向外通知。这四者就是 V2 的完整骨架。理解了这四者的分工,V2 剩下的装饰器(@Once、@Provider、@Consumer、@Computed)都是在同一个逻辑上做补充,不会再有认知跳跃。
6 从 V1 迁到 V2
6.1 一张映射表
迁移不是“改个名字”,但也没有想象中复杂。核心映射如下。
| V1 | V2 | 关键差异 |
|---|---|---|
@Component | @ComponentV2 | 不能混用,必须整体切换 |
@State | @Local | @Local 不可外部初始化 |
@Prop / @Link | @Param | 统一为单向同步 + @Event 回传 |
@Watch | @Monitor | 可深度监听、可取前后值 |
@Observed + @Track | @ObservedV2 + @Trace | 属性级观测 |
@Provide / @Consume | @Provider / @Consumer | 语义基本一致 |
这张表的价值在于:它告诉你哪些是等价迁移,哪些需要改逻辑。前两行是结构改动,中间两行是行为增强,最后一行几乎照搬。
6.2 @Param 不可写,怎么办
@Param 有一个硬限制:本地不可写 [6]。子组件不能直接改父组件传下来的值。
官方给的解法是 @Monitor + @Local 的组合:用 @Local 存本地副本,用 @Monitor 监听 @Param 的变化并覆写本地值 [6]。
这个模式的信息流是单向清晰的:父改变 → 通知子 → 子更新本地副本。子改本地副本不影响父。要影响父,走 @Event。
这个设计看起来麻烦,但它把“数据从哪来、往哪去”写在了代码结构里,比 V1 的隐式双向同步更不容易出错。
6.3 迁移的实操顺序
建议的顺序是:先把 @Component 整体换成 @ComponentV2(这一步会暴露所有不兼容点),再逐个替换状态装饰器,最后处理 @Param 的只读问题。
不要试图“一个组件一个组件地混着迁”——因为两者不能共存于同一 struct,混迁只会得到一堆编译错误。
6.4 迁移后的验收清单
迁移完成后,有四件事值得逐条确认。
第一,所有 @Component 是否都换成了 @ComponentV2(不能混)。第二,原来的 @Prop/@Link 是否都改成了 @Param,并且处理了“本地不可写”的问题。第三,所有需要深度观测的类是否都加了 @ObservedV2,且每个要观测的属性都加了 @Trace。第四,原来依赖 LocalStorage 的地方是否有替代方案。
四条都过了,迁移才算完成——只看“能编译”是不够的,因为第 3、4 条的问题只在运行时暴露。
7 并发:TaskPool、Worker 与 Sendable
7.1 TaskPool 是托管线程池
TaskPool 为应用提供多线程环境,开发者把任务提交到任务队列,系统选合适的工作线程执行并回传结果 [9]。
它的关键机制是自动扩缩容:提交任务时做扩容检测,空闲线程数不足就按负载创建;任务减少后,每 30 秒检测一次负载,满足条件(空闲达 30 秒、无长时任务、无未释放句柄等)才释放线程 [9]。
这个设计意味着你不该自己管线程数。写 TaskPool 就当它是“有上限、会自动调节的池”,别去想线程复用。
一个硬性约束:任务函数必须用 @Concurrent 标注,且只能在 .ets 文件中使用 [9]。
7.2 Worker 是自己管的线程
Worker 需要开发者自行创建,也不支持设置调度优先级 [1]。它的场景是“需要长期存在、需要持有状态”的线程——比如持续解码、持续监听。
官方对两者的定位差别的描述很直接:需要一连串同步任务共用同一个句柄、或依赖某个类对象调度时,用 Worker [9 的姊妹篇]。
7.3 Sendable 解决“跨线程传对象”
默认情况下,跨并发实例传对象是深拷贝,序列化反序列化的成本很高。
@Sendable 装饰的类可以被放在共享堆(SharedHeap)上,跨实例通过引用传递,省掉序列化和反序列化 [10]。它从 API version 11 开始支持 [9]。
这条能力的实际价值很大:从网络或数据库拿到的业务模型,标成 Sendable 后从子线程传回主线程,成本从“拷贝整个对象”降到“传一个引用”。
7.4 选择标准
三个方案的分工可以这样记:
一次性、可并行的计算 → TaskPool。长期运行、需要状态的线程 → Worker。跨线程传大对象 → 加 @Sendable。
还有一个容易被忽略的选择依据:任务数量。官方对比里提到,任务数较少时 Worker 的任务执行耗时优于 TaskPool,任务数大于 8 之后 TaskPool 逐渐占优;但 TaskPool 的运行时内存占用会随任务数增加而高于 Worker。
最后一条特别容易漏:@Sendable 不是替代 TaskPool 的方案,它是配合 TaskPool 用的。传数据用 Sendable,跑任务用 TaskPool。
7.5 并发的一条硬规则
不管用 TaskPool 还是 Worker,有一条规则是共通的:并发实例之间不共享普通对象的内存。
官方的表述是:普通对象所属的内存是隔离的,不会出现线程竞争同一内存资源的情况。这听起来是好消息(不会有锁问题),但它有个另一面:跨实例传的就是拷贝,除非你用了 Sendable。
所以“并发安全”这件事在 ArkTS 里被换成了“数据传递成本”。这和 Dart 的 isolate 是同一个设计哲学:用隔离换确定性。
7.6 并发实例开多少
一个实际问题是:到底开几个并发实例。
TaskPool 会自己扩缩容,所以“开几个”不需要你定。但 Worker 需要你自己创建,这就有了取舍:开少了任务排队,开多了内存和调度成本上升。
一个可用的经验值是不超过物理核数。因为再多也只是在等 CPU,反而增加了切换成本。这条和 CPU 密集任务的通用规则一致。
8 五个会踩的坑
8.1 在 build 里改状态
build 里改状态变量,会触发重建,重建又执行 build,形成循环。表现是界面闪烁或直接卡死。
判断标准很简单:只要有赋值,就该怀疑。副作用应该放在事件回调或生命周期钩子里。
8.2 用 V1 的装饰器写 V2 组件
@ComponentV2 里写 @State,直接编译不过。这不是“兼容性差”,而是两套体系不能混。
排查方法:看组件顶部的装饰器是不是 V2 结尾,再对照表检查内部装饰器。
8.3 忘了 @Trace 就以为能深度观测
@ObservedV2 只装饰类,属性级的观测要靠 @Trace 逐个标注 [8]。
漏标的后果是“改了这个字段界面没反应”,而其他字段正常——这种“部分生效”的现象最难查,因为代码看起来没问题。
8.4 用 TaskPool 跑带闭包的任务
@Concurrent 函数不能访问闭包,也不能调用当前文件的其他普通函数 [9 的并发 FAQ]。所以“把方法传进去”是不行的。
解法是通过参数传入 @Sendable 修饰的函数,在 @Concurrent 函数内部调用。
8.5 在子线程碰 UI
子线程不支持 UI 属性,所以从子线程返回的数据必须和 UI 剥离,回到主线程再渲染 [10]。
这条如果违反,表现往往是“数据到了但界面不更新”,而不是报错——因为框架可能只是忽略了这次更新。
8.6 怎么定位“界面不更新”
这类问题有一个通用的排查顺序,按成本从低到高。
第一步,确认装饰器链是否完整(@ObservedV2 有没有配 @Trace)。第二步,确认改的是不是“被观测的那个对象”——改副本是不会有反应的。第三步,确认改的时机不在 build 里。第四步,如果涉及并发,确认数据回到了主线程。
这个顺序的逻辑是:先查静态结构,再查运行时路径。静态结构错了改代码就行,运行时路径错了要改架构。
8.7 一张症状对照表
把前面几节的现象整理成一张表,方便反查。
| 症状 | 最可能的原因 | 检查点 |
|---|---|---|
| 界面闪一下 | build 里有副作用 | 搜索 build 内的赋值 |
| 改了字段没反应 | 漏标 @Trace | 对照 @ObservedV2 类 |
| 整页都重建 | 粒度太粗(V1 或未用 @Trace) | 状态装饰器类型 |
| 编译报装饰器错误 | V1/V2 混用 | 组件顶部是否为 @ComponentV2 |
| 数据到了界面不更新 | 子线程直接更新 UI | 数据是否回主线程 |
| 滚动卡顿 | V2 组件无复用 | 是否长列表 |
这张表不能覆盖所有情况,但它能覆盖新手 80% 的“不知道为什么”。
9 从 Android 过来要改的直觉
9.1 装饰器不是注解
Kotlin 的注解(@Inject、@Composable)大多由编译期处理器或运行时反射处理。ArkTS 的装饰器是语言机制,直接参与状态依赖的建立。
所以“加个装饰器”在 ArkTS 里往往有实际的行为后果,而不是纯标记。
9.2 没有 XML,也没有 findViewById
Android 的布局在 XML 里,ArkTS 的布局在 build() 里。这是最直观的差异,但影响更深:布局参数不再是“属性集合”,而是链式方法调用,动态改样式的写法也要跟着变。
9.3 页面栈是框架管的
ArkUI 的页面跳转由框架统一管理(router),不需要自己在 Manifest 里注册 Activity。这带来一个好处:页面间的参数传递和返回更简单;代价是不能像 Android 那样自由控制任务栈。
9.4 分布式是原生能力
鸿蒙的差异点在于分布式能力是系统级的:跨设备调用、跨设备数据同步不需要自己搭通道。
这是它相对 Android 的真实优势,也是选型时唯一值得为它单独考虑的理由。如果你的产品是单设备工具类,这个优势用不上,那 ArkTS 的收益就只剩“一套代码适配多屏”。
9.5 生态成熟度要单独评估
语言和框架是一回事,生态是另一回事。
评估 ArkTS 时,除了语法,还要看三件事:常用第三方库有没有鸿蒙版本、团队能不能招到人、系统版本节奏是否稳定。
第三点尤其重要。HarmonyOS 的版本迭代快,部分能力仍在演进(比如 V2 的组件复用)。做长期项目时,要给“框架升级带来的适配”预留时间。
这不是 ArkTS 独有的问题,任何新生态都有。区别在于:成熟生态的坑有人踩过,新生态的坑要自己踩。
9.8 新建项目还是迁移旧项目
两条路线的策略完全不同。
新建:直接用 V2,从第一行代码就按“内部状态 / 外部输入 / 输出”三分法组织。这样不会欠下迁移债。
迁移:先做“能不能整体切”的评估。如果组件数量少,一次性切;如果数量多,按页面分批切,但同一批内不允许混用。
一个容易犯的错是“先迁一部分,剩下的以后再说”。结果是两套装饰器并存,团队里每个人都要同时记住两套规则,认知成本翻倍。
10 结语:先理解装饰器,再理解框架
ArkTS 的入门门槛不高——会 TS 的人半天就能写出能跑的页面。
真正的分水岭在第二周:当界面出现“改了不生效”“部分生效”“整页闪一下”这些现象时,你能不能立刻定位到是粒度问题、是漏标 @Trace、还是在 build 里做了副作用。
这篇给的最小可用判据是三条:状态用 @Local/@Param 分清归属、要深度观测就必须 @ObservedV2 + @Trace 成对出现、build 里只做描述。
三条都能守住,剩下的事情就是把 ArkUI 的组件和 API 一个个熟悉过去——那部分是查文档能解决的,不需要靠猜——而且 ArkUI 的组件文档写得相当细,每个属性的默认值和边界条件都有说明,遇到不确定的行为直接查表就行。
9.6 一份可执行的上手顺序
如果要从零开始,建议按这个顺序走,每一步都能产出可见的东西。
第一周:写三个静态页面(列表、详情、设置),只练容器嵌套和属性链。第二周:给页面加状态,用 V2 的 @Local/@Param,练父子传值。第三周:接一个本地数据源,练 @ObservedV2 + @Trace 的深度观测。第四周:把一个耗时计算挪到 TaskPool,练并发。
四周之后,你会遇到的坑基本都在本文第 8 章里——那一天再回头读状态管理的文档,会发现每一句都能对上自己的经历。这时候再回头读官方文档,效率比一开始通读高得多。
9.7 三个能帮你判断“学没学会”的问题
第一个问题:为什么 @ObservedV2 装饰了类,还要给属性加 @Trace?
答不上来,说明还没理解“观测粒度是属性级”这件事。答案是:类只是容器,真正要监听的是属性变化,@Trace 是在给属性登记“我可被观测”。
第二个问题:@Param 为什么不能本地写?
答不上来,说明还没理解“单向数据流”。答案是:@Param 代表外部输入,允许本地写就变成了隐式双向,数据流向就不可追踪了。要改,走 @Event 回传。
第三个问题:TaskPool 和 Sendable 是什么关系?
答不上来,说明把“跑任务”和“传数据”混成一件事了。答案是:TaskPool 负责调度执行,Sendable 负责降低跨实例传递的成本,两者是配合关系。
三个问题都能答清楚,基本可以独立上手一个中等复杂度的鸿蒙页面了。
参考资料
- 华为开发者联盟. ArkTS 简介(官方语言、TS 扩展、TaskPool/Worker/Sendable、ArkCompiler AOT). https://developer.huawei.com/consumer/cn/doc/harmonyos-guides-V14/arkts-overview-V14
- 华为开发者联盟. @ComponentV2 装饰器:自定义组件(API 12 起支持、不可与 @Component 混用、freezeWhenInactive). https://developer.huawei.com/consumer/cn/doc/harmonyos-guides-v5/arkts-new-componentv2-V5
- 华为开发者联盟. 状态管理 V1 && V2(装饰器总览). https://developer.huawei.com/consumer/cn/blog/topic/03171821823467106
- 华为开发者联盟. 状态管理 V1 和 V2 适用场景介绍(V1 监听盲区、@Monitor 深度监听). https://developer.huawei.com/consumer/cn/doc/harmonyOS-faqs/faqs-arkui-885
- 华为开发者联盟. @Monitor 装饰器:状态变量修改异步监听(生效与失效时机). https://developer.huawei.com/consumer/cn/doc/harmonyOS-guides/arkts-new-monitor/
- 华为开发者联盟. 组件内状态变量迁移(@Param 不可写、@Once 与 @Monitor 覆写 @Local). https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-v1-v2-migration-inner-component/
- 华为开发者联盟. UI 开发(ArkTS 声明式开发范式)概述. https://developer.huawei.com/consumer/cn/doc/harmonyos-guides-V5/arkts-ui-development-overview-V5
- HarmonyOS. State Management V2 Decorators(@ObservedV2/@Trace/@Local/@Param/@Event/@Computed/!! 语法). https://device.harmonyos.com/en/docs/apiref/harmonyos-guides/arkts-state-management-overview
- 华为开发者联盟. TaskPool 简介(@Concurrent、.ets 限制、@Sendable、扩缩容机制). https://developer.huawei.com/consumer/cn/doc/harmonyOS-guides/taskpool-introduction/
- 华为开发者联盟. TaskPool 使用规范(Sendable 共享堆引用传递、子线程与 UI 剥离). https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/task-pool-usage-guidelines
更多推荐


所有评论(0)