引言

一、技术背景

1.1 鸿蒙自定义组件的核心概念

• 封装性：将UI结构、样式和逻辑封装在单一组件内，对外暴露清晰的接口。
• 复用性：一次开发，多处使用（如不同页面的商品卡片复用同一组件）。
• 灵活性：通过Props动态配置组件外观（如颜色、尺寸），通过Events响应交互。

1.2 Props与Events的作用

• Props（属性）：父组件向子组件传递的只读数据（如字符串、数字、对象），用于控制组件的显示内容（如卡片标题、图片路径）。Props通过 @Prop或 @State（若需子组件内部修改并同步父组件）装饰器定义。
• Events（事件）：子组件向父组件通信的机制（如用户点击卡片触发回调），通过 @Event装饰器定义事件名称，并通过 emit方法触发父组件的监听函数。

二、应用使用场景

三、不同场景下的代码实现

3.1 场景1：基础通用卡片组件（带Props，ArkTS）

需求描述

代码实现

// CommonCard.ets（通用卡片组件）
@Entry
@Component
struct CommonCard {
  // Props：通过 @Prop 接收父组件传递的数据（只读）
  @Prop title: string = '默认标题';
  @Prop description: string = '默认描述';
  @Prop imageUrl: string = '';

  build() {
    Column() {
      // 图片区域（若有图片路径）
      if (this.imageUrl) {
        Image(this.imageUrl)
          .width('100%')
          .height(120)
          .borderRadius(8)
          .objectFit(ImageFit.Cover)
      }

      // 文本区域
      Column() {
        Text(this.title)
          .fontSize(18)
          .fontWeight(FontWeight.Bold)
          .margin({ bottom: 8 })
        Text(this.description)
          .fontSize(14)
          .fontColor('#666')
          .textAlign(TextAlign.Start)
      }
      .width('100%')
      .padding({ left: 12, right: 12, top: 8, bottom: 12 })
    }
    .width('90%')
    .height(this.imageUrl ? 250 : 80) // 动态高度（含图片时更高）
    .backgroundColor('#FFFFFF')
    .borderRadius(12)
    .shadow({ radius: 4, color: '#00000010', offsetX: 0, offsetY: 2 }) // 阴影效果
    .margin({ bottom: 10 })
  }
}

父组件调用示例

// ParentPage.ets（使用通用卡片组件的父页面）
@Entry
@Component
struct ParentPage {
  build() {
    Column() {
      Text('通用卡片组件示例')
        .fontSize(24)
        .margin({ bottom: 20 })

      // 使用 CommonCard 组件，传递 Props
      CommonCard({
        title: '商品标题1',
        description: '这是商品的详细描述，支持多行文本展示。',
        imageUrl: '/resources/base/media/product1.jpg' // 假设图片放在 resources/base/media/ 目录
      })

      CommonCard({
        title: '用户信息卡片',
        description: '展示用户的简要介绍，无图片。',
        imageUrl: '' // 无图片
      })
    }
    .width('100%')
    .height('100%')
    .padding(20)
  }
}

关键点解释

• Props定义：通过 @Prop装饰器定义 title、description和 imageUrl，父组件通过对象参数传递数据（如 title: '商品标题1'）。
• 动态布局：根据 imageUrl是否存在，动态调整卡片高度（含图片时为 250px，无图片时为 80px）。
• 样式封装：卡片统一设置圆角、阴影和背景色，提升视觉一致性。

3.2 场景2：带Events交互的卡片组件（点击回调，ArkTS）

需求描述

代码实现

// InteractiveCard.ets（带点击事件的卡片组件）
@Entry
@Component
struct InteractiveCard {
  @Prop title: string = '默认标题';
  @Prop description: string = '默认描述';
  @Prop imageUrl: string = '';

  // Event：通过 @Event 定义点击事件（父组件需监听此事件）
  @Event onClick: () => void;

  build() {
    Column() {
      if (this.imageUrl) {
        Image(this.imageUrl)
          .width('100%')
          .height(120)
          .borderRadius(8)
          .objectFit(ImageFit.Cover)
      }

      Column() {
        Text(this.title)
          .fontSize(18)
          .fontWeight(FontWeight.Bold)
          .margin({ bottom: 8 })
        Text(this.description)
          .fontSize(14)
          .fontColor('#666')
          .textAlign(TextAlign.Start)
      }
      .width('100%')
      .padding({ left: 12, right: 12, top: 8, bottom: 12 })
    }
    .width('90%')
    .height(this.imageUrl ? 250 : 80)
    .backgroundColor('#FFFFFF')
    .borderRadius(12)
    .shadow({ radius: 4, color: '#00000010', offsetX: 0, offsetY: 2 })
    .margin({ bottom: 10 })
    // 监听卡片整体点击事件
    .onClick(() => {
      this.onClick(); // 触发父组件的 onClick 事件
    })
  }
}

父组件调用示例（监听点击事件）

