HarmonyOS 小游戏《对战五子棋》开发第34篇 - ArkTS中复用UI的方法

把重复的UI代码提取成方法------@Builder是ArkUI的"组件函数"

什么是@Builder

@Builder是ArkTS的装饰器,用于定义可复用的UI构建方法。它类似于"轻量级组件"------不需要声明struct,但可以包含完整的UI代码。

本项目的@Builder使用

AIBattlePage使用了4个@Builder方法:

typescript 复制代码
@Builder
levelSelectView() { /* 关卡选择视图 */ }

@Builder
levelCard(item: LevelConfig) { /* 关卡卡片 */ }

@Builder
gameView() { /* 游戏对战视图 */ }

@Builder
resultDialog() { /* 结果弹窗 */ }

@Builder的调用

typescript 复制代码
build() {
  Stack() {
    Column() {
      // 导航栏...
      if (this.inGame) {
        this.gameView()       // 调用@Builder方法
      } else {
        this.levelSelectView() // 调用@Builder方法
      }
    }

    if (this.inGame && this.showResultDialog) {
      this.resultDialog()      // 调用@Builder方法
    }
  }
}

@Builder方法可以用this.xxx()在build()中调用,就像普通方法一样。

@Builder vs 自定义组件

特性 @Builder @Component struct
声明方式 方法 struct
参数传递 方法参数 @Prop/@Link
状态管理 共享宿主组件状态 独立状态
复用性 仅限当前组件 跨文件复用
适合场景 组件内UI拆分 独立可复用组件

为什么AIBattlePage用@Builder

AIBattlePage有两个主要视图(选关、游戏)和一个弹窗,如果全部写在build()中会非常冗长。用@Builder拆分后:

typescript 复制代码
build() {
  Stack() {
    Column() {
      // 导航栏(共用)
      Row() { ... }
      
      // 根据状态选择视图
      if (this.inGame) {
        this.gameView()       // 100+行UI代码被封装
      } else {
        this.levelSelectView() // 50+行UI代码被封装
      }
    }
    
    if (this.inGame && this.showResultDialog) {
      this.resultDialog()      // 80+行UI代码被封装
    }
  }
}

build()方法变得简洁清晰。

@Builder方法内部访问状态

typescript 复制代码
@Builder
gameView() {
  Column() {
    // 直接访问宿主组件的@State
    Text(this.getStatusText())
    
    if (this.aiThinking) {
      LoadingProgress()
    }
    
    ChessBoardView({
      boardData: this.boardData,
      onCellClick: (row: number, col: number) => {
        this.onCellClick(row, col);
      }
    })
  }
}

@Builder方法可以直接访问宿主组件的所有成员变量和方法------不需要参数传递。

@Builder带参数

typescript 复制代码
@Builder
levelCard(item: LevelConfig) {
  Button() {
    Row({ space: 16 }) {
      Text(item.icon)
        .backgroundColor(item.color)
      
      Column() {
        Text(`第${item.level}关`)
        Text(item.name)
        Text(item.desc)
      }
    }
  }
  .enabled(item.level <= this.unlockedLevel)  // 仍可访问宿主状态
}

参数item是LevelConfig类型,在ForEach中传入:

typescript 复制代码
ForEach(this.levels, (item: LevelConfig) => {
  this.levelCard(item)  // 传参调用
}, (item: LevelConfig) => item.level.toString())

@Builder的嵌套调用

typescript 复制代码
@Builder
levelSelectView() {
  Column({ space: 16 }) {
    Text('选择关卡')
    
    ForEach(this.levels, (item: LevelConfig) => {
      this.levelCard(item)  // @Builder调用@Builder
    }, (item: LevelConfig) => item.level.toString())
  }
}

@Builder方法可以调用其他@Builder方法------形成UI的模块化组合。

ChessBoardView为什么不用@Builder

ChessBoardView是独立组件(@Component export struct),不是@Builder------因为它需要跨文件复用(被TwoPlayerPage和AIBattlePage共用)。

选择原则:

  • 仅在当前组件内使用的UI片段 → @Builder
  • 需要跨组件/跨文件复用 → @Component struct

总结

@Builder是ArkUI中组织UI代码的重要工具:

  1. 代码拆分:将冗长的build()方法分解为逻辑单元
  2. 状态共享:直接访问宿主组件的状态
  3. 参数传递:支持方法参数
  4. 嵌套调用:@Builder可以调用@Builder
  5. 适用场景:组件内的UI复用,不需要跨文件

合理使用@Builder可以让复杂的UI代码保持清晰和可维护。

相关推荐
码间留白4 小时前
AI 给的两个方案都被我否了:把 startIcon 与启动遮罩做成同一张图,鸿蒙 APP 冷启动零白屏
性能优化·uni-app·ai编程·harmonyos
二流小码农5 小时前
鸿蒙开发:证书只能创建3个,第4个应用怎么办
android·ios·harmonyos
敲上瘾5 小时前
Qt核心机制:信号与槽详解
开发语言·c++·qt·ui·qt6.3
威哥爱编程8 小时前
模拟面试智能体开发实战 12:每篇都能跑不等于接起来能跑,端到端联调收官把十一块拼图合成一个能用的智能体
python·agent·harmonyos
威哥爱编程8 小时前
模拟面试智能体开发实战 11:报告只躺在后端怎么复盘,把总评搬上手机还要适配大小屏
python·agent·harmonyos
我闪了个去10 小时前
一个 Scroll 撑起整个首页:HarmonyOS 7 懒加载布局把网格、瀑布流、吸顶分组装进一次滚动
harmonyos·arkts
二流小码农1 天前
鸿蒙开发:router组件升级,彻底告别手动配置
android·ios·harmonyos
FRing031 天前
vue2干货总结10(json-server、vant-ui、postcss插件、axios二次封装、图形验证码、toast轻提示)
开发语言·前端·vue.js·ui·json·vue2·postcss
威哥爱编程2 天前
模拟面试智能体开发实战 09:把面试官装进手机,鸿蒙端聊天界面用 SSE 流式输出让回复逐字滚出来
python·agent·harmonyos
威哥爱编程2 天前
模拟面试智能体开发实战 10:配置写死在代码里还怎么换服务端,把设置和简历做成界面可配、可存
python·agent·harmonyos