当前位置：首页 > news >正文

鸿蒙学习实战之路：Dialog 组件封装最佳实践

news 2026/5/12 18:26:41

鸿蒙学习实战之路：Dialog 组件封装最佳实践

Dialog 组件是 HarmonyOS 开发中常用的交互组件，用于实现弹窗提示、确认对话框等功能。本文将结合华为开发者联盟的官方最佳实践，介绍 Dialog 组件的封装方法和常见使用场景。

关于本文

本文基于华为开发者联盟官方文档《Dialog 封装最佳实践》整理而成，旨在帮助开发者快速掌握 Dialog 组件的封装技巧和最佳实践。

官方文档传送门永远是你的好伙伴，请收藏！

本文不能代替官方文档，所有内容均基于官方文档+个人实践经验总结
基本所有章节都会附上对应的文档链接，强烈建议你点击查看
所有代码示例建议自己动手尝试一下
如果英文水平不是很好，善用浏览器翻译功能

代码测试环境

确保你的开发环境符合以下要求：

软件/工具	版本要求
HarmonyOS SDK	API Level 11
TypeScript	5.0+
DevEco Studio	4.1+
设备要求	支持 HarmonyOS NEXT 的真机或模拟器

Dialog 组件概述

Dialog 组件是一种常见的界面交互组件，用于在当前页面之上显示一个模态窗口，通常用于：

提示用户重要信息
要求用户进行确认或选择
收集用户输入
展示加载状态

在 HarmonyOS 中，Dialog 组件提供了多种实现方式：

CustomDialogController：自定义对话框控制器
AlertDialog：系统预设的提示对话框
ConfirmDialog：系统预设的确认对话框
PromptDialog：系统预设的输入对话框

Dialog 组件封装意义

在实际开发中，直接使用系统提供的 Dialog 组件可能会导致以下问题：

代码重复：相同样式的 Dialog 在不同页面重复实现
维护困难：Dialog 样式或逻辑变更需要修改多个地方
一致性差：不同页面的 Dialog 样式和交互可能不一致
易用性低：每次使用都需要编写大量配置代码

通过封装 Dialog 组件，可以解决上述问题，提高开发效率和代码质量。

Dialog 组件封装最佳实践

1. 基础 Dialog 封装

功能说明：封装一个基础的自定义 Dialog 组件，支持自定义标题、内容和按钮。

实现步骤：

创建自定义 Dialog 组件
定义组件属性和事件
实现组件 UI 和交互逻辑
导出组件供外部使用

代码示例：

import { CustomDialog, CustomDialogController, Text, Button, Column, Row, FlexAlign, FontWeight, FontSize, Padding, Margin } from '@kit.ArkUI'// 自定义Dialog组件@CustomDialog
export struct BaseDialog {// 控制器，用于控制Dialog的显示和隐藏controller: CustomDialogController// 标题title: string = '提示'// 内容content: string = ''// 确认按钮文本confirmText: string = '确定'// 取消按钮文本cancelText: string = '取消'// 确认按钮点击事件onConfirm: () => void = () => {}// 取消按钮点击事件onCancel: () => void = () => {}// 是否显示取消按钮showCancel: boolean = truebuild() {Column({alignItems: FlexAlign.Center}) {// 标题Text(this.title).fontSize(FontSize.Medium).fontWeight(FontWeight.Bold).margin({ top: 20, bottom: 10 })// 内容Text(this.content).fontSize(FontSize.Small).textAlign(TextAlign.Center).margin({ bottom: 20 }).padding({ left: 20, right: 20 })// 按钮区域Row({justifyContent: FlexAlign.End,alignItems: FlexAlign.Center}) {// 取消按钮if (this.showCancel) {Button(this.cancelText).fontSize(FontSize.Small).margin({ right: 10 }).onClick(() => {this.onCancel()this.controller.close()})}// 确认按钮Button(this.confirmText).fontSize(FontSize.Small).type(ButtonType.Primary).onClick(() => {this.onConfirm()this.controller.close()})}.margin({ bottom: 20 })}.width(300).backgroundColor('#FFFFFF').borderRadius(12)}
}

2. Dialog 工具类封装

功能说明：封装一个 Dialog 工具类，提供静态方法快速创建和显示各种类型的 Dialog。下图展示了使用工具类实现的自定义弹窗效果：

实现步骤：

创建 Dialog 工具类
定义各种类型 Dialog 的静态方法
在方法内部创建 Dialog 控制器和实例
提供链式调用接口

代码示例：

