鸿蒙自定义组件

最新推荐文章于 2025-11-02 00:16:42 发布

原创最新推荐文章于 2025-11-02 00:16:42 发布 · 997 阅读

14 ·

CC 4.0 BY-SA版权

文章标签：

#harmonyos #华为 #鸿蒙 #自定义组件

鸿蒙专栏收录该内容

385 篇文章

订阅专栏

本文同步发表于我的微信公众号，微信搜索程语新视界即可关注，每个工作日都有文章更新

一、自定义组件基本概念

在鸿蒙OS开发中，自定义组件是根据业务需求将系统组件进行扩展和封装，形成可复用的新组件。自定义组件具有以下核心特点：

可组合性：能够组合使用系统组件及其属性和方法
可重用性：可以在不同父组件或容器中多次实例化使用
数据驱动：通过状态变量变化自动驱动UI刷新

二、创建步骤

1. 基本结构定义

@Component
struct MyComponent {
  @State message: string = 'Hello, World!';

  build() {
    Row() {
      Text(this.message)
        .onClick(() => {
          this.message = 'Hello, ArkUI!';
        })
    }
  }
}

关键要素：

@Component装饰器：使struct具备组件化能力
build()函数：必须实现，用于描述UI结构
@State装饰器：管理组件内部状态

备注：如果在其他文件中引用自定义组件，需要使用export关键字进行导出，然后在使用的页面import导入该自定义组件。

2. 组件参数传递

// 父组件使用
@Entry
@Component
struct ParentComponent {
  build() {
    Column() {
      MyComponent({ message: '自定义文本' })
    }
  }
}

备注：

@Entry装饰的自定义组件将作为UI页面的入口。在单个UI页面中，仅允许存在一个。@Entry可以接受一个可选的LocalStorage参数。
@Entry装饰的自定义组件，其build()函数下的根节点唯一且必须为容器组件。
@Component装饰的自定义组件，其build()函数下的根节点唯一可以为非容器组件。

三、注意事项

1. 组件生命周期

自定义组件包含以下生命周期回调：

aboutToAppear：组件即将显示时触发
aboutToDisappear：组件即将销毁时触发

注意：避免在生命周期函数中执行耗时操作

2. 样式继承与隔离

自定义组件默认不继承父组件样式
使用@Styles装饰器定义可复用样式
通过@Extend实现样式扩展

重要：组件内部样式不应影响外部布局

3. 事件处理规范

// 子组件定义事件
@Component
struct ChildComponent {
  @Prop onCustomEvent: () => void;
  
  build() {
    Button('触发事件')
      .onClick(() => {
        this.onCustomEvent?.();
      })
  }
}

// 父组件使用
ChildComponent({
  onCustomEvent: () => {
    console.log('事件触发');
  }
})

建议：

事件命名使用小驼峰格式
避免在事件回调中直接修改父组件状态
复杂逻辑应提取到单独方法中

4. 性能优化

合理使用@Reusable装饰器：

   @Reusable
   @Component
   struct ReusableComponent {
     // ...
   }

使组件能够被框架复用。

2. 避免不必要的重建：

使用@Link替代频繁的@Prop更新
复杂组件考虑拆分状态管理

3. 列表渲染优化：

   ForEach(this.items, (item) => {
     ListItem(item)
   }, (item) => item.id.toString()) // 必须提供key