鴻蒙學習實戰之路：Dialog 組件封裝最佳實踐詳情 - 封裝,加載,開發者,Android,移動開發鹽焗西蘭花博客

鴻蒙學習實戰之路：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 = 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 的靜態方法
在方法內部創建 Dialog 控制器和實例
提供鏈式調用接口

代碼示例：

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 組件
實現加載動畫效果
提供顯示和隱藏的控制方法

代碼示例：

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

代碼示例：

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

參考文檔

華為開發者聯盟 - Dialog 封裝最佳實踐
華為開發者聯盟 - ArkUI 組件封裝
HarmonyOS 開發者文檔 - CustomDialogController
HarmonyOS 開發者文檔 - Dialog 組件
HarmonyOS 開發者文檔 - 組件封裝最佳實踐

總結

本文介紹了 HarmonyOS 中 Dialog 組件的封裝方法和最佳實踐，包括基礎 Dialog 封裝、工具類封裝、加載 Dialog 封裝以及使用示例。通過封裝 Dialog 組件，可以提高代碼複用性、維護性和一致性，提升開發效率。

在實際開發中，建議根據項目需求和設計規範，靈活調整 Dialog 組件的封裝方式，以達到最佳的使用效果。同時，要關注用户體驗，確保 Dialog 的樣式和交互符合用户預期。

希望本文對你有所幫助，如果你有任何問題或建議，歡迎在評論區交流討論！

鹽焗西蘭花博客

鹽焗西蘭花博客

博客 / 詳情