HarmonyOS应用《玄象》开发实战：@Prop / @Link / @Provide-@Consume 数据传递在星宿模块的实战

阅读时长：约 19 分钟 | 难度：★★★★☆ | 篇章：第 4 篇 · 二十八星宿模块
对应源码：entry/src/main/ets/pages/mansion/MansionListPage.ets、MansionDetailPage.ets

前言

玄象项目星宿模块涉及多个页面间的数据传递——列表页选中星宿后将名称传给详情页，四象 Tab 切换后列表数据刷新。这些场景分别使用了@Prop、@Link、@Provide-@Consume与router.getParams四种数据传递方式。本篇将深入剖析玄象项目数据传递的实战应用：从@Prop单向数据流、@Link双向绑定、@Provide-@Consume跨层级传值，到router.getParams页面间传参。掌握这套数据传递方法，您就能为任何 HarmonyOS 应用选择最合适的数据流方案。

提示：ArkUI 提供多种数据传递装饰器，选择正确的方式能显著提升代码可维护性。

一、@Prop 单向数据流

1.1 @Prop 特性

• 从父组件传入，子组件只读
• 父组件修改时，子组件自动更新
• 子组件不能修改 @Prop 值

1.2 玄象项目应用

@Componentexportstruct GoldBorderCard{@Propwidth:string='100%';@Propheight:string='auto';@Proppadding:number=16;@PropbgColor:string=Colors.BG_CARD;// ...}

父组件传值：

GoldBorderCard({padding:20,bgColor:Colors.BG_CARD_HIGHLIGHT}){// ...}

二、@Link 双向绑定

2.1 @Link 特性

• 父组件与子组件共享同一状态
• 任意一方修改，双方同步更新
• 适合表单输入等双向交互场景

2.2 玄象项目应用

@Componentexportstruct MansionFilter{@Link@PropcurrentSiXiang:string;build(){// 修改 currentSiXiang，父组件同步更新Text('苍龙').onClick(()=>{this.currentSiXiang='苍龙';})}}

三、@Provide-@Consume 跨层级传值

3.1 @Provide-@Consume 特性

• @Provide在祖先组件提供数据
• @Consume在后代组件消费数据
• 跨任意层级，无需逐层传递

3.2 玄象项目应用

// 祖先组件@Entry@Componentstruct HomePage{@Provide('currentSiXiang')currentSiXiang:string='苍龙';build(){MansionListPage()}}// 后代组件@Entry@Componentstruct MansionListPage{@Consume('currentSiXiang')currentSiXiang:string;build(){Text(this.currentSiXiang)// 自动获取祖先组件的值}}

四、router.getParams 页面间传参

4.1 参数传递

// 列表页发送.onClick(()=>{router.pushUrl({url:'pages/mansion/MansionDetailPage',params:{mansionName:mansion.name}});})

4.2 参数接收

// 详情页接收aboutToAppear():void{constparams=router.getParams()asRecord<string,string>;constname=params['mansionName']||'角宿';this.mansion=MansionData.getMansionByName(name);}

五、数据传递方式对比

5.1 对比表

六、玄象项目数据传递选择

6.1 选择原则

• 父子组件简单传参：@Prop
• 需要双向绑定：@Link
• 跨层级共享：@Provide-@Consume
• 页面间跳转：router.getParams+AppStorage

六、数据传递的最佳实践

6.1 数据传递选择决策树

需要传递数据？ ├─ 父子组件间？ │ ├─ 单向：@Prop │ └─ 双向：@Link ├─ 跨层级组件？ │ └─ @Provide-@Consume └─ 页面间跳转？ └─ router.getParams

6.2 数据传递的性能对比

6.3 玄象项目中数据传递的实际应用

七、数据传递的调试技巧

7.1 数据流追踪

在开发过程中，可通过日志追踪数据传递：

// 在 @Prop 接收方输出日志aboutToAppear():void{hilog.info(0x0000,'DataFlow','MansionDetailPage received: %{public}s',JSON.stringify(router.getParams()));}// 在 @Provide 提供方输出日志@Provide('currentSiXiang')currentSiXiang:string='苍龙';aboutToAppear():void{hilog.info(0x0000,'DataFlow','Provided currentSiXiang: %{public}s',this.currentSiXiang);}

7.2 数据传递的常见错误与排查

7.3 数据传递的性能建议

1. 避免深层传递：超过 3 层时使用 @Provide-@Consume
2. 避免大对象传递：@Prop 传递的对象应尽量精简
3. 避免频繁更新：@State 频繁更新会导致大量 UI 重渲染
4. 使用 AppStorage 替代多层传递：全局状态使用 AppStorage 管理

总结

本篇以玄象项目星宿模块为蓝本，深入剖析了 ArkUI 数据传递四种方式：@Prop单向数据流、@Link双向绑定、@Provide-@Consume跨层级传值、router.getParams页面间传参。掌握这套数据传递方法，您就能为任何 HarmonyOS 应用选择最合适的数据流方案。

如果这篇文章对你有帮助，欢迎点赞👍、收藏⭐、关注🔔，你的支持是我持续创作的动力！

相关资源：

• HarmonyOS 官方文档：@Prop 装饰器
• HarmonyOS 官方文档：@Link 装饰器
• 开源鸿蒙跨平台社区：https://openharmonycrossplatform.csdn.net