前言

学习 Popup 不能只停留在“弹出一段提示文字”。真正进入业务场景后，浮层往往承载的是一块小型信息卡片，比如用户详情、商品摘要、审批说明、头像资料等。只要内容不需要彻底打断主流程，Popup 就非常适合承接这种局部信息展示。

这个案例用一张用户信息卡片，演示了怎样通过 @Builder 自定义 Popup 内容，让浮层真正具备业务表达能力。

页面目标

页面中央是一张简化的用户卡片，右侧有一个“详情”按钮。点击后，会在下方弹出一块带标题、分隔线和多行字段信息的资料面板。

这种结构特别适合：

• 列表中的用户详情预览
• 商品卡片的补充信息
• 审批单据的快速查看

完整代码

import { DEMO_CARD_COLOR, DEMO_THEME_COLOR } from './types'

@Entry
@Component
struct PopupProfileCard {
  @State isShow: boolean = true
  @State showDetailPopup: boolean = false

  build() {
    Column() {
      if (this.isShow) {
        Column() {
          Text('Popup 自定义内容')
            .fontSize(16)
            .fontWeight(FontWeight.Bold)
            .margin({ bottom: 16 })

          Column() {
            Row() {
              Text('用户信息卡片')
                .fontSize(13)
                .fontColor('#999999')
            }
            .margin({ bottom: 12 })

            Row() {
              Column() {
                Text('张三')
                  .fontSize(17)
                  .fontWeight(FontWeight.Bold)
                  .fontColor('#333333')
                Text('产品经理')
                  .fontSize(13)
                  .fontColor('#999999')
                  .margin({ top: 4 })
              }

              Text('').layoutWeight(1)

              Button('详情')
                .width(70)
                .height(36)
                .backgroundColor(DEMO_THEME_COLOR)
                .borderRadius(18)
                .fontColor('#FFFFFF')
                .fontSize(13)
                .bindPopup(this.showDetailPopup, {
                  builder: this.detailPopupBuilder,
                  placement: Placement.Bottom,
                  enableArrow: true,
                  onStateChange: (e) => {
                    if (!e.isVisible) {
                      this.showDetailPopup = false
                    }
                  }
                })
                .onClick(() => {
                  this.showDetailPopup = !this.showDetailPopup
                })
            }
            .width('100%')
          }
          .width('100%')
          .padding(16)
          .backgroundColor('#F8F8F8')
          .borderRadius(10)
        }
        .width('100%')
        .padding(24)
        .backgroundColor(DEMO_CARD_COLOR)
        .borderRadius(12)
      }
    }
    .width('100%')
    .height('100%')
    .backgroundColor('#F5F6FA')
    .padding(16)
  }

  @Builder
  detailPopupBuilder() {
    Column() {
      Text('详细信息')
        .fontSize(15)
        .fontWeight(FontWeight.Bold)
        .margin({ bottom: 12 })

      Divider().margin({ bottom: 12 })

      Row() {
        Text('部门').fontSize(13).fontColor('#999999').width(60)
        Text('产品研发部').fontSize(13).fontColor('#333333')
      }
      .width('100%')
      .margin({ bottom: 8 })

      Row() {
        Text('工号').fontSize(13).fontColor('#999999').width(60)
        Text('PD2024001').fontSize(13).fontColor('#333333')
      }
      .width('100%')
      .margin({ bottom: 8 })

      Row() {
        Text('邮箱').fontSize(13).fontColor('#999999').width(60)
        Text('zhangsan@example.com').fontSize(13).fontColor(DEMO_THEME_COLOR)
      }
      .width('100%')
      .margin({ bottom: 8 })

      Row() {
        Text('入职').fontSize(13).fontColor('#999999').width(60)
        Text('2022-03-15').fontSize(13).fontColor('#333333')
      }
      .width('100%')
    }
    .width(220)
    .padding(16)
    .backgroundColor('#FFFFFF')
    .borderRadius(12)
    .shadow({ radius: 12, color: '#00000015' })
  }
}

关键代码讲解

1. Popup 完全可以承载一张小型业务卡片

案例里的 detailPopupBuilder() 已经不是单纯的一句说明，而是一块结构完整的信息面板。它包含：

• 标题
• 分隔线
• 多行字段对
• 重点字段高亮

这说明 Popup 的上限并不低，只要内容量合适，就能承担很多局部详情展示任务。

2. @Builder 让内容结构保持清晰

把详情面板单独放进 Builder，有两个好处：

• 主页面结构不会被浮层内容打乱
• 浮层可以独立迭代和复用

以后你要把这张资料卡换成商品参数卡、审批摘要卡，方法完全一样。

3. 通过字段排布提升可读性

案例里每一行都用了“字段名 + 字段值”的结构，并且给字段名固定了宽度：

Text('部门').width(60)
Text('产品研发部')

这会让整张卡片看起来更整齐，阅读路径也更稳定。对于信息型 Popup 来说，这种细节非常重要。

实战建议

推荐把这类 Popup 用在：

• 列表项的快速详情预览
• 不需要跳页的小型资料查看
• 附近即看、看完即走的补充信息场景

如果内容已经复杂到需要滚动、编辑或多步骤交互，就不要继续用 Popup 硬撑，应该改成对话框或独立页面。

总结

这个案例真正传达的是：Popup 不只是提示层，也可以是轻量信息卡片。只要内容规模控制得当，它会比跳页和弹窗都更轻巧，也更适合高频查看场景。