// src/main/ets/components/UserCard.ets
import { User } from "../common/UserDemo"

@Component
export struct UserCard {
  @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/，统一管理。

🔧 使用方式

在父组件中导入并调用：

import { UserCard } from '../components/UserCard'

// ...
ForEach(this.users, (item: User) => {
  UserCard({ item: item }) // ⚠️ 必须用 { } 包裹参数！
})

❌ 常见错误：
写成 UserCard(item) 会报错！ArkTS 要求具名参数必须显式声明。

✅ 优势

• • 跨页面复用：一个组件，处处可用
• • 类型安全：TypeScript 自动校验 item 类型
• • 样式统一：改一处，全局生效
• • 支持状态管理：可使用 @State、@Link 等

🛠️ 方案二：自定义构建器 @Builder（轻量级复用）

@Builder 是一种函数式 UI 复用机制，适用于同一页面内的重复片段。

✅ 实现方式

在当前组件内部定义：

// 在 Index.ets 内部
@Builder
renderUserItem(item: User) {
  Column() {
    Text('姓名：' + item.name)
    Text('邮箱：' + item.email)
  }
  .padding(10)
  .margin(5)
}

🔧 使用方式

直接调用，像普通函数：

ForEach(this.users, (item: User) => {
  this.renderUserItem(item) // 无需导入，直接调用
})

✅ 优势 vs ❌ 局限

📌 使用建议：

• • 列表项、表单项等页面内重复内容 → 用 @Builder
• • 用户卡片、弹窗、按钮等通用 UI → 用独立组件

🆚 终极对比：一张表看懂怎么选

🧭 最佳实践建议

1. 命名规范

• • 独立组件：PascalCase → UserCard.ets
• • Builder：camelCase → renderUserItem

2. 目录组织

src/main/ets/
├── components/       # 通用组件
│   ├── UserCard.ets
│   └── ProductItem.ets
├── pages/            # 页面
└── common/           # 模型、工具类

3. 避免过度拆分

若某 UI 只用一次，不要强行抽取！保持代码简洁更重要。

4. 强类型约束

无论哪种方式，务必添加 TypeScript 类型注解：

renderUserItem(item: User) // ✅ 明确类型

💎 总结

• • 独立组件（@Component） = 重型武器 → 跨页面、复杂交互、长期维护
• • 自定义构建器（@Builder） = 轻量工具 → 页面内、简单 UI、快速实现

🌟 高手思维：
不是“会不会拆组件”，而是“在正确场景用最合适的方式”。

掌握这两种复用模式，你就能构建出结构清晰、易于扩展、团队友好的鸿蒙应用架构！

作者：程序员小V（VON）
专注 HarmonyOS / Flutter / OpenHarmony 开发
用代码构建生态，用分享照亮他人

👉 关注我的 CSDN 主页，获取更多鸿蒙实战教程：
🔗 https://blog.csdn.net/2302_80329073