鸿蒙开发-ArkTS 创建自定义组件

news2025/1/26 15:43:00

在 ArkTS 中创建自定义组件是一个相对简单但功能强大的过程。以下是如何在 ArkTS 中创建和使用自定义组件的详细步骤：

一、定义自定义组件

使用@Component注解：为了注册一个组件，使其能够在其他文件中被引用，你需要使用@Component注解。例如：

@Component
struct MyComponent {
  build() {
    Column() {
      Text('自定义组件')
      Button('点击')
    }
  }
}

组件命名规则：一个项目下所有的自定义组件名不可以重复，无论是否在一个.ets文件中。
根组件要求：被@Component装饰的组件（包括主组件和其他自定义组件），其build()方法中必须有且仅有一个根容器组件。

二、自定义组件的属性与样式

属性：你可以在组件中定义属性，并通过父组件传递值来动态改变这些属性。例如，通过@State定义状态变量，并在build()方法中使用这些变量。
样式：组件内的样式不会受外界调用时的影响，只会缩放（可能还会直接少显示一部分），不会改变颜色、位置、方法等。因此，在使用组件时，需要给其留有充足的位置。

三、自定义组件的成员变量与函数

成员变量：为了更好的让自定义组件灵活使用，ArkTS允许对自定义组件里面的成员变量进行赋值，但是不允许对成员函数赋值。如果要改变函数，则需要使用箭头函数的形式来调用函数。
成员函数：你可以在组件中定义成员函数，并在需要时调用它们。例如，定义一个按钮的点击事件处理函数。

四、使用@BuilderParams传递UI组件

在组件中，你可以使用@BuilderParam来指定一个为箭头函数的成员参数，这个箭头函数可以设置一个初始的默认值。这样，父组件就可以在调用子组件时，传入自定义的结构来替换子组件的默认结构。这类似于Vue中的插槽功能。

五、自定义布局

如果默认的布局方式不能满足你的需求，你还可以自定义布局。这通常涉及到重写onMeasureSize和onPlaceChildren方法，以精确控制子组件的位置和大小。

六、示例

以下是一个完整的示例，展示了如何创建一个自定义组件并在父组件中使用它：

// MyComponent.ets
@Component
struct MyComponent {
  @State message: string = '这是一个自定义组件'
 
  build() {
    Column() {
      Text(this.message)
        .fontSize(20)
        .width(200)
        .height(20)
        .textAlign(TextAlign.Center)
        .fontColor('#ccc')
        .backgroundColor(Color.White)
    }
  }
}
 
// Index.ets
import { MyComponent } from '../components/MyComponent'
 
@Entry
@Component
struct Index {
  build() {
    Column() {
      MyComponent()
        .width('100%')
        .backgroundColor('#BFECFF') // 父组件设置的背景颜色不会改变子组件的背景颜色
    }
  }
}