logo
积分中心
鸿蒙UI开发——实现一个上拉抽屉效果
头像 蓝亭书序 2026-11-18 14:17:07    发布
0 浏览 0 收藏


1、概 述

在项目开发中,我们可能会遇到临时交互的场景(即:弹出一个临时交互框,交互完毕后继续用户的主流程),效果如下:

图片

在ArkUI中,此类弹出窗被称为“半模态页面”,ArkUI为我们提供了一套可以快速实现此效果的接口,本文针对此效果的实现做讨论。

2、接口定义

给组件绑定半模态页面,点击后显示模态页面。接口定义如下:


bindSheet(isShow: Optional<boolean>, builder: CustomBuilder, options?: SheetOptions)


用法类似如下(第5行代码):


build() {
  Column() {
    Button("点击我弹出上拉抽屉")
      // ... 其他属性
      .bindSheet($this.isShow, this.myBuilder(), {
        // 三挡高度(默认是中间)
        detents: [SheetSize.MEDIUM, SheetSize.LARGE, 200],
        blurStyle: BlurStyle.Thick,
        showClose: true,
        title: { title: "抽屉标题", subtitle: "抽屉副标题" },
      })
  }
  .justifyContent(FlexAlign.Start)
  .width('100%')
  .height('100%')
}


其中:

  • isShow是可以支持双向绑定的显示/隐藏的切换控制;
  • builder是抽屉需要显示的内容,内容构造器;
  • options是配置参数,定义如下:


名称类型说明
backgroundColorResourceColor半模态页面的背板颜色。默认值:Color.White。
onWillAppear() => void半模态页面显示(动画开始前)回调函数。
onAppear() => void半模态页面显示(动画结束后)回调函数。
onWillDisappear() => void半模态页面回退(动画开始前)回调函数。说明:不允许在onWillDisappear函数中修改状态变量,可能会导致组件行为不稳定。
onDisappear() => void半模态页面回退(动画结束后)回调函数。
heightSheetSize | Length半模态高度,默认是LARGE。说明:API version 12之前,底部弹窗横屏时该属性设置无效,高度为距离屏幕顶部8vp。API version 12开始,底部弹窗横屏时该属性设置生效,最大高度为距离屏幕顶部8vp。底部弹窗时,当设置detents时,该属性设置无效。底部弹窗竖屏时,最大高度为距离信号栏8vp。居中弹窗和跟手弹窗设置类型为SheetSize.LARGE和SheetSize.MEDIUM无效,显示默认高度560vp。居中弹窗和跟手弹窗最小高度为320vp,最大高度为窗口短边的90%。当使用Length设置的高度和使用SheetSize.FIT_CONTENT自适应的高度大于最大高度,则显示最大高度,小于最小高度,则显示最小高度。
detents[(SheetSize | Length), ( SheetSize | Length)?, (SheetSize | Length)?]半模态页面的切换高度档位。说明:从API version 12开始,底部弹窗横屏时该属性设置生效。底部弹窗竖屏生效,元组中第一个高度为初始高度。面板可跟手滑动切换档位,松手后是否滑动至目标档位有两个判断条件:速度和距离。速度超过阈值,则执行滑动至与手速方向一致的目标档位;速度小于阈值,则引入距离判断条件,当位移距离>当前位置与目标位置的1/2,滑动至与手速方向一致的目标档位,位移距离当前位置与目标位置的1/2,返回至当前档位。速度阈值:1000,距离阈值:50%。
preferTypeSheetType半模态页面的样式。说明:半模态在不同窗口所支持的显示类型:1. 宽度 < 600vp:底部。2. 600vp <= 宽度 < 840vp:底部、居中。默认居中样式。3. 宽度 >= 840vp:底部、居中、跟手。默认跟手样式。
showCloseboolean | Resource是否显示关闭图标,默认显示。说明:Resource需要为boolean类型。
dragBarboolean是否显示控制条。说明:半模态面板的detents属性设置多个不同高度并且设置生效时,默认显示控制条。否则不显示控制条。
blurStyleBlurStyle半模态面板的模糊背景。默认无模糊背景。
maskColorResourceColor半模态页面的背景蒙层颜色。
titleSheetTitleOptions | CustomBuilder半模态面板的标题。
enableOutsideInteractiveboolean半模态所在页面是否允许交互。说明:设置为true时允许交互,不显示蒙层;设置为false时不允许交互,显示蒙层;若不进行设置,默认底部弹窗与居中弹窗不允许交互,跟手弹窗允许交互。当设置为true时,maskColor设置无效。
shouldDismiss(sheetDismiss: SheetDismiss) => void半模态页面交互式关闭回调函数。说明:当用户执行下拉关闭/back事件/点击蒙层关闭/关闭按钮关闭交互操作时,如果注册该回调函数,则不会立刻关闭。
onWillDismissDismissSheetAction半模态页面交互式关闭回调函数。说明:当用户执行关闭操作时,如果注册该回调函数,不会立刻关闭, 由开发者控制是否关闭。在回调函数中可以通过reason得到关闭页面的操作类型,从而根据原因选择是否关闭半模态页面。在onWillDismiss回调中,不能再做onWillDismiss拦截。元服务API: 从API version 12开始,该接口支持在元服务中使用。
onWillSpringBackWhenDismissSpringBackAction半模态页面交互式关闭前控制回弹函数。说明:当用户执行下拉关闭操作并注册shouldDimiss或onWillDismiss时,如果注册该回调函数,则不会回弹,由开发者控制下滑关闭时是否回弹。在回调函数中可以通过调用springBack来实现回弹效果。
onHeightDidChangeCallback<number>半模态页面高度变化回调函数。说明:底部弹窗时,只有档位变化和拖拽跟手才返回每一帧高度,拉起半模态和避让软键盘只返回最后的高度,其他弹窗只在半模态拉起返回最后高度。返回值为px。
onDetentsDidChangeCallback<number>半模态页面档位变化回调函数。说明:底部弹窗时,档位变化返回最后的高度。返回值为px。
onWidthDidChangeCallback<number>半模态页面宽度变化回调函数。说明:宽度变化时返回最后的宽度。返回值为px。
onTypeDidChangeCallback<SheetType>半模态页面形态变化回调函数。说明:形态变化时返回最后的形态。
borderWidthDimension | EdgeWidths | LocalizedEdgeWidths设置半模态页面的边框宽度。可分别设置4个边框宽度。默认值:0。百分比参数方式:以父元素半模态页面宽的百分比来设置半模态页面的边框宽度。当半模态页面左边框和右边框大于半模态页面宽度,半模态页面上边框和下边框大于半模态页面高度,显示可能不符合预期。说明:底部弹窗时,底部边框宽度设置无效。
borderColorResourceColor | EdgeColors | LocalizedEdgeColors设置半模态页面的边框颜色。默认值:Color.Black。如果使用borderColor属性,需要和borderWidth属性一起使用。说明:底部弹窗时,底部边框颜色设置无效。
borderStyleBorderStyle | EdgeStyles设置半模态页面的边框样式。默认值:BorderStyle.Solid。如果使用borderStyle属性,需要和borderWidth属性一起使用。说明:底部弹窗时,底部边框样式设置无效。
widthDimension设置半模态页面的宽度。百分比参数方式:以父元素宽的百分比来设置半模态页面的宽度。
shadowShadowOptions | ShadowStyle设置半模态页面的阴影。
uiContextUIContext在UIContext实例对应的窗口中显示半模态。说明:使用openBindSheet启动的半模态页面,不支持设置、更新该属性。元服务API: 从API version 12开始,该接口支持在元服务中使用。
modeSheetMode设置半模态页面的显示层级。默认值:SheetMode.OVERLAY。说明:1. 半模态显示期间mode属性不支持动态切换,两种模式的显示层级完全不同,无法做到显示期间同一个半模态从一个层级变换到另一个层级。建议在使用时明确诉求固定mode值。2. 设置SheetMode.EMBEDDED时不支持设置UIContext属性,两者对应的半模态显示层级效果互相冲突。3. 使用openBindSheet启动半模态页面,若未传入有效的targetId,则不支持设置为SheetMode.EMBEDDED,默认为SheetMode.OVERLAY。元服务API: 从API version 12开始,该接口支持在元服务中使用。
scrollSizeModeScrollSizeMode设置半模态面板滑动时,内容区域刷新时机。默认值:ScrollSizeMode.FOLLOW_DETENT 。

