核心内容摘要
520886·MOOC动漫：让热爱发声，点亮创意无限可能
弹窗概述弹窗一般指打开应用时自动弹出或者用户行为操作时弹出的UI界面用于短时间内展示用户需关注的信息或待处理的操作。
从ArkUI组件树层级上来看Overlay浮层、弹窗、模态、带Order的Overlay浮层都挂载在Root节点下。
弹窗、模态、带Order的Overlay浮层根据设置的层级数字大小进行逐层显示并且全部显示在Overlay浮层上面。
如图所示对于一个多页面应用基本树结构如下所示。
多个Page页面之间使用Router的接口进行跳转。
NavBar和Navdestination组成的页面可以通过Navigation接口进行跳转。
而Dialog、Popup、Menu、OverlayManager、Toast、bindSheet以及bindContentCover的组件在结合路由、导航使用时存在如下几种显示模式。
弹窗显示在当前应用窗口最上层层级高于应用主窗内所有页面默认行为。
如下图所示触发弹窗显示时弹窗层级要高于Page页面和Navigation页面即如果弹窗组件没有被关闭的话页面切换前后弹窗组件都会显示在页面上方而不会出现新的路由/导航页面覆盖在弹窗之上的情况。
说明如果Popup或Menu等存在绑定组件的弹窗组件在页面跳转后因为所绑定的组件不在新页面显示系统内部会自动关闭对应弹窗组件。
但因为弹窗组件显示同时受开发者配置的参数控制例如当Popup的show参数设置为显示时弹窗组件会覆盖在下一个页面上显示。
弹窗显示在当前页面内层级低于下一跳页面。
当开发者期望弹窗是一个页面内的弹窗即当路由/导航切换页面时弹窗会被跳转的页面覆盖随着页面切回原页面弹窗仍然正常显示。
此时弹窗层级如下图所示页面级弹窗功能需要结合弹窗组件的页面级能力使用当前支持页面级能力的有Dialog和bindSheet。
弹窗显示在独立窗口内窗口层级高于应用所在窗口。
在PC/2in1等设备上开发者常期望弹窗的显示在应用窗口之外此时需要借助子窗的能力。
例如自定义弹窗可以通过CustomDialogControllerOptions中的showInSubwindow属性控制是否使用子窗功能。
基于子窗显示的弹窗效果如下图所示。
此时弹窗组件的显示层级受窗口的层级管理控制会高于当前应用所在的窗口低于系统窗口如系统输入法、系统弹窗等。
弹窗的种类根据用户交互操作场景弹窗可分为模态弹窗和非模态弹窗两种类型其区别在于用户是否必须对其做出响应。
模态弹窗为强交互形式会中断用户当前的操作流程要求用户必须做出响应才能继续其他操作通常用于需要向用户传达重要信息的场景。
非模态弹窗为弱交互形式不会影响用户当前操作行为用户可以不对其进行回应通常都有时间限制出现一段时间后会自动消失。
一般用于告诉用户信息内容外还需要用户进行功能操作的场景。
说明当前模态弹窗通过设置指定属性变成非模态例如AlertDialog可以设置AlertDialogParam中的isModal属性值为false变成非模态其他弹窗详见API说明。
不建议在非前台状态下调用弹窗显示接口。
系统弹窗由系统弹出出于安全考虑不支持自定义样式。
系统弹窗出现时调用非系统弹窗的显示接口例如promptAction的openCustomDialog、CustomDialogController的open等禁止该类弹窗显示。
使用场景开发者可根据实际应用场景选择合适的弹窗进行页面开发。
弹窗名称应用场景弹出框Dialog当需要展示用户当前需要或必须关注的信息内容或操作时例如二次退出应用等应优先考虑使用此弹出框。
菜单Menu/openMenu当需要给用户提供可执行的操作时例如长按图标展示操作选项等应优先考虑使用此弹窗。
气泡提示Popup/openPopup当需要给用户提供提示时例如点击一个问号图标弹出一段帮助提示等应优先考虑使用此弹窗。
绑定模态页面bindContentCover/bindSheet当需要新的界面覆盖在旧的界面上且旧的界面不消失的一种转场方式时例如缩略图片点击后查看大图等应优先考虑使用此弹窗。
即时反馈Toast当需要在一个小的窗口中提供用户当前操作的简单反馈时例如提示文件保存成功等应优先考虑使用此弹窗。
设置浮层OverlayManager当需要完全自定义内容、行为、样式时可以使用浮层将UI展示在页面之上例如音乐/语音播放悬浮球/胶囊等应优先考虑使用此弹窗。
规格约束多个弹窗组件先后弹出时后弹出的组件的层级高于先弹出的层级退出时按照层级从高到低的顺序逐次退出。
在移动设备中子窗模式的弹窗当前无法超出主窗口。
而在2in1设备上使用模态类弹窗时会出现需要超出主窗口显示的场景开发者可以通过设置showInSubWindow为true实现超出主窗口的显示效果。
如下图所示固定样式弹框固定样式弹出框采用固定的布局格式这使得开发者无需关心具体的显示布局细节只需输入所需显示的文本内容从而简化了使用流程提升了便捷性。
接口概览使用约束可以通过调用UIContext或getUIContext在非UI页面或某些异步回调中使用本文中的接口。
CalendarPickerDialog当前不支持此操作。
操作菜单 (showActionMenu)、对话框 (showDialog)需先使用UIContext中的getPromptAction()方法获取到PromptAction对象再通过该对象调用对应方法。
列表选择弹出框 (ActionSheet)、警告弹出框 (AlertDialog)、选择器弹出框 (PickerDialog)中除CalendarPickerDialog都需先使用ohos.window中的getUIContext()方法获取UIContext实例再通过此实例调用对应方法。
或者可以通过自定义组件内置方法getUIContext()获取。
操作菜单 (showActionMenu)、对话框 (showDialog)、列表选择弹出框 (ActionSheet)、警告弹出框 (AlertDialog)可以设置isModal为false变成非模态弹窗。
操作菜单 (showActionMenu)、对话框 (showDialog)、列表选择弹出框 (ActionSheet)和警告弹出框 (AlertDialog)不支持设置内容区的字体样式如字体颜色、大小换行等操作如需自定义样式建议使用不依赖UI组件的全局自定义弹出框或者基础自定义弹出框。
注意不是所有固定弹框都不能设置样式只能设置部分内容样式每个固定弹框允许设置的内容样式内容不一样需要具体参考各固定弹窗的指南。
生命周期弹出框提供了生命周期函数用于通知用户该弹出框的生命周期。
生命周期的触发时序依次为onWillAppear - onDidAppear - onWillDisappear - onDidDisappear也可参照各组件API。
从API version 19开始对话框showDialog、列表选择弹出框ActionSheet、警告弹出框AlertDialog支持以下生命周期。
名称类型说明onWillAppearCallbackvoid弹出框显示动效前的事件回调。
onDidAppearCallbackvoid弹出框弹出后的事件回调。
onWillDisappearCallbackvoid弹出框退出动效前的事件回调。
onDidDisappearCallbackvoid弹出框消失后的事件回调。
即时反馈(Toast)使用步骤页面中通过import导入PromptActionimport { PromptAction } from kit.ArkUI;通过使用UIContext中的getPromptAction获取当前UI上下文关联的PromptAction对象private promptAction: PromptAction this.uicontext.getPromptAction();再通过该对象调用showToast创建并显示文本提示框this.promptAction.showToast({message:‘保存成功,//弹窗显示内容duration: 2000//弹窗显示时间})显示模式操作菜单 (showActionMenu)操作菜单通过UIContext中的getPromptAction方法获取到PromptAction对象再通过该对象调用showActionMenu接口实现支持在回调或开发者自定义类中使用。
操作菜单中title字段的字体最大放大倍数为2。
创建并显示操作菜单后菜单的响应结果会异步返回选中按钮在buttons数组中的索引。
例子参考固定样式弹框对话框 (showDialog)对话框通过UIContext中的getPromptAction方法获取到PromptAction对象再通过该对象调用showDialog接口实现支持在回调或开发者自定义类中使用。
对话框中title字段的字体最大放大倍数为2。
创建并显示对话框对话框响应后异步返回选中按钮在buttons数组中的索引。
例子参考固定样式弹框选择器弹窗 (PickerDialog)选择器弹窗通常用于在用户进行某些操作如点击按钮时显示特定的信息或选项。
日历选择器弹窗 (CalendarPickerDialog)日历选择器弹窗提供日历视图包含年、月和星期信息通过CalendarPickerDialog接口实现。
开发者可调用show函数定义并弹出日历选择器弹窗。
日历选择器弹窗的弹出依赖UI的执行上下文不可在UI上下文不明确的地方使用具体约束参见UIContext说明。
通过配置CalendarDialogOptions中的acceptButtonStyle、cancelButtonStyle属性可以实现自定义按钮样式。
例子参考固定样式弹框日期滑动选择器弹窗 (DatePickerDialog)开发者可以利用指定的日期范围创建日期滑动选择器弹窗将日期信息清晰地展示在弹出的窗口上。
日期滑动选择器弹窗通过UIContext中的showDatePickerDialog接口实现。
弹窗中配置DatePickerDialogOptions的lunarSwitch、showTime属性为true时会展示切换农历的开关和时间当checkbox被选中时会显示农历。
当按下确定按钮时弹窗会通过onDateAccept返回目前所选中的日期。
如需弹窗再次弹出时显示选中的是上一次确定的日期就要在回调中重新给selectTime进行赋值。
例子参考固定样式弹框通过配置disappearTextStyle、textStyle、selectedTextStyle、acceptButtonStyle、cancelButtonStyle实现了自定义文本以及按钮样式。
例子参考固定样式弹框如下图时间滑动选择器弹窗 (TimePickerDialog)开发者可根据24小时的时间区间创建时间滑动选择器弹窗将时间信息清晰地展示在弹出的窗口上。
时间滑动选择器弹窗通过UIContext中的showTimePickerDialog接口实现。
该示例通过配置disappearTextStyle、textStyle、selectedTextStyle、acceptButtonStyle、cancelButtonStyle实现了自定义文本以及按钮样式。
例子参考固定样式弹框文本滑动选择器弹窗 (TextPickerDialog)开发者可根据指定的选择范围创建文本滑动选择器弹窗将文本信息清晰地展示在弹出的窗口上。
文本滑动选择器弹窗通过UIContext中的showTextPickerDialog接口实现。
示例中通过设置range的参数类型为TextCascadePickerRangeContent[]实现3列文本选择器弹窗。
当按下确定按钮时弹窗会通过onAccept返回目前所选中文本和索引值。
如需弹窗再次弹出时显示选中的是上一次确定的文本就要在回调中重新给select进行赋值。
例子参考固定样式弹框列表选择弹窗 (ActionSheet)列表选择器弹窗适用于呈现多个操作选项尤其当界面中仅需展示操作列表而无其他内容时。
列表选择器弹窗通过UIContext中的showActionSheet接口实现。
列表选择弹窗中title字段的字体最大放大倍数为2。
该示例通过配置width、height、transition等接口定义了弹窗的样式以及弹出动效。
例子参考固定样式弹框警告弹窗 (AlertDialog)向用户提问或得到用户的许可时使用警告弹窗。
警告弹窗用来提示重要信息但会中断当前任务尽量提供必要的信息和有用的操作。
避免仅使用警告弹窗提供信息用户不喜欢被信息丰富但不可操作的警告打断。
警告弹窗通过UIContext中的showAlertDialog接口实现。
警告弹窗中title和subtitle字段的字体最大放大倍数为2。
该示例通过配置width、height、transition等接口定义了多个按钮弹窗的样式以及弹出动效。
例子参考固定样式弹框不依赖UI组件的全局自定义弹框在广告、中奖、警告、软件更新等与用户交互响应操作的场景下可以使用UIContext中获取到的PromptAction对象提供的openCustomDialog接口来实现自定义弹出框。
相较于CustomDialogController优势点在于页面解耦支持动态刷新。
说明弹出框openCustomDialog存在两种入参方式创建自定义弹出框openCustomDialog传参为ComponentContent形式通过ComponentContent封装内容可以与UI界面解耦调用更加灵活可以满足开发者的封装诉求。
具有较高的灵活性弹出框样式完全自定义并且在弹出框打开后可以使用updateCustomDialog方法动态更新弹出框的参数。
openCustomDialog传参为builder形式相对于ComponentContentbuilder必须要与上下文做绑定与UI存在一定耦合。
此方法有默认的弹出框样式适合于开发者想要实现与系统弹窗默认风格一致的效果。
本文介绍通过入参形式为ComponentContent创建自定义弹出框传builder形式的弹出框
使用方法可参考openCustomDialog。
弹出框openCustomDialog默认为模态弹窗且有蒙层不可与蒙层下方控件进行交互不支持点击和手势等向下透传。
可以通过配置promptAction.BaseDialogOptions类型中的isModal属性来实现模态和非模态弹窗详细说明可参考弹窗的种类。
当isModal为true时弹出框为模态弹窗且弹窗周围的蒙层区不支持透传。
isModal为false时弹出框为非模态弹窗且弹窗周围的蒙层区可以透传。
因此如果需要同时允许弹出框的交互和弹出框外页面的交互行为需要将弹出框设置为非模态。
生命周期弹出框提供了生命周期函数用于通知用户该弹出框的生命周期。
生命周期的触发时序依次为onWillAppear - onDidAppear - onWillDisappear - onDidDisappear。
名称类型说明onDidAppear() void弹出框弹出后的事件回调。
onDidDisappear() void弹出框消失后的事件回调。
onWillAppear() void弹出框显示动效前的事件回调。
onWillDisappear() void弹出框退出动效前的事件回调。
接口概述创建并弹出自定义弹框接口及参数说明更新自定义弹框接口及参数说明对自定义弹窗示例代码的讲解参考视频课程16分钟处自定义弹出框的打开与关闭说明详细变量定义请参考完整示例。
创建ComponentContent。
ComponentContent用于定义自定义弹出框的内容。
其中wrapBuilder(buildText)封装自定义组件new Params(this.message)是自定义组件的入参可以缺省也可以传入基础数据类型。
打开自定义弹出框。
调用openCustomDialog接口打开的弹出框默认customStyle为true即弹出框的内容样式完全按照contentNode自定义样式显示。
关闭自定义弹出框。
由于closeCustomDialog接口需要传入待关闭弹出框对应的ComponentContent。
因此如果需要在弹出框中设置关闭方法则可参考完整示例封装静态方法来实现。
关闭弹出框之后若需要释放对应的ComponentContent则需要调用ComponentContent的dispose方法。
更新自定义弹出框的内容ComponentContent与BuilderNode有相同的使用限制不支持自定义组件使用Reusable、Link、Provide、Consume等装饰器来同步弹出框弹出的页面与ComponentContent中自定义组件的状态。
因此若需要更新弹出框中自定义组件的内容可以通过ComponentContent提供的update方法来实现。
更新自定义弹出框的属性通过updateCustomDialog可以动态更新弹出框的属性。
目前支持更新弹出框的对齐方式、基于对齐方式的偏移量、是否点击蒙层自动关闭以及蒙层颜色对应的属性分别为BaseDialogOptions中的alignment、offset、autoCancel和maskColor。
更新属性时未设置的属性会恢复为默认值。
例如初始设置{ alignment: DialogAlignment.Top, offset: { dx: 0, dy: 50 } }更新时设置{ alignment: DialogAlignment.Bottom }则初始设置的offset: { dx: 0, dy: 50 }不会保留会恢复为默认值。
为弹出框内容和蒙层设置不同的动画效果当弹出框出现时内容与蒙层显示动效一致。
若开发者希望为弹出框内容及蒙层设定不同动画效果从API version 19开始可通过BaseDialogOptions中dialogTransition和maskTransition属性单独配置弹窗内容与蒙层的动画。
具体的动画效果请参考组件内转场 (transition)。
说明当isModal为true时蒙层将显示此时可以设置蒙层的动画效果否则maskTransition将不生效。
设置弹出框避让软键盘的距离为显示弹出框的独立性弹出框弹出时会与周边进行避让包括状态栏、导航条以及键盘等留有间距。
故当软键盘弹出时默认情况下弹出框会自动避开软键盘并与之保持16vp的距离。
从API version 15开始开发者可以利用BaseDialogOptions中的keyboardAvoidMode和keyboardAvoidDistance这两个配置项来设置弹出框在软键盘弹出时的行为包括是否需要避开软键盘以及与软键盘之间的距离。
设置软键盘间距时需要将keyboardAvoidMode值设为KeyboardAvoidMode.DEFAULT。
基于ArkUI实现多种样式弹框功能本篇Codelab主要介绍如何给应用添加各种类型的弹窗弹窗主要包括气泡提示Popup、即时反馈Toast、固定样式弹出框、自定义弹窗等。
帮助开发者了解各种弹窗的类型并掌握对应的
使用方法。
相关概念气泡提示Popup主要用于屏幕录制、信息弹出提醒等显示状态。
即时反馈Toast用于向用户显示简短的操作反馈或状态信息。
固定样式弹出框是系统提供的标准化弹窗具有固定的样式和交互方式。
自定义弹窗样式、布局、内容和行为可以根据应用场景进行个性化定制。
各案例代码参考基于ArkUI实现多种样式弹框功能气泡提示Popup的实现Row() { Image($r(app.media.dot_grid)) .width(
.height(
} .onClick(() { this.customPopup !this.customPopup }) .bindPopup(this.customPopup, { builder: this.PopupBuilder, // Bubble content placement: Placement.Bottom, // The pop position of the bubble onStateChange: (e) { if (!e.isVisible) { this.customPopup false; } } })即时反馈Toast的实现Row({ space: 2 }) { Text($r(app.string.save)) .fontSize(
.opacity(
0.