《从零到一:鸿蒙原生应用开发实战》第8篇:@Prop 和 @Link 详解——父子组件传值,需要搞懂这两个装饰器

你好，我是华鸿技术栈的作者。

上一篇我们把 @State 拆透了。一个变量改一下，页面跟着变，这种感觉一旦习惯了，会本能地想：那我把页面拆成几个小模块，每个模块有自己的 @State，行不行？

行是行，但有个麻烦——拆出来的模块之间数据不互通。关注按钮拆出去之后，它不知道外面那个粉丝数变了没有。

ArkUI 给了两个专门干这件事的装饰器：@Prop 和 @Link。前者负责父传子，后者负责双向同步。这两个搞定，父子组件之间怎么传数据、怎么同步状态，心里就有谱了。

8.1 一个现实的问题：组件拆开了，数据怎么办

先交代一下背景。下面这种写法，功能没问题，但没法复用：

// 所有东西写在一个 build() 里Column() {  Text('华鸿技术栈')  Text('粉丝：1280')  Button('+ 关注')}

这种写法在页面少的时候还过得去。一旦项目里有三四个页面都用到了同一个关注按钮，你就要把同样的代码复制三四遍。后面要改按钮样式，也得改三四遍。

拆组件是必然的。但拆完之后马上碰到一个问题：关注按钮的“已关注/未关注”状态，是放在按钮自己里面管，还是放在页面里管？

答案是放在页面里管，然后通过 @Prop 或 @Link 传给按钮。父子组件传值的本质：数据统一放在父组件（页面）里，子组件（按钮、卡片）只负责展示和交互。父组件把数据“递”给子组件，需要的时候子组件也能“还”回去。

我带过一些转鸿蒙的开发者，不少人在这里卡住过。状态管理这块，培训有老师带着练一遍，和自己啃文档啃出来的效率差别挺大。后面讲 @Link 的时候再说原因。

8.2 @Prop：父组件传值给子组件，单向

@Prop 是干什么的？ 它让父组件把数据传给子组件。父组件数据变了，子组件同步刷新。子组件自己改了 @Prop 的值，父组件不受影响。

先看代码，感受一下 @Prop 怎么用：

// 子组件：粉丝数展示@Componentstruct FollowerDisplay {  @Prop count: number;  // 父组件传进来的值  build() {    Text(`粉丝：${this.count}`)      .fontSize(16)      .fontColor('#666666')  }}// 父组件@Entry@Componentstruct Page {  @State followerCount: number = 1280;  build() {    Column() {      FollowerDisplay({ count: this.followerCount })  // 把值传进去    }  }}

父组件里 followerCount 变了，FollowerDisplay 显示的数字自动刷新。反过来，如果在 FollowerDisplay 里改了 count 的值，父组件的 followerCount 不会受影响。

@Prop 的核心规则：

• 父传值写法：组件名({ 子组件属性: this.父组件变量 })

• 子组件接收：用 @Prop 修饰同名的属性

• 数据流向：父→子，单项通行

什么时候用 @Prop：子组件只需要读数据，不需要写回去。文章标题、粉丝数、发布时间，这些展示型数据都用 @Prop。

8.3 @Link：父子双向绑定，改哪边都同步

@Link 是干什么的？ 它和 @Prop 的区别就一点：子组件改了 @Link 的值，父组件会同步刷新。父子共享同一份数据，任何一方的修改，另一方立刻感知。

继续用上面的例子，这次把“粉丝数”改成双向绑定：

// 子组件@Componentstruct FollowerDisplay {  @Link count: number;  // 注意，换成了 @Link  build() {    Text(`粉丝：${this.count}`)      .fontSize(16)      .fontColor('#666666')  }}// 父组件@Entry@Componentstruct Page {  @State followerCount: number = 1280;  build() {    Column() {      FollowerDisplay({ count: $followerCount })  // 注意：传值时前面加 $    }  }}

两处改动：子组件的 @Prop 换成 @Link，父组件传值时 this.followerCount 前面加了个 $。就这两处，单向变双向。

@Link 的核心规则：

• 父传值写法：组件名({ 子组件属性: $父组件变量 })，$ 是双向绑定的标识

• 子组件接收：用 @Link 修饰

• 数据流向：父↔子，双向通行

• @Link 的源数据必须是 @State 或其他可观测状态变量，普通变量不行

很多自学的开发者第一次用 @Link 会漏掉 $，然后找半天 bug。培训的时候老师一般会专门强调这个点，因为十个人里有八个第一次都会忘。你在写的时候多留个心，省一趟排查。

8.4 一个完整例子：关注按钮拆出来，独立复用

下面把 @Prop 和 @Link 放在同一个页面里。作者名称是只读的（@Prop），关注状态和粉丝数是双向的（@Link），点击按钮同时改两个数据：

