鸿蒙学习实战之路：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 和交互逻辑
导出组件供外部使用

代码示例：

typescript 复制代码

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 = true

  build() {
    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 控制器和实例
提供链式调用接口

代码示例：

typescript 复制代码

import { BaseDialog } from "./BaseDialog";

// Dialog工具类
export class DialogUtil {
  // 显示基础提示Dialog
  static 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,
    });

    // 显示Dialog
    controller.open();
    return controller;
  }

  // 显示确认Dialog
  static 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,
    });

    // 显示Dialog
    controller.open();
    return controller;
  }
}

3. 加载 Dialog 封装

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

实现步骤：

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

代码示例：

typescript 复制代码

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

  // 显示加载Dialog
  static 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
    })

    // 显示Dialog
    this.controller.open()
  }

  // 隐藏加载Dialog
  static hide() {
    if (this.controller) {
      this.controller.close()
      this.controller = null
    }
  }
}

4. Dialog 组件使用示例

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

实现步骤：

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

代码示例：

typescript 复制代码

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(() => {
          // 显示加载Dialog
          LoadingDialogUtil.show('数据加载中...')

          // 模拟异步操作
          setTimeout(() => {
            // 隐藏加载Dialog
            LoadingDialogUtil.hide()
          }, 2000)
        })
    }
    .width('100%')
    .height('100%')
    .padding(20)
  }
}

Dialog 组件封装注意事项

属性设计：
- 提供合理的默认值
- 支持灵活的自定义配置
- 避免过度设计，保持组件简洁
事件处理：
- 提供明确的事件回调接口
- 处理好 Dialog 的显示和隐藏逻辑
- 避免内存泄漏
样式设计：
- 遵循设计规范，保持风格一致
- 支持主题切换
- 考虑不同屏幕尺寸的适配
性能优化：
- 避免不必要的重绘和重排
- 合理使用动画效果
- 及时释放资源

常见问题与解决方案

问题：Dialog 显示后无法点击外部区域关闭
解决方案 ：设置autoCancel属性为true
问题：Dialog 显示位置不正确
解决方案 ：调整alignment和offset属性
问题：Dialog 在某些设备上样式异常
解决方案：使用相对单位，避免硬编码尺寸
问题：Dialog 关闭后控制器未正确释放
解决方案：在关闭 Dialog 后将控制器设置为 null

参考文档

总结

本文介绍了 HarmonyOS 中 Dialog 组件的封装方法和最佳实践，包括基础 Dialog 封装、工具类封装、加载 Dialog 封装以及使用示例。通过封装 Dialog 组件，可以提高代码复用性、维护性和一致性，提升开发效率。

在实际开发中，建议根据项目需求和设计规范，灵活调整 Dialog 组件的封装方式，以达到最佳的使用效果。同时，要关注用户体验，确保 Dialog 的样式和交互符合用户预期。

希望本文对你有所帮助，如果你有任何问题或建议，欢迎在评论区交流讨论！