HarmonyOS 自定义弹窗选型与开发

HarmonyOS 自定义弹窗选型与开发 - 初学者指南

什么是弹窗？

弹窗是在应用界面上方临时显示的窗口组件，用于向用户展示信息、获取用户输入或确认用户操作。比如我们常见的：

• 提示信息（如"保存成功"）
• 确认对话框（如"确定删除吗？"）
• 菜单选项（如分享、编辑等）
• 输入表单（如登录、注册）

为什么需要了解弹窗选型？

HarmonyOS 提供了多种实现弹窗的方式，不同方式有不同的特点和适用场景。选择合适的弹窗类型能让你的应用：

• 用户体验更好
• 代码更好维护
• 功能更稳定

HarmonyOS 弹窗的主要类型

🚀 推荐使用的弹窗类型

1. UIContext 弹窗（推荐 ⭐⭐⭐⭐⭐）

这是目前最推荐的弹窗实现方式，包含三种具体实现：

a) UIContext.openBindSheet() - 底部弹窗

• 什么时候用：底部操作菜单、选项列表
• 特点：从底部弹出，占据部分屏幕
• 优势：符合用户习惯，操作便捷

b) UIContext.getPromptAction().openCustomDialog() - 自定义对话框

• 什么时候用：提示信息、确认操作、表单输入
• 特点：居中显示，高度可定制
• 优势：功能强大，样式自由

c) UIContext.getOverlayManager() - 悬浮组件

• 什么时候用：全局提示、悬浮按钮
• 特点：可在任意位置显示
• 优势：不受页面布局限制

2. Navigation.Dialog - 路由弹窗

• 什么时候用：需要保持在页面切换后不消失的弹窗
• 特点：本质上是一个透明页面
• 优势：与路由系统集成良好

❌ 不推荐使用的弹窗类型

1. CustomDialog（基础自定义弹窗）

为什么不推荐：

• 只能在组件内部使用，不够灵活
• 不支持动态创建
• 多个弹窗时代码冗余

2. @ohos.promptAction

为什么不推荐：

• 可能显示到错误的窗口
• 样式定制能力有限

弹窗的核心功能对比

为了帮助初学者选择，我简化了功能对比表：

新手建议：

• 🏁 刚开始学习：优先使用 openCustomDialog，功能最全面
• 📋 底部菜单：使用 openBindSheet
• 🔄 页面级弹窗：使用 Navigation.Dialog

实际开发案例

案例 1：图文提示弹窗（类似增强版 Toast）

使用场景：操作成功/失败提示，带图标的消息

为什么选择这种方式：
系统自带的 showToast 只能显示纯文本，我们需要图文混合的提示。

实现步骤：

// 1. 定义弹窗内容
@Builder
function buildToastContent(message: string, iconRes: Resource) {
  Column() {
    Image(iconRes)
      .width(40)
      .height(40)
      .margin({ bottom: 8 })

    Text(message)
      .fontSize(16)
      .fontColor(Color.White)
  }
  .padding(16)
  .backgroundColor(Color.Black)
  .borderRadius(8)
}

// 2. 显示弹窗
showCustomToast(message: string, iconRes: Resource) {
  // 获取UI上下文
  let uiContext = this.getUIContext()

  // 创建弹窗内容
  let contentNode = new ComponentContent(uiContext, wrapBuilder(buildToastContent), message, iconRes)

  // 配置弹窗选项
  let options: BaseDialogOptions = {
    isModal: false,           // 非模态，不阻挡页面操作
    autoCancel: true,         // 点击外部关闭
    focusable: false,         // 不抢占焦点
    alignment: DialogAlignment.Center
  }

  // 显示弹窗
  uiContext.getPromptAction().openCustomDialog(contentNode, options)

  // 3秒后自动关闭
  setTimeout(() => {
    uiContext.getPromptAction().closeCustomDialog(contentNode)
  }, 3000)
}

初学者注意事项：

• focusable: false 防止弹窗抢占焦点，避免键盘收起
• 记得设置自动关闭时间，避免弹窗一直显示

案例 2：隐私协议弹窗

使用场景：应用首次启动，需要用户同意隐私协议

特殊需求：

1. 点击协议链接跳转页面，返回后弹窗还在
2. 用户不能通过侧滑关闭弹窗，必须选择同意/拒绝

实现步骤：

// 1. 定义隐私弹窗内容
@Builder
function buildPrivacyDialog() {
  Column() {
    Text('隐私协议')
      .fontSize(18)
      .fontWeight(FontWeight.Bold)
      .margin({ bottom: 16 })

    Text('请阅读并同意以下协议：')
      .fontSize(14)
      .margin({ bottom: 8 })

    // 可点击的协议链接
    Text('《用户协议》《隐私政策》')
      .fontSize(14)
      .fontColor(Color.Blue)
      .onClick(() => {
        // 跳转到协议页面
        router.pushUrl({ url: 'pages/PrivacyPage' })
      })
      .margin({ bottom: 20 })

    // 按钮组
    Row() {
      Button('拒绝')
        .onClick(() => {
          // 处理拒绝逻辑
          this.closePrivacyDialog()
        })
        .margin({ right: 12 })

      Button('同意')
        .onClick(() => {
          // 处理同意逻辑
          this.closePrivacyDialog()
        })
    }
  }
  .padding(20)
  .backgroundColor(Color.White)
  .borderRadius(12)
}