// 子组件1：作者名称（只读）@Componentstruct AuthorName {  @Prop name: string;  build() {    Text(this.name)      .fontSize(24)      .fontWeight(FontWeight.Bold)  }}// 子组件2：关注按钮 + 粉丝数（双向）@Componentstruct FollowSection {  @Link isFollowed: boolean;  @Link followerCount: number;  build() {    Column({ space: 10 }) {      Text(`粉丝：${this.followerCount}`)        .fontSize(16)        .fontColor('#666666')      Button(this.isFollowed ? '已关注' : '+ 关注')        .width(120)        .height(44)        .fontSize(16)        .backgroundColor(this.isFollowed ? '#CCCCCC' : '#007DFF')        .fontColor(Color.White)        .borderRadius(22)        .onClick(() => {          this.isFollowed = !this.isFollowed;          if (this.isFollowed) {            this.followerCount++;          } else {            this.followerCount--;          }        })    }  }}// 父组件：页面@Entry@Componentstruct AuthorPage {  @State authorName: string = '华鸿技术栈';  @State count: number = 1280;  @State followed: boolean = false;  build() {    Column({ space: 20 }) {      // @Prop 传值：只读      AuthorName({ name: this.authorName })      // @Link 传值：双向（注意 $）      FollowSection({ isFollowed: $followed, followerCount: $count })      // 父组件自己的状态文字，随 @Link 同步刷新      Text(this.followed ? '已关注' : '未关注')        .fontSize(14)        .fontColor('#999999')    }    .width('100%')    .height('100%')    .justifyContent(FlexAlign.Center)  }}

跑起来之后，点关注按钮，三个地方同步变：按钮文字和颜色、粉丝数、底部状态文字。数据源头是父组件的 @State，通过 @Link 让子组件也能改，改完父组件和其他子组件自动同步。

8.5 @Prop 和 @Link 怎么选：一张表定下来

选型就一条原则：确定子组件只需要展示数据，用 @Prop；需要子组件反向修改父组件的数据，换 @Link。不要所有传值都用 @Link——数据流越简单，出问题越好查。

8.6 常见的坑，趁早避开

坑一：@Link 传值忘了加 $

// 错FollowSection({ isFollowed: this.followed })// 对FollowSection({ isFollowed: $followed })

不加 $，@Link 不会建立双向绑定，功能直接失效。编辑器一般会标红，但有时候埋在一堆代码里不容易发现。

坑二：该用 @Link 的地方用了 @Prop

点按钮发现父组件数据没变，排查半天发现是 @Prop。@Prop 设计上就不允许子改父，这不是 bug，是装饰器选错了。

坑三：@Link 绑了普通变量

// 错count: number = 0;FollowSection({ followerCount: $count })// 对@State count: number = 0;FollowSection({ followerCount: $count })

@Link 的源头必须是可观测的状态变量，普通变量编译直接报错。

这三个坑，说穿了都简单，但第一次碰到的时候排查过程一般都比较折腾。有些东西有人点一句，三秒钟明白的事；自己摸索，可能一两个小时都耗在一个 $ 符号上。

8.7 本篇总结

父子组件传值，两个装饰器搞定：

• @Prop：父→子，单向。子组件只展示数据，不需要改父组件的值。

• @Link：父↔子，双向。子组件需要反向修改父组件数据时用它，传值时记得在变量前加 $。

常见问题

Q: @Prop 和 @Link 到底选哪个？A: 子组件只需要展示数据，用 @Prop，比如文章标题、粉丝数。子组件需要修改父组件数据，用 @Link，比如关注按钮、开关、输入框。默认先用 @Prop，确定需要反向修改再换 @Link。

Q: @Link 传值时为什么必须加 $？A: $ 是 ArkUI 的语法规定，用来标识“这个变量要双向绑定”。不加 $，框架不会建立双向关系，子组件改了父组件收不到。这是硬性规则，漏了直接失效。

Q: @Prop 和 @Link 能同时在一个子组件里用吗？A: 可以。上面的实战里 FollowSection 同时用了 @Link 修饰的 isFollowed 和 followerCount，一个组件里 @Prop 和 @Link 混合使用完全没问题。

Q: @Link 的源数据能是 @Prop 吗？A: 不能。@Link 的源必须是 @State 或其他可观测状态变量。@Prop 本身是拷贝，不是原始数据源，不能再作为 @Link 的绑定源。

Q: 自学状态管理这块容易卡住，有没有什么建议？A: 状态管理是鸿蒙开发里概念比较密集的部分。自学的常见问题是遇到报错不知道从哪查，一个小问题耗掉很长时间。如果条件允许，找个系统的培训课程跟着练一遍，有人帮你梳理逻辑链、指出容易出错的地方，效率会高不少。如果纯自学，建议每学完一个装饰器就手敲两遍代码，不要复制粘贴——肌肉记忆比眼睛记忆靠谱。

下一篇：父子组件的传值搞定了。但有一种场景 @Prop 和 @Link 都解决不了——数据需要跨很多层组件传递，比如用户登录信息、主题色，整个应用到处都要用，一层层传太傻了。下一篇讲 @Provide 和 @Consume，跨越组件层级直接共享数据。

本文由「华鸿技术栈」原创发布，专注鸿蒙原生应用与元服务开发。分享实战代码、源码解析、性能优化及生态前沿。不讲虚的，只上干货。转载请联系授权。