弹窗是一种在用户界面的前端弹出一个独立的窗口来吸引用户注意力的交互方式，常用于提示重要信息、引导用户操作、获取用户反馈或展示特定内容。本章将介绍警告弹窗、确认对话框、列表选择弹窗等多种交互弹窗，在避免过度打扰用户的同时，确保信息清晰、简洁地传达给用户。
6.1 使用警告弹窗
警告弹窗是一种强提醒的交互方式，通常用于向用户显示重要的信息、警告或需要用户确认的操作。
创建一个名为MyAlert的新的 HarmonyOS 项目，并打开工程开发面板。
在 build()函数中使用 Stack 组件作为父级容器，使用Button组件作为主体UI，代码如下：
//第6章/Index.ets
@Entry
@Component
struct Index {
build() {
Stack() {
Button('Show Alert', { type: ButtonType.Capsule, stateEffect: true })
.onClick(() => {
})
}
.height('100%')
.width('100%')
}
}
在onClick 事件中调用AlertDialog.show()方法来显示一个警告弹窗，并完成警告弹窗的样式，代码如下：
//第6章/Index.ets
AlertDialog.show({
title: 'System Alert',
message: 'Are you sure you want to add new data?',
alignment: DialogAlignment.Center,
confirm: {
value: 'OK',
action: () => {
console.info('Button-clicking callback')
}
},
cancel: () => {
console.info('Closed callbacks')
}
})
在AlertDialog.show()方法中有 5 种常用的参数，其中title用于设置弹窗的标题，message用于设置弹窗的说明文字，alignment 用于设置弹窗的显示位置。confirm用于设置弹窗的主要操作按钮，允许开发者设置主要按钮的文字和点击事件回调。cancel 用于设置弹窗被关闭时的回调事件。
在预览器中，点击Show Alert 按钮，开发者可以看到系统打开了一个警告弹窗，如图 6-1 所示。
图 6-1 警告弹窗预览
6.2 自定义弹窗按钮
在实际应用开发时，开发者可能会需要在警告弹窗中显示多个操作按钮，例如，当用户尝试删除一个数据项时，弹窗可以显示“确定”和“取消”两个按钮，用户只有在点击确认按钮后才会执行删除操作，从而提高应用的安全性和用户友好性。
创建一个名为MyAlertActions的新的 HarmonyOS 项目，并打开工程开发面板。
声明一个 string 类型的变量displayedText，用于显示按钮被点击时显示的文字。同时声明 AlertDialogButtonOptions[] 类型的状态变量buttons，用于显示警告弹窗的按钮组，代码如下：
//第6章/Index.ets
@State displayedText: string = 'Delete'
private buttons: AlertDialogButtonOptions[] = [
{
value: 'Cancel',
fontColor:Color.Gray,
action: () => {
this.displayedText = 'Cancel clicked'
}
},
{
value: 'Delete',
fontColor:Color.Red,
action: () => {
this.displayedText = 'Delete clicked'
}
},
]
buttons 数组中创建了 2 个按钮，其中Cancel 按钮的文字颜色为Gray，当该按钮被点击时设置displayedText 的值为Cancel clicked。Delete 按钮的文字颜色为Red，当该按钮被点击时设置displayedText 的值为Delete clicked。
将 build()函数中使用Stack、Button 组件构建 UI，并在Button 组件的点击事件中使用AlertDialog.show()方法来显示一个警告弹窗，同时设置警告弹窗中的按钮组来源于buttons 数组，代码如下：
//第6章/Index.ets
@Entry
@Component
struct Index {
@State displayedText: string = 'Delete'
private buttons: AlertDialogButtonOptions[] = [...]
build() {
Stack() {
Button(this.displayedText, { type: ButtonType.Capsule, stateEffect: true })
.onClick(() => {
AlertDialog.show({
title: 'Confirm Deletion',
message: 'Are you sure you want to delete this item?',
alignment: DialogAlignment.Center,
buttons: this.buttons,
cancel: () => {
this.displayedText = 'Closed callbacks'
}
})
})
}
.height('100%')
.width('100%')
}
}
在预览器中，当开发者点击警告弹窗中的Delete 按钮时，在首页上的Button 组件文字将显示Delete clicked，如图 6-2 所示。
图 6-2 自定义弹窗按钮
6.3 使用列表选择弹窗
相较于警告弹窗，ActionSheet（列表选择弹窗）是一种轻量级的交互方式，适合在需要用户从多个选项中选择一个操作时使用。
创建一个名为MyActionSheet的新的 HarmonyOS 项目，并打开工程开发面板。
声明一个 string 类型的变量displayedText，用于显示按钮被点击时显示的文字。同时声明 SheetInfo[] 类型的状态变量sheets，用于显示列表选择弹窗的按钮组，代码如下：
//第6章/Index.ets
@State displayedText: string = 'More Actions'
private sheets: SheetInfo[] = [
{
title: 'Edit',
action: () => {
this.displayedText = 'Editing item'
}
},
{
title: 'Share',
action: () => {
this.displayedText = 'Sharing item'
}
},
{
title: 'Delete',
action: () => {
this.displayedText = 'Deleting item'
}
},
{
title: 'Copy',
action: () => {
this.displayedText = 'Copying item'
}
},
{
title: 'Move',
action: () => {
this.displayedText = 'Moving item'
}
}
]
sheets定义了一个包含 5 个选项的数组，每个选项都有一个标题和一个点击时触发的回调函数，其中回调函数使用赋值运算符显示用户选择的操作文字。
将 build()函数中使用Stack、Button 组件构建 UI，并在Button 组件的点击事件中使用ActionSheet.show()方法来显示一个列表选择弹窗，同时设置列表选择弹窗中的选项组sheets来源于sheets数组，代码如下：
//第6章/Index.ets
@Entry
@Component
struct Index {
@State displayedText: string = 'More Actions'
private sheets: SheetInfo[] = [...]
build() {
Stack() {
Button(this.displayedText, { type: ButtonType.Capsule, stateEffect: true })
.onClick(() => {
ActionSheet.show({
title: 'More Actions',
subtitle: 'Choose an action',
message: 'Select what you want to do with this item',
sheets: this.sheets,
height: 350,
confirm: {
defaultFocus: true,
value: 'Cancel',
action: () => {
console.info('ActionSheet canceled by confirm button')
}
},
cancel: () => {
console.log('ActionSheet canceled by tapping outside')
},
})
})
}
.height('100%')
.width('100%')
}
}
在预览器中，当开发者点击列表选择弹窗中的选项时，点击的选项将会触发回调函数，从而首页上的Button组件文字将显示对应的文字，如图 6-3 所示。
图 6-3 列表选择弹窗预览
6.4 实现自定义弹窗
当 ArkUI 提供的系统弹窗无法满足业务诉求时，开发者也可以自定义弹窗组件来实现更复杂、更符合业务需求的交互效果。
创建一个名为MyDialog的新的 HarmonyOS 项目，并打开工程开发面板。
与使用@Component 装饰器构建自定义组件方式类似，@CustomDialog 装饰器用于构建一个自定义弹窗组件，代码如下：
//第6章/Index.ets
@CustomDialog
struct SheetView {
controller?: CustomDialogController
build() {
Stack() {
Column({space:28}) {
SymbolGlyph($r('sys.symbol.heart_fill'))
.fontSize(48)
.fontColor([Color.Red])
.margin({top:20})
Column({space:10}) {
Text('Make a Decision')
.fontSize(17)
.fontWeight(FontWeight.Bold)
Text('Use this helper to guide you through the decision-making process. Consider the pros and cons, and choose the option that best fits your needs.')
.fontSize(14)
.fontColor('#999999')
}
Column({space:10}) {
Button('DECIDE', { type: ButtonType.Capsule, stateEffect: true })
.width('60%')
.onClick(() => {
if (this.controller != undefined) {
this.controller.close()
}
})
Button('CANCEL', { type: ButtonType.Capsule, stateEffect: true })
.backgroundColor(0xD5D5D5)
.width('60%')
.onClick(() => {
if (this.controller != undefined) {
this.controller.close()
}
})
}
}
.padding(20)
}
.width('100%')
}
}
SheetView组件使用@CustomDialog装饰器装饰来构建一个自定义弹窗组件，在SheetView 弹窗中使用Stack、Column 组件对多个基础组件进行布局，并使用SymbolGlyph、Text、Button 组件实现基础样式。
CustomDialogController 需要在@CustomDialog装饰器装饰的弹窗内定义，来实现弹窗所需的交互逻辑，比如在Button 组件的点击事件中，当controller 存在时，可调用close()方法实现关闭弹窗交互。
回到Index 视图上，初始化一个构造器dialogController，用于控制自定义弹窗的显示和隐藏，并让该构造器指向目标弹窗SheetView，同时设置弹窗显示方向为从屏幕底部滑入，代码如下：
//第6章/Index.ets
@Entry
@Component
struct Index {
dialogController: CustomDialogController = new CustomDialogController({
builder: SheetView(),
alignment: DialogAlignment.Bottom,
})
build() {
Stack(){
Button('Show SheetView', { type: ButtonType.Capsule, stateEffect: true })
.onClick(() => {
this.dialogController.open()
})
}
.height('100%')
.width('100%')
}
}
在Button组件的点击事件中，可调用open()方法实现打开弹窗交互，如图 6-4 所示。
图 6-4 自定义弹窗预览
6.5 显示气泡提示
气泡提示是一种在视图上显示辅助说明内容的交互方式，用户可通过点击的方式来查询某一元素的说明内容，这种提示信息通常以一个小的弹出窗口形式出现，帮助用户理解特定的系统功能或内容。
创建一个名为MyPopup的新的 HarmonyOS 项目，并打开工程开发面板。
声明一个 boolean 类型的变量showPopup，用于控制气泡提示的显示和隐藏。同时声明 PopupOptions类型的状态变量popupOptions，用于显示气泡提示所需要展示的内容，代码如下：
@State showPopup: boolean = false
private popupOptions: PopupOptions = {
message: 'Popup content displayed here'
}
在build()函数中使用SymbolGlyph组件和Text 组件实现一个带有提示图标的文字，并使用bindPopup修饰器来实现气泡提示的功能，代码如下：
//第6章/Index.ets
@Entry
@Component
struct Index {
@State showPopup: boolean = false
private popupOptions: PopupOptions = {...}
build() {
Stack(){
Row({space:5}){
SymbolGlyph($r('sys.symbol.info_circle'))
Text('Popup')
}
.onClick(() => {
this.showPopup = !this.showPopup
})
.bindPopup(this.showPopup, this.popupOptions)
}
.height('100%')
.width('100%')
}
}
bindPopup 修饰器中有 2 个参数，分别用于绑定点击事件showPopup 和提示内容popupOptions。在预览器中，开发者可以点击图标文字，预览气泡提示的交互效果，如图 6-5 所示。
图 6-5 气泡提示预览
6.6 实现上下文菜单
上下文菜单是一种在有限的界面空间内为用户提供丰富的操作选项的交互方式，当用户可能需要对某个任务进行多种操作时，下文菜单允许用户点击按钮将列出所有可用的操作选项，方便用户进行选择。
创建一个名为MyContextMenus的新的 HarmonyOS 项目，并打开工程开发面板。
声明 MenuElement[] 类型的状态变量fileMenus，用于定义上下文菜单的所有选项，代码如下：
//第6章/Index.ets
private fileMenus: MenuElement[] = [
{
value: '打开',
action: () => {
console.info('正在打开文件')
}
},
{
value: '复制',
action: () => {
console.info('正在复制文件')
}
},
{
value: '粘贴',
action: () => {
console.info('正在粘贴文件')
}
},
{
value: '重命名',
action: () => {
console.info('正在重命名文件')
}
},
{
value: '删除',
action: () => {
console.info('正在删除文件')
}
}
]
fileMenus定义了一个包含 5 个选项的数组，每个选项都有一个选项名称和一个点击时触发的回调函数，其中回调函数使用console.info()方法打印用户操作的动作。
将 build()函数中使用Stack、Button 组件构建 UI，为 Button 组件添加bindMenu 修饰器用于构建上下文菜单，并为菜单绑定来源为fileMenus 的数组，代码如下：
//第6章/Index.ets
@Entry
@Component
struct Index {
private fileMenus: MenuElement[] = [...]
build() {
Stack() {
Button('文件操作', { type: ButtonType.Capsule, stateEffect: true })
.bindMenu(this.fileMenus)
}
.height('100%')
.width('100%')
}
}
在预览器中，当开发者点击“文件操作”选项时，系统会打开一个上下文菜单，如图 6-6 所示 。
图 6-6 上下文菜单预览
6.7 实现Toast弹窗
Toast是一种轻量级的提示弹窗，通常采用一两句话向用户传递临时性的信息，常用于操作反馈、状态提示等场景。Toast的显示和消失都非常迅速，因此不会让用户感到被打扰，同时还能及时提醒用户一些重要的信息。
创建一个名为MyToast的新的 HarmonyOS 项目，并打开工程开发面板。
Toast 组件在使用前需要导入@kit.ArkUI 模块中的promptAction工具接口，该接口用于实现调用ArkUI的Toast 组件的能力来创建并显示文本提示框、对话框和操作菜单。代码如下：
import { promptAction } from '@kit.ArkUI'
将 build()函数中使用Stack、Button 组件构建 UI，并在Button 组件的点击事件中使用promptAction.showToast()方法来显示一个Toast弹窗，代码如下：
//第6章/Index.ets
import { promptAction } from '@kit.ArkUI'
@Entry
@Component
struct Index {
build() {
Stack() {
Button('Show Toast', { type: ButtonType.Capsule, stateEffect: true })
.onClick(() => {
promptAction.showToast({
message: 'Login successful',
duration: 2000,
alignment:Alignment.Bottom,
})
})
}
.height('100%')
.width('100%')
}
}
在 promptAction.showToast()方法中，开发者可以设置Toast弹窗显示的文本、持续时长、显示位置，来动态调整Toast弹窗的样式。
在预览器中，当开发者点击Show Toast按钮时，系统会打开一个Toast弹窗，如图 6-7 所示 。
图 6-7 Toast弹窗预览
6.8 本章小结
本章围绕 ArkUI 中各类弹窗与提示组件的使用进行了详细讲解。通过对警告弹窗、自定义按钮弹窗、列表选择弹窗、气泡提示、上下文菜单及 Toast 弹窗的实现示例，读者可以系统地掌握 ArkUI 弹窗系统的用法与交互设计方式。
在实际开发中，弹窗组件是实现用户反馈、操作确认与提示信息的重要手段。本章不仅展示了内置弹窗的灵活配置，还引导读者完成了从基础使用到深度定制的实现过程。通过这些实战内容，开发者可以有效提升界面的交互性与信息传达效率，打造更加友好且易用的用户体验。
希望通过本章的学习，读者能够熟练运用 ArkUI 提供的弹窗能力，在项目中快速实现多样化的提示与交互设计，进一步提升应用的整体表现力与专业度。
