刚接触 ArkTS 的人,最常犯的一个错是把这四个装饰器当成"四种写法",随便挑一个能跑通的就用。它们其实是四种数据流向,选错了不会报错,只会在某个下午突然发现"数据改了但界面没动"。

这篇按流向把四个拆开讲,每个给出它真正管的那一段路,最后给一张选择表。

一、先把四种流向画出来

不看代码,先看这四个东西各自连接哪两个点:

  • @State —— 组件自己和自己。值变了,自己这个组件的 UI 重建。
  • @Prop —— 父组件到子组件,单向。父变了子跟着变,子改了父不知道。
  • @Link —— 父组件和子组件,双向。两边指向同一份数据,谁改都同步。
  • @Provide / @Consume —— 祖先和任意层的后代,跨层级双向。中间那些层不用管这件事。

一句话概括:@State 管自己,@Prop 管接收,@Link 管共享,@Provide 管穿透。

判断该用哪个,问自己两个问题就够了:

  1. 这份数据的所有者是谁?谁有资格改它?
  2. 从所有者到使用者,中间隔了几层?

第一个问题答"组件自己",就是 @State。答"父组件",再看第二个问题:只隔一层,向下用 @Prop、向上用 @Link;隔了好几层,用 @Provide/@Consume。

二、@State:组件自己的事,别拿出来共享

@State 是最简单也最容易被滥用的一个。它的语义是组件私有——父组件在创建的时候可以给个初始值,之后就管不着了。

@Entry
@Component
struct Counter {
 @State count: number = 0;

 build() {
 Column() {
 Text(`当前 ${this.count}`)
 .fontSize(20)
 Button('加一')
 .onClick(() => {
 this.count++;
 })
 }
 }
}

这段代码改 this.count,Text 会刷新。因为 count 是这个组件的状态,而 Text 在这个组件的 build 里。

滥用 @State 的典型场景:把本该属于父组件的数据在子组件里也声明一份 @State,然后在两个地方各改各的。结果就是父组件那份和子组件那份逐渐不同步,你还得写额外的逻辑去对齐。

判断标准很硬:**如果这份数据在组件销毁后就没有意义了,它才该是 @State。**购物车的商品数量属于页面,不属于"这个数量选择器组件",那它就不该是子组件的 @State。

三、@Prop:单向下降,适合"我只读"

@Prop 建立的是父到子的单向通道。父组件的值变了,子组件跟着更新;子组件内部改了,只改自己那份副本,父组件完全不知道。

@Component
struct PriceTag {
 @Prop price: number;
 @Prop discount: number = 1;

 build() {
 Text(`¥${(this.price * this.discount).toFixed(2)}`)
 .fontSize(16)
 }
}

@Entry
@Component
struct GoodsPage {
 @State basePrice: number = 199;

 build() {
 Column() {
 PriceTag({ price: this.basePrice, discount: 0.9 })
 Button('涨价')
 .onClick(() => {
 this.basePrice += 50; // 子组件跟着刷新
 })
 }
 }
}

点"涨价",PriceTag 里的数字会变。这就是 @Prop 该用的地方:子组件是纯展示,它需要值,但不需要拥有值。

@Prop 有两个坑必须知道:

第一个坑:@Prop 传对象是浅拷贝。父组件传一个对象进来,子组件拿到的是新对象,但里面嵌套的对象还是同一个引用。所以改嵌套属性时,子组件的界面不一定刷新——这跟 @Prop 无关,是嵌套对象的可观察性问题,要配 @Observed 和 @ObjectLink 解决,后面第六节讲。

**第二个坑:@Prop 有拷贝成本。**每次父组件更新,子组件都要拷一份。数据量小无所谓,如果传的是几百条记录的列表,每次更新都拷一遍,滚动就会掉帧。这种情况改用 @ObjectLink 或者干脆把数据源提升到父组件用 @Link 共享。

四、@Link:双向绑定,代价是把修改权也交出去了

@Link 和 @Prop 最大的区别是它不拷贝。父子两边引用同一份数据,谁改都算数。

@Component
struct NumberStepper {
 @Link value: number;

 build() {
 Row() {
 Button('-').onClick(() => { this.value--; })
 Text(`${this.value}`).fontSize(18).margin({ left: 12, right: 12 })
 Button('+').onClick(() => { this.value++; })
 }
 }
}

@Entry
@Component
struct CartPage {
 @State quantity: number = 1;

 build() {
 Column() {
 NumberStepper({ value: $quantity }) // 注意这个 $
 Text(`小计 ¥${quantity * 89}`)
 }
 }
}

这里 NumberStepper 里点加号,父组件的 quantity 真的变了,下面那行小计跟着刷新。这就是 @Link 的价值:子组件有权修改父组件的数据,而且改完两边都一致。

