HarmonyOS Next 弹窗系列教程（5）

本章我们将深入探讨 HarmonyOS Next 中两种覆盖范围更广的弹出层组件：模态页面和浮层。这两种组件适用于需要展示更多内容或提供更复杂交互的场景。

模态页面概述

模态页面是一种占据更大屏幕空间的交互式弹窗，ArkUI 框架提供了半模态和全模态两种类型的模态页面组件：

• 半模态页面：支持多种形态展示，可根据设备宽度自适应显示不同样式。用户可通过侧滑、点击蒙层、点击关闭按钮或下拉手势关闭半模态页面。
• 全模态页面：提供全屏覆盖的弹窗效果，默认需要通过侧滑手势才能关闭，完全覆盖底层界面。

半模态页面（bindSheet）

半模态页面的实现主要包含以下步骤：

1. 使用bindSheet方法绑定半模态页面
2. 通过布尔类型变量控制半模态页面的显示状态
3. 传入自定义构建函数定义半模态页面的内容

@Entry
@Component
struct SheetDemo {
  @State isShowSheet: boolean = false

  @Builder
  SheetBuilder() {
    Column() {
      Button("我来自半模态")
    }.width('100%').height('100%')
  }

  build() {
    Column() {
      Button('Open Sheet').width('90%').height('80vp')
        .onClick(() => {
          this.isShowSheet = !this.isShowSheet
        })
        .bindSheet($$this.isShowSheet, this.SheetBuilder(), {
          title: { title: '半模态' },
        })
    }.width('100%').height('100%')
    .justifyContent(FlexAlign.Center)
  }
}

配置参数说明

参数名	类型	必填	说明
isShow	Optional	是	控制半模态页面的显示状态。从 API version 10 开始，支持$$双向数据绑定。
builder	CustomBuilder	是	定义半模态页面的内容构建器。
options	SheetOptions	否	配置半模态页面的可选属性。

全模态页面（bindContentCover）

全模态页面（bindContentCover）是一种覆盖整个屏幕的模态交互页面，完全遮盖底层视图。适用于大图查看、全屏文档阅读等场景。

实现全模态页面的步骤与半模态页面类似：

1. 使用bindContentCover方法绑定全模态页面
2. 通过布尔类型变量控制全模态页面的显示状态
3. 传入自定义构建函数定义全模态页面的内容

@Entry
@Component
struct SheetDemo {
  @State isShowContentCover: boolean = false

  @Builder
  ContentCoverBuilder() {
    Column() {
      Button("我来自全模态")
        .onClick(() => {
          this.isShowContentCover = !this.isShowContentCover
        })
    }.width('100%').height('100%')
    .justifyContent(FlexAlign.Center)
    .backgroundColor("#0099ff")
  }

  build() {
    Column() {
      Button('Open Sheet').width('90%').height('80vp')
        .onClick(() => {
          this.isShowContentCover = !this.isShowContentCover
        })
        .bindContentCover($$this.isShowContentCover, this.ContentCoverBuilder())
    }.width('100%').height('100%')
    .justifyContent(FlexAlign.Center)
  }
}

配置参数说明

参数名	类型	必填	说明
isShow	Optional	是	控制全模态页面的显示状态。从 API version 10 开始，支持$$双向数据绑定。
builder	CustomBuilder	是	定义全模态页面的内容构建器。
options	ContentCoverOptions	否	配置全模态页面的可选属性。

浮层（OverlayManager）

**浮层（OverlayManager）**是一种特殊的 UI 层级管理组件，用于将自定义 UI 内容展示在页面（Page）之上，但位于 Dialog、Popup、Menu、BindSheet、BindContentCover 和 Toast 等组件之下的层级。浮层的显示范围限定在当前窗口的安全区域内，特别适用于需要常驻显示的悬浮元素场景。

基本实现方法

浮层的实现需要按照以下步骤进行：

1. 创建浮层要显示的内容

   // 1. 创建浮层内容构建器
   @Builder
   function builderText(params: Params) {
     Column() {
       Text(params.text)
         .fontSize(30)
         .fontWeight(FontWeight.Bold)
     }.offset(params.offset)
     .width("100%")
     .height("100%")
     .backgroundColor("#CF7553")
   }
   

2. 获取 UI 上下文环境

   // 2. 获取UI上下文
   private uiContext: UIContext = this.getUIContext()
   

3. 获取 OverlayManager 管理器实例

   // 3. 获取浮层管理器
   private overlayNode: OverlayManager = this.uiContext.getOverlayManager()
   

4. 创建位置偏移对象

   // 4. 定义浮层位置偏移
   componentOffset: Position = { x: 0, y: 120 };
   

5. 创建 ComponentContent 节点对象

   // 5. 创建浮层内容节点
   componentContent = new ComponentContent(
     this.uiContext,
     wrapBuilder < [Params] > builderText,
     new Params(this.message, this.componentOffset)
   );
   

6. 操作浮层的显示与隐藏

   • 添加浮层内容

     Button("添加浮层").onClick(() => {
       // 添加浮层内容
       this.overlayNode.addComponentContent(this.componentContent);
     });
     

   • 隐藏浮层

     Button("隐藏浮层").onClick(() => {
       // 隐藏浮层内容
       this.overlayNode.hideComponentContent(this.componentContent);
     });
     

   • 显示浮层

     Button("显示浮层").onClick(() => {
       // 显示浮层内容
       this.overlayNode.showComponentContent(this.componentContent);
     });
     

效果展示

更多用法

如需了解浮层的更多高级用法，请参考官方文档。

总结与应用场景选择

至此，我们已经完成了 HarmonyOS Next 弹窗系列的全部介绍。在实际应用开发中，开发者应根据具体场景选择最合适的弹窗类型，以提供最佳的用户体验。

下表汇总了各类弹窗的主要应用场景：

弹窗类型	适用场景
弹出框（Dialog）	适用于展示用户需要关注的重要信息或操作，如确认退出应用等关键决策场景。
菜单控制（Menu）	适用于为特定组件提供多个可选操作，如长按图标显示操作菜单等场景。
气泡提示（Popup）	适用于为特定组件提供辅助信息，如点击问号图标显示帮助提示等场景。
模态页面（bindContentCover/bindSheet）	适用于在当前界面上覆盖显示新内容，如缩略图查看大图、展示详细信息等场景。
即时反馈（Toast）	适用于提供操作结果的简短反馈，如文件保存成功提示等非干扰性通知场景。
浮层（OverlayManager）	适用于需要完全自定义 UI 和交互的悬浮元素，如音乐播放控制器、屏幕录制指示器等常驻功能。