// ParentPageWithEvent.ets
@Entry
@Component
struct ParentPageWithEvent {
  // 处理卡片点击事件（父组件自定义逻辑）
  handleCardClick() {
    console.log('卡片被点击！可在此处跳转详情页或显示弹窗');
    // 示例：弹出提示
    AlertDialog.show({
      title: '提示',
      message: '您点击了卡片！',
      confirm: {
        value: '确定',
        action: () => {}
      }
    });
  }

  build() {
    Column() {
      Text('带交互的通用卡片组件')
        .fontSize(24)
        .margin({ bottom: 20 })

      // 使用 InteractiveCard 组件，传递 Props 并监听 onClick 事件
      InteractiveCard({
        title: '可点击的商品卡片',
        description: '点击此卡片将触发父组件的回调逻辑。',
        imageUrl: '/resources/base/media/product1.jpg'
      }, (onClick: () => void) => {
        // 绑定点击事件（鸿蒙中通过参数传递回调函数）
        onClick = () => this.handleCardClick();
      })
    }
    .width('100%')
    .height('100%')
    .padding(20)
  }
}

关键点解释

• Events定义：通过 @Event onClick: () => void定义点击事件，子组件通过 this.onClick()触发事件。
• 父组件监听：父组件在调用 InteractiveCard时，通过回调函数（如 (onClick) => { onClick = () => this.handleCardClick(); }）绑定具体的交互逻辑（如弹窗、页面跳转）。

注意：鸿蒙 ArkTS 中事件的传递通常通过 参数回调​ 实现（类似 Vue 的 v-on），而非直接的事件绑定语法（如 @click）。更常见的做法是通过 @Observed和 @ObjectLink实现父子组件状态同步，但基础场景可通过回调函数简化。

3.3 场景3：多类型卡片组件（动态Props，ArkTS）

需求描述

代码实现

// DynamicCard.ets（多类型通用卡片组件）
@Entry
@Component
struct DynamicCard {
  @Prop cardType: string = 'default'; // 卡片类型：'product'（商品）、'user'（用户）、'news'（新闻）
  @Prop title: string = '默认标题';
  @Prop description: string = '默认描述';
  @Prop imageUrl: string = '';
  @Prop price: string = ''; // 仅商品类型使用
  @Prop userName: string = ''; // 仅用户类型使用

  build() {
    Column() {
      // 根据类型动态渲染内容
      if (this.cardType === 'product' && this.imageUrl) {
        Image(this.imageUrl)
          .width('100%')
          .height(120)
          .borderRadius(8)
          .objectFit(ImageFit.Cover)

        Column() {
          Text(this.title)
            .fontSize(18)
            .fontWeight(FontWeight.Bold)
            .margin({ bottom: 8 })
          Text(this.description)
            .fontSize(14)
            .fontColor('#666')
            .margin({ bottom: 8 })
          Text(this.price)
            .fontSize(16)
            .fontColor('#FF6B35')
            .fontWeight(FontWeight.Medium) // 商品价格高亮
        }
        .width('100%')
        .padding(12)

      } else if (this.cardType === 'user' && this.imageUrl) {
        Image(this.imageUrl)
          .width(60)
          .height(60)
          .borderRadius(30)
          .objectFit(ImageFit.Cover)
          .margin({ bottom: 10 })

        Text(this.userName)
          .fontSize(16)
          .fontWeight(FontWeight.Bold)
        Text(this.description)
          .fontSize(14)
          .fontColor('#666')
      } else {
        // 默认类型（无图片或基础文本）
        Column() {
          Text(this.title)
            .fontSize(18)
            .fontWeight(FontWeight.Bold)
            .margin({ bottom: 8 })
          Text(this.description)
            .fontSize(14)
            .fontColor('#666')
        }
        .width('100%')
        .padding(12)
      }
    }
    .width('90%')
    .backgroundColor('#FFFFFF')
    .borderRadius(12)
    .margin({ bottom: 10 })
  }
}

父组件调用示例（动态配置类型）

// ParentPageDynamic.ets
@Entry
@Component
struct ParentPageDynamic {
  build() {
    Column() {
      Text('多类型通用卡片组件')
        .fontSize(24)
        .margin({ bottom: 20 })

      // 商品卡片
      DynamicCard({
        cardType: 'product',
        title: '商品A',
        description: '这是一款优质商品',
        imageUrl: '/resources/base/media/product1.jpg',
        price: '¥299.00'
      })

      // 用户卡片
      DynamicCard({
        cardType: 'user',
        title: '用户信息',
        description: '用户简介',
        imageUrl: '/resources/base/media/avatar.jpg',
        userName: '张三'
      })

      // 默认文本卡片
      DynamicCard({
        title: '普通文本卡片',
        description: '无图片的简单文本展示'
      })
    }
    .width('100%')
    .height('100%')
    .padding(20)
  }
}

关键点解释