// 2. 显示隐私弹窗
showPrivacyDialog() {
  let uiContext = this.getUIContext()

  // 获取页面节点ID（重要：实现页面切换保持）
  let frameNode = uiContext.getFrameNodeById('mainPage')
  let uniqueId = frameNode?.getUniqueId()

  let contentNode = new ComponentContent(uiContext, wrapBuilder(buildPrivacyDialog))

  let options: BaseDialogOptions = {
    isModal: true,              // 模态弹窗，阻挡页面操作
    autoCancel: false,          // 不允许点击外部关闭
    levelMode: LevelMode.PAGE,  // 页面级弹窗
    levelUniqueId: uniqueId,    // 绑定到特定页面

    // 3. 侧滑拦截实现
    onWillDismiss: (reason: DismissReason) => {
      if (reason === DismissReason.PRESS_BACK || reason === DismissReason.SLIDE) {
        // 拦截侧滑和返回键，不关闭弹窗
        return false
      }
      return true
    }
  }

  this.privacyDialogNode = contentNode
  uiContext.getPromptAction().openCustomDialog(contentNode, options)
}

初学者重点理解：

• levelMode 和 levelUniqueId：让弹窗绑定到特定页面，页面切换时弹窗保持
• onWillDismiss：拦截关闭操作，实现侧滑拦截
• 页面节点 ID 的获取：确保弹窗正确绑定

案例 3：进度展示弹窗

使用场景：文件下载、数据加载等耗时操作

关键点：弹窗显示后，页面需要能更新弹窗内的进度

实现步骤：

// 1. 进度弹窗组件
@Component
struct ProgressDialog {
  @State progress: number = 0
  @State status: string = '准备中...'

  build() {
    Column() {
      Text(this.status)
        .fontSize(16)
        .margin({ bottom: 16 })

      Progress({ value: this.progress, total: 100, type: ProgressType.Linear })
        .width(200)
        .height(6)
        .margin({ bottom: 8 })

      Text(`${this.progress}%`)
        .fontSize(14)
        .fontColor(Color.Gray)
    }
    .padding(20)
    .backgroundColor(Color.White)
    .borderRadius(8)
  }
}

// 2. 显示和更新进度
showProgressDialog() {
  let uiContext = this.getUIContext()

  // 创建可更新的内容节点
  this.progressContentNode = new ComponentContent(uiContext, wrapBuilder(buildProgressDialog))

  let options: BaseDialogOptions = {
    isModal: true,
    autoCancel: false,  // 不允许手动关闭，避免中断任务
    // 自定义渐隐渐显动画
    transition: TransitionEffect.asymmetric(
      TransitionEffect.opacity(0).animation({ duration: 300 }),
      TransitionEffect.opacity(0).animation({ duration: 300 })
    )
  }

  uiContext.getPromptAction().openCustomDialog(this.progressContentNode, options)

  // 开始任务
  this.startTask()
}

// 3. 更新进度的关键方法
updateProgress(progress: number, status: string) {
  // 重点：使用update()方法更新弹窗内容
  this.progressContentNode.update(progress, status)
}

// 4. 模拟任务执行
startTask() {
  let progress = 0
  let timer = setInterval(() => {
    progress += 10

    if (progress <= 100) {
      this.updateProgress(progress, `下载中... ${progress}%`)
    } else {
      clearInterval(timer)
      this.updateProgress(100, '下载完成')

      // 1秒后关闭弹窗
      setTimeout(() => {
        this.closeProgressDialog()
      }, 1000)
    }
  }, 500)
}

初学者重点：

• contentNode.update()：这是更新弹窗内容的关键方法
• autoCancel: false：防止用户误关闭弹窗中断任务
• 自定义动画：让弹窗显示更平滑

案例 4：底部操作弹窗

使用场景：分享菜单、更多操作等

为什么用 openBindSheet：底部弹出符合用户操作习惯

实现步骤：

// 1. 定义操作项数据
interface ActionItem {
  icon: Resource
  title: string
  action: () => void
}

// 2. 底部操作弹窗组件
@Builder
function buildActionSheet(actions: ActionItem[]) {
  Column() {
    // 顶部把手
    Divider()
      .width(40)
      .height(4)
      .backgroundColor(Color.Gray)
      .borderRadius(2)
      .margin({ top: 8, bottom: 16 })

    // 操作列表
    ForEach(actions, (item: ActionItem) => {
      Row() {
        Image(item.icon)
          .width(24)
          .height(24)
          .margin({ right: 12 })

        Text(item.title)
          .fontSize(16)
          .layoutWeight(1)
      }
      .width('100%')
      .height(56)
      .padding({ left: 16, right: 16 })
      .onClick(() => {
        item.action()
        this.closeActionSheet()  // 执行操作后关闭弹窗
      })
    })

    // 取消按钮
    Button('取消')
      .width('90%')
      .height(44)
      .margin({ top: 16, bottom: 16 })
      .onClick(() => {
        this.closeActionSheet()
      })
  }
  .width('100%')
  .backgroundColor(Color.White)
  .borderRadius({ topLeft: 16, topRight: 16 })
}

