HarmonyOS应用开发实战(基础篇)Day11 -《组件复用》

组件复用

组件复用

在鸿蒙应用开发过程中,随着项目规模扩大,页面逻辑和 UI 结构会变得日益复杂。若将所有代码写在单一组件中,不仅会导致可读性下降 ,还会造成重复代码泛滥 ,严重违背"DRY(Don't Repeat Yourself)"原则。

因此,组件复用 成为提升开发效率、保障代码一致性、降低维护成本的关键手段。通过将通用 UI 片段(如用户卡片、商品项、消息气泡等)抽取为独立单元,我们可以在多个页面或列表中无缝复用,实现"一次编写,多处使用"。

正如你在开发中可能遇到的困惑:"这个 UI 片段散落在多个地方,修改起来太麻烦"------这正是组件化要解决的核心问题。

🎯 复用目标:

  • 提高代码可维护性
  • 减少冗余逻辑
  • 支持团队协作(UI 与逻辑解耦)
  • 便于单元测试

在 ArkTS 中,官方提供了两种主流的组件复用方式:

  1. 抽取为独立组件文件(使用 @Component + @Prop)
  2. 定义为自定义构建器(使用 @Builder)

下面我们将分别详解这两种方式的实现细节、适用场景与注意事项。


提取到文件夹中(独立组件)

这是最常用、最推荐 的组件复用方式,尤其适用于跨页面、跨模块 的 UI 单元。其核心思想是:将一段 UI 逻辑封装成一个可接收外部数据的独立组件 ,并通过 @Prop 装饰器实现单向数据流(父 → 子)。

实现步骤

  1. 在项目目录下创建专门的组件文件夹(如 components 或 ui);
  2. 新建 .ets 文件(如 UserList.ets);
  3. 使用 @Component 声明组件,并通过 @Prop 接收外部传入的数据;
  4. 在需要使用的地方导入并调用该组件。
ts 复制代码
// src/main/ets/components/UserList.ets
import { User } from "../common/UserDemo"

@Component
export struct UserList {
  @Prop item: User; // 接收父组件传入的用户对象

  build() {
    Column() {
      Text('姓名:' + this.item.name)
        .fontSize(16)
        .fontWeight(FontWeight.Bold)
      Text('邮箱:' + this.item.email)
        .fontSize(14)
        .fontColor('#666')
    }
    .width('100%')
    .padding(10)
    .backgroundColor('#f9f9f9')
    .borderRadius(8)
  }
}

💡 关键点解析:

  • @Prop :表示该属性由父组件传入,子组件不可修改(单向绑定),确保数据流清晰;
  • export struct:必须导出,才能被其他文件导入;
  • 路径规范 :建议将组件集中管理,如 src/main/ets/components/,便于查找与维护。

使用方式

在父组件中导入 UserList,并通过大括号 {} 传递参数(这是 ArkTS 的语法要求):

ts 复制代码
// 在 Index.ets 中使用
import { UserList } from '../components/UserList'

// ...
ForEach(this.users, (item: User) => {
  UserList({ item: item }) // 注意:必须用 { } 包裹参数
})

⚠️ 常见错误 :

若写成 UserList(item)(无大括号),编译器会报错,因为 ArkTS 要求具名参数必须显式声明。

优势与适用场景

  • ✅ 高内聚低耦合 :组件内部逻辑封闭,仅通过 @Prop 暴露接口;
  • ✅ 支持 TypeScript 类型检查:传参时自动校验类型;
  • ✅ 可跨页面复用:如用户卡片既可用于"联系人列表",也可用于"聊天详情";
  • ✅ 便于样式统一 :修改 UserList.ets 即可全局生效。

Builder(自定义构建器)

@Builder 是 ArkTS 提供的一种轻量级 UI 复用机制 ,适用于同一组件内部 的 UI 片段提取。它本质上是一个带参数的函数 ,返回一段 UI 描述,不创建新的组件实例,性能开销极低。

实现方式