• 动态Props：通过 cardType区分卡片类型，并根据类型选择性渲染特定内容（如商品卡片显示价格，用户卡片显示头像）。
• 扩展性：通过新增 Props（如 price、userName）支持更多字段，无需修改组件核心逻辑。

四、原理解释与核心特性

4.1 自定义组件的工作流程

sequenceDiagram
    participant Parent as 父组件（调用方）
    participant Child as 自定义组件（CommonCard/InteractiveCard）
    participant Renderer as 渲染引擎

    Parent->>Child: 传递 Props（如 title、imageUrl）
    Parent->>Child: 绑定 Events（如 onClick 回调）
    Child->>Renderer: 根据 Props 渲染 UI 结构
    User->>Child: 触发交互（如点击卡片）
    Child->>Parent: 通过 Events 通知交互（调用 onClick 回调）
    Parent->>Renderer: 执行父组件的自定义逻辑（如跳转页面）

• Props传递：父组件通过对象参数向子组件传递数据（如 title: '商品标题'），子组件通过 @Prop装饰器接收并渲染。
• Events通信：子组件通过 @Event定义事件（如 onClick），父组件绑定回调函数，子组件在交互时触发事件（如 this.onClick()），实现双向通信。
• 封装复用：子组件封装了UI结构、样式和基础交互逻辑，父组件仅需关注数据传递和事件处理，无需重复编写代码。

4.2 核心特性

五、环境准备

5.1 开发工具与项目配置

• 工具：鸿蒙开发工具 DevEco Studio（版本 3.2+）。
• 模板：创建新项目时选择“Empty Ability”模板（基于 ArkTS）。
• 资源目录：图片资源（如 product1.jpg）需放在 resources/base/media/目录下，通过相对路径引用（如 /resources/base/media/product1.jpg）。

5.2 实际应用示例（完整可运行）

场景：电商商品列表（通用卡片 + 列表渲染）

1. 功能：使用 ForEach循环渲染多个商品卡片（通过通用卡片组件），每个卡片通过 Props 传递商品数据（图片、标题、价格），并通过 Events 监听点击购买。
2. 代码扩展：结合 场景1（通用卡片）​ 和 场景2（事件交互），在父组件中循环生成商品数据并传递 Props/Events。
3. 运行效果：商品列表展示统一的卡片样式，点击任意卡片触发购买提示。

六、测试步骤与详细代码

测试1：验证Props传递

1. 步骤：运行 ParentPage.ets，检查通用卡片组件是否正确显示传递的标题、描述和图片。
2. 预期：卡片内容与父组件传递的 Props 一致（如标题为“商品标题1”，图片为指定路径的图片）。

测试2：验证事件交互

1. 步骤：运行 ParentPageWithEvent.ets，点击卡片。
2. 预期：弹出提示框（或执行父组件定义的回调逻辑，如“您点击了卡片！”）。

测试3：验证多类型卡片

1. 步骤：运行 ParentPageDynamic.ets，检查不同 cardType的卡片是否按预期渲染（如商品卡片显示价格，用户卡片显示头像）。
2. 预期：每种类型的卡片布局和内容符合对应业务需求。

七、部署场景

• 电商应用：商品列表、购物车项等复用通用卡片组件，通过 Props 传递商品数据，通过 Events 处理购买/收藏。
• 社交应用：用户信息卡片、动态消息卡片等，动态配置类型并复用布局。
• 新闻资讯：文章列表卡片，通过 Props 传递标题、摘要和时间，通过 Events 监听点击阅读。

八、疑难解答

8.1 常见问题

8.2 调试技巧

• 日志输出：在子组件的 build方法中添加 console.log，打印接收到的 Props（如 console.log('标题:', this.title)）。
• 事件监听验证：在父组件的事件处理函数中打印日志（如 handleCardClick() { console.log('卡片被点击！'); }），确认事件是否触发。
• DevEco Studio 预览：通过 Previewer​ 实时查看组件在不同数据下的渲染效果。

九、未来展望与技术趋势

1. 状态管理集成：结合鸿蒙的 @State/@Observed​ 实现父子组件状态同步（如子组件修改 Props 后同步到父组件）。
2. 动态主题支持：通过 Props 传递主题配置（如颜色、字体），实现卡片的动态换肤。
3. 跨平台复用：通用卡片组件的逻辑可能通过统一规范适配不同平台（如 Android/iOS），提升多端一致性。
4. AI 辅助生成：未来可能通过 AI 工具根据需求自动生成通用卡片组件的 Props 和 Events 定义，减少手动编码。

十、总结

• Props​ 允许父组件动态传递数据（如标题、图片），控制组件的显示内容；
• Events​ 实现子组件向父组件通信（如点击交互），支持自定义业务逻辑；
• 核心价值：通过封装通用UI模块，减少冗余代码，适应多场景需求（如商品、用户、新闻卡片），是构建高质量鸿蒙应用的基础能力。