注意传递时必须写 $quantity,这个 $ 表示"传引用不传值"。写成 quantity 会编译报错或者退化成单向,具体看 API 版本。

@Link 的代价是所有权的稀释。一份数据被三个子组件 @Link 住,那你读代码时就得同时看三个地方才知道它为什么变成了现在这个值。所以用 @Link 要有纪律:能 @Prop 就 @Prop,只有真的需要子组件改父组件的数据时才上 @Link。

五、@Provide/@Consume:跨层级,省掉中间传参

父传子用 @Prop,孙组件要同一个值怎么办?逐层往下传 @Prop 是最直接的做法,但如果隔了四五层,中间那些组件就成了纯粹的传话筒——它们根本不关心这个值,只负责往下递。

@Provide/@Consume 解决的正是这件事。

@Entry
@Component
struct AppRoot {
 @Provide('theme') theme: string = 'light';

 build() {
 Column() {
 Header() // 中间这两层完全不碰 theme
 Content()
 }
 }
}

@Component
struct Header {
 build() { Text('标题').fontSize(20) }
}

@Component
struct Content {
 build() {
 Column() {
 DeepCard()
 }
 }
}

@Component
struct DeepCard {
 @Consume('theme') theme: string;

 build() {
 Text(this.theme === 'dark' ? '深色' : '浅色')
 .backgroundColor(this.theme === 'dark' ? '#222' : '#fff')
 }
}

AppRoot 提供,DeepCard 消费,中间 Header 和 Content 一行都不用改。这是 @Provide 唯一的、也是最大的价值:省掉中间层的传参污染。

两个使用要点:

第一,别名要对上。@Provide('theme') 和 @Consume('theme') 字符串必须一致。不写别名时按变量名匹配,改个变量名就断了,而且不报错——这是最难查的一类问题。

**第二,@Consume 不许有初始值。**它必须能找到上游的 @Provide,找不到会运行时报错。所以这个组件不能单独预览,必须有祖先提供值。

代价也是明确的:跨层级让数据流变得不可见。看 DeepCard 的代码,你完全不知道 theme 从哪来。所以 @Provide 适合那种全局主题、当前登录用户、语言设置这类本来就跨层的东西,不适合业务数据。

六、四种选完还刷新的问题:@Observed 与 @ObjectLink

上面四个管的是"变量本身变没变"。但有一类情况它们都救不了:变量没变,变的是它里面的属性。

@Observed
class UserInfo {
 name: string = '';
 age: number = 0;
}

@Component
struct UserCard {
 @ObjectLink user: UserInfo; // 注意是 @ObjectLink,不是 @Prop

 build() {
 Column() {
 Text(this.user.name)
 Text(`${this.user.age}`)
 }
 }
}

给类加上 @Observed,子组件用 @ObjectLink 接收,这时候改 this.user.age 就能刷新了。

如果这里用 @Prop user: UserInfo,会发生什么?父组件把对象拷一份给子组件,子组件改 user.age 时,被观察的是 user 这个引用,不是 age 这个属性,所以界面不动。

这一组是 @Prop 的补充,不是替代。判断:传的是简单类型(string / number / boolean),@Prop 够用;传的是对象并且子组件要改它的属性,必须 @Observed + @ObjectLink。

七、一张选择表

把上面四节压成一张表。判断顺序从上到下,命中就停。

场景用什么关键点
组件自己的 UI 状态,销毁即失效@State私有,父组件只能给初始值
子组件纯展示,只需要读父组件的值@Prop单向,对象是浅拷贝,有拷贝成本
子组件要改父组件的数据@Link双向,传参写 $,谨慎放权
隔多层,中间层不关心这个值@Provide/@Consume别名必须一致,@Consume 不能有初值
传对象,且子组件要改它的属性@Observed + @ObjectLink@Prop 在这救不了
想在值变化时做点别的事@Watch 挂在上面任一个后面只做副作用,不改数据

再补一条容易被忽略的:**同一个变量不要挂两个装饰器。**比如 @State @Link 这种写法是错的,它们语义冲突。一个变量只能有一个"身份"。

八、最后一句

这四个装饰器难的不是语法,是在写第一行代码时就想清楚这份数据归谁。归错了,后面所有同步问题都是它的连锁反应——你会发现自己在写各种 onChange 去手动对齐两份数据,那其实就是装饰器选错的信号。

如果你现在正好卡在这块,想找一份把状态管理和 ArkUI 放在一起排的完整案例对照着看,可以看看誉天教育的鸿蒙课,它第一阶段排的是 ArkTS 与开发环境、ArkUI 与状态管理、数据网络与权限、多端适配四块,状态管理跟布局是连着讲的,不是拆成两个独立章节。

Logo

讨论HarmonyOS开发技术,专注于API与组件、DevEco Studio、测试、元服务和应用上架分发等。

更多推荐