核心规则

ArkTS 中自定义UI组件必须使用 struct 定义，不支持使用 class 定义UI组件；class 仅用于定义纯逻辑类与数据模型。

/**
 * 自定义按钮组件
 * @description 通用操作按钮，支持多种样式配置
 */
@Component // 标记为UI组件
struct CustomButton {
  // 组件属性定义
  @Prop label: string = "确定"; // 按钮文本
  @Prop buttonType: ButtonType = ButtonType.Normal; // 按钮类型
  @Prop onClick: () => void; // 点击回调

  // 组件生命周期
  aboutToAppear() {
    // 组件即将显示时执行
    console.log(`按钮 ${this.label} 即将显示`);
  }

  aboutToDisappear() {
    // 组件即将销毁时执行
    console.log(`按钮 ${this.label} 即将销毁`);
  }

  // UI构建方法（必须实现）
  build() {
    Button(this.label)
      .type(this.buttonType)
      .onClick(() => {
        if (this.onClick) {
          this.onClick();
        }
      })
      .height(44)
      .padding({ left: 16, right: 16 })
  }
}

// 页面入口组件示例
@Entry // 标记为页面入口
@Component
struct HomePage {
  build() {
    Column() {
      Text("首页")
        .fontSize(24)
      
      // 引用自定义组件
      CustomButton({
        label: "登录",
        buttonType: ButtonType.Primary,
        onClick: () => {
          console.log("点击登录")
        }
      })
    }
    .width('100%')
    .height('100%')
    .padding(20)
  }
}

性能红线

build() 方法会在状态变化时频繁执行，任何耗时操作都会直接导致UI卡顿，所有非UI逻辑必须移到生命周期方法或事件回调中。

/**
 * 商品卡片组件
 * @description 展示商品信息，支持收藏状态切换
 */
@ObservedV2 // API 12+，启用深度状态监听
@Component
struct ProductCard {
  @Prop product: Product; // 商品数据
  @Link isFavorite: boolean; // 收藏状态（双向绑定）
  @State isLoading: boolean = false; // 加载状态（组件内部状态）

  // 监听收藏状态变化
  @Watch('isFavorite')
  onFavoriteChange(newValue: boolean) {
    console.log(`商品${this.product.id}收藏状态变更为: ${newValue}`);
  }

  // 提取重复UI逻辑
  @Builder
  PriceTag(price: number) {
    Text(`¥${price.toFixed(2)}`)
      .fontSize(16)
      .fontColor(Color.Red)
      .fontWeight(FontWeight.Bold)
  }

  build() {
    Column() {
      Image(this.product.imageUrl)
        .width('100%')
        .height(200)
        .objectFit(ImageFit.Cover)
      
      Text(this.product.name)
        .fontSize(14)
        .maxLines(2)
        .textOverflow({ overflow: TextOverflow.Ellipsis })
      
      this.PriceTag(this.product.price)
      
      Toggle({ type: ToggleType.Checkbox, isOn: this.isFavorite })
        .selectedColor(Color.Red)
        .onChange((isOn) => {
          this.isFavorite = isOn;
        })
    }
    .width('48%')
    .padding(10)
    .borderRadius(8)
    .backgroundColor(Color.White)
  }
}

// 通用样式定义
@Styles
function cardStyle() {
  .borderRadius(8)
  .backgroundColor(Color.White)
  .shadow({ radius: 4, color: '#1A000000', offsetX: 0, offsetY: 2 })
}

// 扩展Text组件样式
@Extend(Text)
function titleText() {
  .fontSize(16)
  .fontWeight(FontWeight.Bold)
  .fontColor('#333')
}

// 使用示例
@Component
struct NewsCard {
  @Prop title: string;
  @Prop content: string;

  build() {
    Column() {
      Text(this.title)
        .titleText() // 使用扩展样式
      
      Text(this.content)
        .fontSize(14)
        .fontColor('#666')
        .margin({ top: 8 })
    }
    .width('100%')
    .padding(16)
    .cardStyle() // 使用通用样式
  }
}

// ✅ 推荐：通过interface定义组件属性
interface UserCardProps {
  user: User;
  showAvatar?: boolean;
  onFollow?: () => void;
  onMessage?: () => void;
}

@Component
struct UserCard {
  @Prop props: UserCardProps; // 统一接收属性对象

  build() {
    // 组件实现
  }
}

// 组件目录结构示例
// src/main/ets/components/
// ├── common/              # 基础公共组件
// │   ├── CustomButton.ets
// │   ├── Loading.ets
// │   └── index.ts
// ├── business/            # 业务通用组件
// │   ├── UserCard.ets
// │   ├── ProductCard.ets
// │   └── index.ts
// └── pages/               # 页面级组件
//     ├── HomePage.ets
//     ├── MinePage.ets
//     └── index.ts