HarmonyOS7 @Builder 把重复 UI 收起来：别急着拆组件

最新推荐文章于 2026-07-24 21:50:47 发布

原创最新推荐文章于 2026-07-24 21:50:47 发布 · 1.4k 阅读

6 ·

本内容遵循CC 4.0 BY-SA版权协议

GEO检测

一张适合技术文章开篇的 sketch-notes 风格框架图，主题是 HarmonyOS 7 中 `

文章目录

前言

页面里重复三次以上的标题栏、设置行、状态标签，复制粘贴肯定能跑，但后面改样式会很痛苦。

这时候很多人会立刻拆组件。我的习惯是先判断：这个 UI 片段是不是只在当前页面复用？有没有独立状态？会不会跨页面使用？如果答案都偏轻，用 @Builder 更合适。

@Builder 适合收起当前组件里的局部重复，不是所有组件拆分的替代品。

一张 sketch-notes 风格的对比表插图，内容是 "直接复制 / @Builder / 独立

为什么这个问题经常被写乱

@Builder 把重复 UI 收起来这类内容很容易被写成“代码能跑就算讲完了”，但对初学者来说，这恰恰是最不够的地方。真正让人卡住的，往往不是某个组件名记不住，而是不知道这段代码为什么要这样拆、状态为什么要这样放、以后需求变化时应该从哪里改。

所以这篇文章不只想给你一个能跑的例子，更想把背后的判断过程讲清楚。你只要把这个判断过程吃透，后面自己改页面、补需求、查问题时，心里会稳很多。

Builder 和组件怎么选

写法	适合场景	代价
直接复制	一两处临时 UI	后期样式容易漂移
`@Builder`	同页面局部重复	不适合承载复杂业务状态
独立组件	多页面复用、有明确接口	命名和参数要设计清楚

设置页是 @Builder 很适合的场景：分组标题、普通设置行、开关设置行都很像，但还没必要拆成一堆文件。

复制粘贴省的是当下几分钟，后面统一改样式时会还回来。

先把页面目标想清楚

一张 sketch-notes 风格的流程图，表现写页面前的判断过程：先想清楚页面目标和用户最在意的

在真正写代码之前，先别急着盯着 API。更有用的做法是先想清楚：这个页面到底想解决什么问题，用户最在意的反馈是什么，哪些状态必须一直保持一致。

当你先把这条主线想明白，再回头看组件和状态设计，很多选择都会顺理成章。对小白来说，这一步尤其重要，因为它能帮你从“照着抄”慢慢过渡到“看得懂、改得动”。

完整 ArkUI 示例

下面这个设置页用三个 @Builder 收起重复 UI：分组标题、普通设置行、开关设置行。

@Entry
@Component
struct SettingsBuilderPage {
  @State pushEnabled: boolean = true
  @State useCellular: boolean = false

  @Builder
  SectionTitle(title: string) {
    Text(title)
      .fontSize(13)
      .fontColor('#888888')
      .width('100%')
      .padding({ left: 4, top: 12, bottom: 6 })
  }

  @Builder
  SettingRow(title: string, desc: string, value: string) {
    Row() {
      Column({ space: 4 }) {
        Text(title).fontSize(16).fontColor('#222222')
        Text(desc).fontSize(12).fontColor('#888888').maxLines(1)
      }
      .alignItems(HorizontalAlign.Start)
      .layoutWeight(1)
      Text(value).fontSize(14).fontColor('#666666')
      Text('>').fontSize(16).fontColor('#BBBBBB').margin({ left: 6 })
    }
    .padding(14)
    .backgroundColor(Color.White)
  }

  @Builder
  SwitchRow(title: string, desc: string, enabled: boolean, onChange: (value: boolean) => void) {
    Row() {
      Column({ space: 4 }) {
        Text(title).fontSize(16)
        Text(desc).fontSize(12).fontColor('#888888')
      }
      .alignItems(HorizontalAlign.Start)
      .layoutWeight(1)
      Toggle({ type: ToggleType.Switch, isOn: enabled })
        .onChange((value: boolean) => onChange(value))
    }
    .padding(14)
    .backgroundColor(Color.White)
  }

  build() {
    Column() {
      this.SectionTitle('账号')
      this.SettingRow('个人资料', '头像、昵称和简介', '去完善')
      this.SettingRow('登录设备', '查看最近登录的手机和平板', '2 台')

      this.SectionTitle('通知')
      this.SwitchRow('消息推送', '订单和系统通知会及时提醒', this.pushEnabled, (value: boolean) => {
        this.pushEnabled = value
      })
      this.SwitchRow('使用蜂窝网络同步', '非 Wi-Fi 环境也同步草稿', this.useCellular, (value: boolean) => {
        this.useCellular = value
      })
    }
    .padding(16)
    .backgroundColor('#F5F7FA')
  }
}