在当前组件内部定义 @Builder 方法:

ts 复制代码
// 在 Index.ets 内部
@Builder
musicBuildList(item: User) {
  Column() {
    Text('姓名:' + item.name)
      .fontSize(16)
    Text('邮箱:' + item.email)
      .fontSize(14)
  }
  .width('100%')
  .padding(10)
  .margin(5)
}

使用方式

直接在 build() 中调用,无需导入:

ts 复制代码
ForEach(this.users, (item: User) => {
  this.musicBuildList(item) // 直接调用,像函数一样
})

优势与局限

优势 局限
✅ 语法简洁,无额外文件 ❌ 仅限当前组件内部使用
✅ 零性能开销(无组件实例化) ❌ 无法跨页面复用
✅ 适合简单、高频的 UI 片段 ❌ 不支持 @State、@Prop 等状态管理

📌 使用建议:

  • 若某段 UI 仅在一个页面内重复出现 (如列表项、表单项),优先使用 @Builder;
  • 若需跨页面共享 ,或包含复杂交互逻辑(如点击事件、状态变化),则应使用独立组件。

两种方式对比总结

特性 独立组件(@Component + @Prop) 自定义构建器(@Builder)
作用域 全局(可跨页面) 仅当前组件内部
数据传递 通过 @Prop(单向) 函数参数(值传递)
状态管理 支持 @State, @Link 等 不支持
性能开销 有组件实例化成本 几乎为零
适用场景 通用 UI 单元(卡片、按钮、弹窗) 页面内重复 UI 片段
工程结构 需新建文件,目录清晰 代码内联,快速实现

最佳实践建议

  1. 命名规范:

    • 独立组件:PascalCase(如 UserCard.ets)
    • Builder:camelCase(如 renderUserItem)
  2. 目录组织:

    复制代码
    src/main/ets/
    ├── components/       # 通用组件
    │   ├── UserCard.ets
    │   └── ProductItem.ets
    ├── pages/            # 页面组件
    └── common/           # 工具类、模型
  3. 避免过度拆分 :

    若某 UI 片段仅使用一次,无需强行抽取,保持代码简洁性更重要。

  4. 类型安全 :

    无论哪种方式,都应为参数添加 TypeScript 类型注解,如 item: User。


通过合理运用 独立组件 与 自定义构建器 ,开发者可以构建出高内聚、低耦合、易维护的鸿蒙应用架构,大幅提升开发效率与代码质量。

相关推荐
HMS工业网络8 小时前
工业远程访问的五项安全部署原则
运维·服务器·安全
知白映川10 小时前
一个不上传数据的工具,怎么知道自己有没有人用
安全·架构
山东科恩光电11 小时前
安全地毯压敏传感技术在自动化产线与仓储区域的人员检测及联动停机防护方案
安全
爱写Bug的浮游14 小时前
初识仓颉:5 分钟看懂核心语法
harmonyos·编程语言
重生之我是萧炎14 小时前
PR安装教程,Adobe Premiere Pro安装教程(含安装包),仅供学习使用
学习·adobe
蒸蒸yyyyzwd15 小时前
深搜广搜学习笔记
笔记·学习
叼烟扛炮16 小时前
[LangChain] 学习笔记(13):并发不是越大越好——batch / gather / 信号量 / 配额治理
笔记·学习·langchain
如夏倾城16 小时前
五大远程桌面协议:RDP、SSH、VNC/RFB、Citrix ICA/HDX 与 VMware Blast Extreme
运维·windows·网络协议·安全·自动化·ssh·远程工作
羽落•无痕(苏晗默)16 小时前
华为数通IA——14、网络服务与应用:TCP/UDP 传输层协议与 FTP、Telnet、SSH 实践
网络·网络协议·tcp/ip·网络安全·华为·udp·信息与通信
0xBADCODE16 小时前
2026 工业互联网安全大赛 · 全国预选赛题解系列密码学方向 crypto-5
网络·安全·web安全·网络安全·系统安全·密码学