// 3. 显示底部弹窗
showActionSheet() {
  // 定义操作项
  let actions: ActionItem[] = [
    {
      icon: $r('app.media.share'),
      title: '分享',
      action: () => { console.log('分享操作') }
    },
    {
      icon: $r('app.media.edit'),
      title: '编辑',
      action: () => { console.log('编辑操作') }
    },
    {
      icon: $r('app.media.delete'),
      title: '删除',
      action: () => { console.log('删除操作') }
    }
  ]

  let uiContext = this.getUIContext()
  let contentNode = new ComponentContent(uiContext, wrapBuilder(buildActionSheet), actions)

  // 配置底部弹窗选项
  let options: SheetOptions = {
    height: SheetSize.MEDIUM,  // 固定高度
    dragBar: false,            // 不显示拖拽条（我们自定义了）
    backgroundColor: Color.Transparent,
    onAppear: () => {
      console.log('弹窗出现')
    },
    onDisappear: () => {
      console.log('弹窗消失')
    }
  }

  this.actionSheetNode = contentNode
  uiContext.openBindSheet(contentNode, options)
}

// 4. 可变高度版本（高级用法）
showFlexibleActionSheet() {
  let options: SheetOptions = {
    // 使用detents实现可变高度
    detents: [SheetSize.MEDIUM, SheetSize.LARGE],
    backgroundColor: Color.Transparent,
    showClose: true  // 显示关闭按钮
  }

  // 其他代码相同...
}

初学者提示：

• SheetSize.MEDIUM：固定高度，无法拖拽
• detents：设置多个高度档位，支持拖拽切换
• 记得在操作执行后关闭弹窗

新手最佳实践建议

🎯 选择弹窗类型的简单决策树

开始
├─ 需要底部弹出的菜单？
│  └─ 是 → 使用 openBindSheet
└─ 否
   ├─ 需要页面切换后保持？
   │  └─ 是 → 使用 Navigation.Dialog
   └─ 否 → 使用 openCustomDialog

📝 代码组织建议

1. 创建弹窗工具类：

export class DialogUtils {
  static showToast(message: string) {
    // 图文提示弹窗的封装
  }

  static showConfirm(title: string, content: string, onConfirm: () => void) {
    // 确认弹窗的封装
  }

  static showActionSheet(actions: ActionItem[]) {
    // 操作弹窗的封装
  }
}

2. 统一弹窗样式：

export const CommonDialogStyles = {
  background: Color.White,
  borderRadius: 12,
  padding: 20,
  shadow: { radius: 10, color: Color.Gray, offsetX: 0, offsetY: 4 },
};

⚠️ 常见错误避免

1. 忘记保存弹窗节点引用：

// ❌ 错误：无法关闭弹窗
showDialog() {
  let contentNode = new ComponentContent(...)
  uiContext.openCustomDialog(contentNode, options)
  // contentNode变量丢失，无法关闭
}

// ✅ 正确：保存引用
private dialogNode: ComponentContent | null = null

showDialog() {
  this.dialogNode = new ComponentContent(...)
  uiContext.openCustomDialog(this.dialogNode, options)
}

closeDialog() {
  if (this.dialogNode) {
    uiContext.closeCustomDialog(this.dialogNode)
    this.dialogNode = null
  }
}

2. 弹窗抢占焦点导致键盘收起：

// ✅ 添加 focusable: false
let options: BaseDialogOptions = {
  focusable: false, // 防止抢占焦点
  // ...其他配置
};

3. 页面切换时弹窗消失：

// ✅ 使用页面级弹窗
let options: BaseDialogOptions = {
  levelMode: LevelMode.PAGE,
  levelUniqueId: frameNode?.getUniqueId(),
  // ...其他配置
};

🚀 性能优化建议

1. 复用弹窗节点：避免频繁创建销毁
2. 延迟加载：复杂弹窗内容可以延迟构建
3. 及时释放：弹窗关闭后清理引用，避免内存泄漏

总结

弹窗是 HarmonyOS 应用开发中的重要组件，选择合适的实现方式能大大提升开发效率和用户体验。

初学者记住这几点：

1. 优先使用 UIContext 系列 API
2. 根据使用场景选择合适的弹窗类型
3. 注意弹窗节点的生命周期管理
4. 多实践，从简单案例开始

希望这份指南能帮助你更好地掌握 HarmonyOS 弹窗开发！

💡 小贴士：建议初学者先掌握 openCustomDialog 的基本用法，然后再逐步学习其他类型的弹窗实现。