3、案 例

实现一个案例效果如下:

图片

代码如下(24~30行的配置,5~15行的builder):


@Entry
@Component
struct SheetTransitionExample {
  @State isShow: boolean = false
  @Builder
  myBuilder() {
    Column() {
      Text('欢迎加入【Harmony自习室】')
        .fontSize(20)
      Button("确认")
        .margin(10)
        .fontSize(20)
    }
    .width('100%')
  }
  build() {
    Column() {
      Button("点击我弹出上拉抽屉")
        .onClick(() => {
          this.isShow = true
        })
        .fontSize(20)
        .margin(10)
        .bindSheet($this.isShow, this.myBuilder(), {
          // 三挡高度(默认是中间)
          detents: [SheetSize.MEDIUM, SheetSize.LARGE, 200],
          blurStyle: BlurStyle.Thick,
          showClose: true,
          title: { title: "抽屉标题", subtitle: "抽屉副标题" },
        })
    }
    .justifyContent(FlexAlign.Start)
    .width('100%')
    .height('100%')
  }
}




©本站发布的所有内容,包括但不限于文字、图片、音频、视频、图表、标志、标识、广告、商标、商号、域名、软件、程序等,除特别标明外,均来源于网络或用户投稿,版权归原作者或原出处所有。我们致力于保护原作者版权,若涉及版权问题,请及时联系我们进行处理。
分类
HarmonyOS

暂无评论数据

加载中...

发布

地址:北京市朝阳区北三环东路三元桥曙光西里甲1号第三置业A座1508室 电话:13391790444或(010)62178877
版权所有:电脑商情信息服务集团 北京赢邦策略咨询有限责任公司
声明:本媒体部分图片、文章来源于网络,版权归原作者所有,我司致力于保护作者版权,如有侵权,请与我司联系删除

京ICP备:2022009079号-2

京公网安备:11010502051901号

ICP证:京B2-20230255