import { BaseDialog } from "./BaseDialog";// Dialog工具类
export class DialogUtil {// 显示基础提示Dialogstatic showTipDialog(params: {title?: string;content: string;confirmText?: string;onConfirm?: () => void;}) {// 创建Dialog控制器const controller = new CustomDialogController({builder: BaseDialog({title: params.title || "提示",content: params.content,confirmText: params.confirmText || "确定",showCancel: false,onConfirm: params.onConfirm || (() => {}),}),autoCancel: true,alignment: DialogAlignment.Center,offset: { dx: 0, dy: 0 },gridCount: 4,});// 显示Dialogcontroller.open();return controller;}// 显示确认Dialogstatic showConfirmDialog(params: {title?: string;content: string;confirmText?: string;cancelText?: string;onConfirm?: () => void;onCancel?: () => void;}) {// 创建Dialog控制器const controller = new CustomDialogController({builder: BaseDialog({title: params.title || "确认",content: params.content,confirmText: params.confirmText || "确定",cancelText: params.cancelText || "取消",showCancel: true,onConfirm: params.onConfirm || (() => {}),onCancel: params.onCancel || (() => {}),}),autoCancel: true,alignment: DialogAlignment.Center,offset: { dx: 0, dy: 0 },gridCount: 4,});// 显示Dialogcontroller.open();return controller;}
}

3. 加载 Dialog 封装

功能说明：封装一个加载状态的 Dialog 组件，用于显示加载中的提示信息。

实现步骤：

创建加载 Dialog 组件
实现加载动画效果
提供显示和隐藏的控制方法

代码示例：

import { CustomDialog, CustomDialogController, Text, LoadingProgress, Column, FlexAlign, FontSize, Padding, Margin } from '@kit.ArkUI'// 加载Dialog组件@CustomDialog
export struct LoadingDialog {// 控制器controller: CustomDialogController// 加载提示文本message: string = '加载中...'build() {Column({alignItems: FlexAlign.Center}) {// 加载动画LoadingProgress().width(40).height(40).color('#007DFF').margin({ bottom: 10 })// 提示文本Text(this.message).fontSize(FontSize.Small).color('#666666')}.width(120).height(120).backgroundColor('rgba(0, 0, 0, 0.7)').borderRadius(12).padding(20)}
}// 加载Dialog工具类
export class LoadingDialogUtil {private static controller: CustomDialogController | null = null// 显示加载Dialogstatic show(message: string = '加载中...') {// 如果已经存在控制器，则先关闭if (this.controller) {this.controller.close()}// 创建新的控制器this.controller = new CustomDialogController({builder: LoadingDialog({message: message}),autoCancel: false,alignment: DialogAlignment.Center,offset: { dx: 0, dy: 0 },gridCount: 4})// 显示Dialogthis.controller.open()}// 隐藏加载Dialogstatic hide() {if (this.controller) {this.controller.close()this.controller = null}}
}

4. Dialog 组件使用示例

功能说明：展示如何使用封装后的 Dialog 组件。

实现步骤：

导入封装的 Dialog 组件和工具类
在页面中使用 Dialog 工具类显示不同类型的 Dialog

代码示例：

import { Page, Text, Button, Column, Row, FlexAlign, Margin, Padding } from '@kit.ArkUI'
import { DialogUtil, LoadingDialogUtil } from '../utils/DialogUtil'@Entry
@Component
struct DialogExample {build() {Column({alignItems: FlexAlign.Center,justifyContent: FlexAlign.Center}) {// 提示Dialog示例Button('显示提示Dialog').margin({ bottom: 20 }).onClick(() => {DialogUtil.showTipDialog({title: '提示',content: '这是一个提示Dialog',confirmText: '知道了',onConfirm: () => {console.log('提示Dialog确认按钮点击')}})})// 确认Dialog示例Button('显示确认Dialog').margin({ bottom: 20 }).onClick(() => {DialogUtil.showConfirmDialog({title: '确认',content: '确定要执行此操作吗？',confirmText: '确定',cancelText: '取消',onConfirm: () => {console.log('确认Dialog确认按钮点击')},onCancel: () => {console.log('确认Dialog取消按钮点击')}})})// 加载Dialog示例Button('显示加载Dialog').onClick(() => {// 显示加载DialogLoadingDialogUtil.show('数据加载中...')// 模拟异步操作setTimeout(() => {// 隐藏加载DialogLoadingDialogUtil.hide()}, 2000)})}.width('100%').height('100%').padding(20)}
}