从“数据怎么不更新了”开始说起刚接触 ArkUI 的开发者十有八九会遇到这个问题明明在代码里改了变量但屏幕上就是没反应。这个现象的本质在于 ArkUI 的 UI 更新机制。传统命令式开发里你直接操作 DOM 或者调用invalidate()来强制刷新。但在 ArkTS 声明式开发范式里UI 是数据驱动框架需要知道哪些数据变化了以及哪个组件依赖这些数据。如果数据声明方式不对框架认为它“不可观测”自然就不会触发重绘。很多人第一次接触State时容易把它理解成“普通的成员变量”直接在回调里修改。或者试了半天Prop和Link遇到编译报错就懵了。这些问题的根源在于没搞懂状态装饰器背后数据管理的所有权和同步方向。状态装饰器解决的根本问题状态装饰器解决的问题很直接建立数据与 UI 的绑定关系明确数据从哪来、能影响到谁、修改后谁负责刷新。它代替了传统开发里手动操控 UI 控件的繁琐步骤让开发者把精力放在业务数据的变化逻辑上。ArkUI 提供了一整套状态管理器从组件内部私有状态到父子组件通信再到跨组件甚至跨页面共享。这里面最基础、使用频率最高的就是三个装饰器装饰器所属域数据所有权同步方向典型场景State组件内部私有完全由当前组件管理单向自身变化触发 UI 刷新计数器、表单输入框、列表局部状态Prop父子组件父组件拥有子组件获得只读副本单向父到子父组件传递一个配置值给子组件Link父子组件父组件拥有子组件通过引用共享同一份数据双向同步复杂表单、需要子组件修改父组件数据的场景核心差异在于数据的所有权和传递层级。State是单组件自用的Prop是只读拷贝Link是双向引用。选错了轻则功能实现不了重则编译报错或者运行时效率问题。环境说明DevEco Studio 版本DevEco Studio 6.1.0 及以上 HarmonyOS SDK 版本HarmonyOS 6.1.0(23) 及以上 目标设备手机以上版本已验证过当前所有示例代码。核心实现从计数器到父子组件同步下面从最简单的State开始再到父子组件配合的例子完整演示数据驱动 UI 更新的流程。步骤 1State 实现计数器这一段代码用于展示一个自增计数器按钮点击触发内部状态count加一UI 自动刷新。// CounterPage.etsEntryComponentstruct CounterPage{Statecount:number0build(){Column({space:20}){Text(当前计数:${this.count}).fontSize(24)Button(加一).onClick((){// 直接修改 State 变量框架会自动检测变化this.count})}.width(100%).height(100%).justifyContent(FlexAlign.Center)}}注意事项State只能修饰箭头函数作用域内的变量不能是对象属性除非用Observed。修改State变量时必须直接赋值this.count 1或者使用不可变方式this.arr [...this.arr, newItem]如果直接操作数组或对象的内部如this.arr.push()框架可能检测不到变化。性能上State变化会重建与它直接绑定的组件。如果State修饰一个大型对象比如包含上千个字段频繁修改会对性能有影响。这种情况下建议拆成多个小State或者使用ObservedObjectLink。步骤 2Prop Link 实现父子组件同步这个例子模拟一个购物车场景父组件控制总价子组件商品项可以加减数量并将变化同步回父组件。我们用Prop实现父传子展示商品名用Link实现双向同步数量。// CartItem.etsComponentstruct CartItem{// Prop 接收父组件传入的商品名PropitemName:string// Link 与父组件的 State countList 中的某个元素建立双向绑定LinkWatch(onCountChange)count:number// 可选监听 count 变化做一些副作用onCountChange():void{console.info(商品${this.itemName}的数量变为:${this.count})}build(){Row({space:10}){Text(this.itemName).width(80)Button(-).onClick((){if(this.count0){// 直接修改 Link 变量变化会同步到父组件this.count--}})Text(${this.count}).width(20).textAlign(TextAlign.Center)Button().onClick((){this.count})}.padding(10).border({width:1,color:Color.Gray})}}// CartPage.etsEntryComponentstruct CartPage{StatecountList:number[][0,0,0]privateitems:string[][苹果,香蕉,橘子]build(){Column({space:10}){Text(购物车).fontSize(20)// 用 ForEach 循环渲染子组件ForEach(this.items,(item:string,index:number){// 关键Link 必须传变量引用不能传表达式// 使用 $countList[index] 语法获取可观察引用CartItem({itemName:item,count:$countList[index]})},(item:string)item)Divider()Text(总数量:${this.countList.reduce((a,b)ab,0)}).fontSize(16)}.width(100%).padding(20)}}为什么这样设计架构使用$countList[index]而不是this.countList[0]是因为Link要求传递一个可观察引用。$语法会返回一个Link装饰的变量否则编译会直接报错。子组件用Prop接收itemName父只读用Link接收count双向职责清晰。如果子组件也需要修改itemName那就得用Link这与需求冲突所以设计上保持单向只读更合理。性能影响Link和State的变更都是受控的但Link因为涉及跨组件更新开销略高于State。在一个列表里如果几十个CartItem都在频繁修改count父组件CartPage的State countList每次变化都会触发整个列表的ForEach重建。这在数据量大时会有卡顿风险后续可以结合key和lazyForEach做优化。踩坑记录问题 1Prop 变量修改后父组件没变现象子组件内部修改了Prop变量页面上子组件自己的 UI 变了但父组件里对应的变量没变导致数据不一致。原因这是设计上的故意行为。Prop提供一个复制副本子组件对这个副本的修改仅限于子组件内部并不会影响父组件的原始数据。官方文档的示例也容易让新人误解以为Prop可以“写回”。解法如果希望子组件修改后同步回父组件必须使用Link或者通过回调函数父组件传一个State变量给子组件子组件调回调传回新值。通常推荐第一种因为Link写法更简洁回调方式编写逻辑比较绕。问题 2Link 在列表场景中循环引用导致崩溃现象在ForEach中使用Link绑定到State数组的元素如果元素本身是一个对象对象内部又引用了父组件或者其他对象就会形成循环引用导致页面卡死或崩溃。原因Link本质上是引用传递对象内部某个属性又引用了父组件父组件的State变化触发子组件更新子组件又反过来修改了父组件形成死循环。更隐蔽的情况是数组元素被多次索引时系统内部会构建复杂的依赖关系图一旦出现环就会触发无限重绘。解法保持数据扁平化State数组只存简单值或浅层对象避免深度嵌套。在Watch或onClick回调里不要同时修改父子双方的State/Link变量。比如不要既修改this.count又在子组件里修改父组件的某个状态把修改逻辑统一收敛到父组件。如果必须在对象内部维护复杂关系改用ObservedObjectLink并用Watch手动控制更新链的深度必要时加上防抖或节流。最佳实践优先使用State私有状态不要滥用Link。如果子组件只是展示数据用Prop足够。Link的开销和复杂性都比State高只在确实需要双向同步时才用。这条原则能避免很多不必要的组件耦合。State绑定大型对象时避免直接修改对象内部属性。使用Observed装饰对象类或者在修改时创建一个新对象并整体替换this.data { ...this.data, newField: newVal }。这样可以保证框架稳定检测到变化并且避免深层引用问题。在ForEach中为每个子组件提供稳定的key。如果没有提供key或key不稳定如使用数组索引当列表增删时Link的绑定可能会错乱导致子组件保留了不合法的引用。推荐使用item本身的唯一标识如id作为 key。Demo 入口上述代码示例已经包含完整可运行结构。对应的主入口文件为CartPage.ets直接将其设置为Entry即可运行。FAQQ为什么真机正常模拟器上Link修改没生效A通常是模拟器的 SDK 版本低于真机。部分旧模拟器对Link的$语法支持不完整。建议将模拟器和 DevEco Studio 都更新到最新版本或者在真机上验证。Q为什么页面返回后我之前的状态丢失了A这是正常的生命周期行为。页面返回时State变量的内存会被释放。如果需要在页面间持久化状态可以使用StorageLink或LocalStorageLink结合 AppStorage / LocalStorage或者手动写入持久化存储Preference / Database。这个机制和State本身没关系是声明式框架的通用设计。Q为什么Link绑定的对象直接赋值this.obj newObj编译报错ALink是基于引用绑定不支持重新赋值给另一个对象。它只能和父组件的State/Prop指向的同一块内存地址交互。如果需要替换整个对象在父组件操作State变量即可子组件的Link会自动感知。