ArkUI @LocalBuilder:组件关系别被 bind 搞乱

举报
蓝瘦的蜕变 发表于 2026/11/18 19:15:01 2026/11/18
【摘要】 今天我们写一个很小的 @LocalBuilder 页面,先把它和普通 @Builder 的边界分清楚。 @LocalBuilder 不是为了替代所有构建函数。它更像是组件内部的一块局部模板:只服务当前组件,重点是维持声明组件和渲染组件之间的关系。 参考文档:组件扩展 先说结论 适合用 @LocalBuilder 的场景

ArkUI @LocalBuilder:组件关系别被 bind 搞乱

今天我们写一个很小的 @LocalBuilder 页面,先把它和普通 @Builder 的边界分清楚。

@LocalBuilder 不是为了替代所有构建函数。它更像是组件内部的一块局部模板:只服务当前组件,重点是维持声明组件和渲染组件之间的关系。

参考文档:组件扩展

先说结论

适合用 @LocalBuilder 的场景:

  • 某个 UI 片段只属于当前组件。
  • 我们不想把它抽成完整自定义组件。
  • 这段 UI 又比普通几行代码更值得单独命名。

不适合的场景:

  • 需要全局复用的模板。
  • 需要被配置数组保存的模板。
  • 需要跨页面传来传去的业务组件。

这篇我们只做局部片段,不讲复杂状态刷新。

先准备一个面板外壳

@Builder
function EmptyLocalSlot() {
  Blank()
    .height(1)
}

@Component
struct LocalPreviewPanel {
  title: string = '';
  note: string = '';
  @BuilderParam content: () => void = EmptyLocalSlot;
}

这个面板只负责标题、说明和外壳。里面真正展示什么,交给 @BuilderParam content。

这样做是为了让 @LocalBuilder 的内容能放进一个统一容器里,但又不把两件事混在一起。

写局部构建函数

@LocalBuilder
OwnerBadge() {
  Row({ space: 12 }) {
    Text('L')
    Column() {
      Text(this.ownerName)
      Text(this.ownerDesc)
    }
  }
}

它写在页面组件内部,所以可以直接读当前组件里的普通成员变量。

这里我们没有用 @State。不是不能用,而是这篇先把结构关系讲清楚,不把话题带回状态管理。

页面效果

这个 Demo 里有两个面板:

  • 第一个面板展示一个局部名片。
  • 第二个面板展示一段规则说明。

它们的内容都来自当前页面里的 @LocalBuilder。你可以把它理解成“这个页面自己的局部小模板”。

如果你平时写页面时有一小段 UI 只在当前页面出现,但重复了两三次,这种地方就可以先考虑 @LocalBuilder。

完整示例代码

文件位置:entry/src/main/ets/pages/arkUI/custom/ArkUILocalBuilderDemo.ets

@Builder
function EmptyLocalSlot() {
  Blank()
    .height(1)
}

@Component
struct LocalPreviewPanel {
  title: string = '';
  note: string = '';
  @BuilderParam content: () => void = EmptyLocalSlot;

  build() {
    Column({ space: 12 }) {
      Text(this.title)
        .fontSize(18)
        .fontWeight(700)
        .fontColor('#111827')
      Text(this.note)
        .fontSize(13)
        .fontColor('#6B7280')
        .lineHeight(20)
      this.content()
    }
    .width('100%')
    .padding(16)
    .borderRadius(18)
    .backgroundColor('#FFFFFF')
    .border({ width: 1, color: '#E5E7EB' })
    .alignItems(HorizontalAlign.Start)
  }
}

@Entry
@Component
struct ArkUILocalBuilderDemo {
  private ownerName: string = '父组件里的名片';
  private ownerDesc: string = '这段内容由 @LocalBuilder 声明在当前组件里,调用时也保持这层关系。';

  @LocalBuilder
  OwnerBadge() {
    Row({ space: 12 }) {
      Text('L')
        .width(46)
        .height(46)
        .borderRadius(23)
        .backgroundColor('#DBEAFE')
        .fontSize(20)
        .fontWeight(700)
        .fontColor('#2563EB')
        .textAlign(TextAlign.Center)
      Column({ space: 5 }) {
        Text(this.ownerName)
          .fontSize(17)
          .fontWeight(700)
          .fontColor('#111827')
        Text(this.ownerDesc)
          .fontSize(13)
          .fontColor('#4B5563')
          .lineHeight(19)
      }
      .layoutWeight(1)
      .alignItems(HorizontalAlign.Start)
    }
    .width('100%')
    .padding(14)
    .borderRadius(16)
    .backgroundColor('#EFF6FF')
  }

  @LocalBuilder
  RuleCard() {
    Column({ space: 8 }) {
      Text('@LocalBuilder 只能写在组件内部')
        .fontSize(16)
        .fontWeight(700)
        .fontColor('#0F766E')
      Text('它适合整理“只属于这个组件”的小片段。需要全局复用时,还是用全局 @Builder 或自定义组件更清楚。')
        .fontSize(14)
        .fontColor('#4B5563')
        .lineHeight(21)
    }
    .width('100%')
    .padding(14)
    .borderRadius(16)
    .backgroundColor('#F0FDFA')
  }

  build() {
    Scroll() {
      Column({ space: 20 }) {
        Column({ space: 8 }) {
          Text('ArkUI @LocalBuilder')
            .fontSize(28)
            .fontWeight(700)
            .fontColor('#111827')
          Text('组件关系别被 bind 搞乱')
            .fontSize(16)
            .fontColor('#4B5563')
          Text('@LocalBuilder 不是拿来替代所有 @Builder 的。它更适合当前组件内部的小片段,重点是维持声明组件和渲染组件之间的关系。')
            .fontSize(14)
            .fontColor('#6B7280')
            .lineHeight(22)
        }
        .width('100%')
        .alignItems(HorizontalAlign.Start)

        LocalPreviewPanel({
          title: '把局部片段塞进面板',
          note: '外壳由子组件提供,内容由当前组件的 @LocalBuilder 生成。'
        }) {
          this.OwnerBadge()
        }

        LocalPreviewPanel({
          title: '适合写什么',
          note: '只属于当前组件的小标题、小徽章、小说明,都可以先放在 @LocalBuilder 里。'
        }) {
          this.RuleCard()
        }

        Text('这一页故意不演示复杂状态刷新。我们先记住一个边界:@LocalBuilder 是局部构建函数,别把它写成跨页面、跨业务的模板系统。')
          .width('100%')
          .padding(16)
          .borderRadius(16)
          .backgroundColor('#F8FAFC')
          .fontSize(14)
          .fontColor('#4B5563')
          .lineHeight(22)
      }
      .width('100%')
      .padding(24)
      .alignItems(HorizontalAlign.Start)
    }
    .width('100%')
    .height('100%')
    .backgroundColor('#F8FAFC')
  }
}
【版权声明】本文为华为云社区用户原创内容,未经允许不得转载,如需转载请自行联系原作者进行授权。如果您发现本社区中有涉嫌抄袭的内容,欢迎发送邮件进行举报,并提供相关证据,一经查实,本社区将立刻删除涉嫌侵权内容,举报邮箱: cloudbbs@huaweicloud.com
  • 点赞
  • 收藏
  • 关注作者

评论(0)

0/1000
抱歉,系统识别当前为高风险访问,暂不支持该操作

全部回复

上滑加载中

设置昵称

在此一键设置昵称,即可参与社区互动!

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。