鸿蒙三方库 | harmony-utils之DialogUtil弹窗工具详解

2301_79533122

8人浏览 · 2026-07-25 00:32:35

2301_79533122 · 2026-07-25 00:32:35 发布

前言

弹窗是应用与用户交互的重要方式，用于信息确认、操作提示、数据输入等。@pura/harmony-utils 的 DialogUtil 封装了常用弹窗方法，简化了弹窗的创建和显示。本文将从API说明、代码实战、进阶用法、常见问题等多个维度进行全面讲解，帮助开发者快速掌握并应用到实际项目中。

在这里插入图片描述

一、DialogUtil核心API

DialogUtil 提供了以下弹窗方法：

方法	说明	返回类型	使用场景
`showAlert(title, message)`	显示提示弹窗	void	信息提示
`showConfirm(title, message)`	显示确认弹窗	boolean	操作确认
`showActionSheet(options)`	显示列表选择弹窗	number	选项选择

1.1 核心特性

简洁易用：封装复杂API为一行调用，降低使用门槛
类型安全：完整的TypeScript类型定义，编译期即可发现错误
异常处理：内置异常捕获机制，避免运行时崩溃
多种样式：支持提示、确认、列表选择三种弹窗

1.2 弹窗类型对照

类型	方法	按钮数	返回值
提示弹窗	showAlert	1个（确定）	void
确认弹窗	showConfirm	2个（确认/取消）	boolean
列表选择	showActionSheet	多个选项	number

二、完整使用步骤

2.1 安装依赖

ohpm install @pura/harmony-utils

2.2 提示弹窗

import { DialogUtil } from '@pura/harmony-utils';

Button('显示提示弹窗')
  .width('100%')
  .onClick(() => {
    try {
      DialogUtil.showAlert('提示', '操作已完成');
      this.result = '提示弹窗已显示 💬';
    } catch (e) {
      this.result = '异常: ' + e;
    }
  })

2.3 确认弹窗

Button('显示确认弹窗')
  .width('100%')
  .onClick(async () => {
    try {
      let confirmed = await DialogUtil.showConfirm('确认', '是否删除此文件？');
      this.result = `用户选择: ${confirmed ? '确认 ✅' : '取消 ❌'}`;
    } catch (e) {
      this.result = '异常: ' + e;
    }
  })

2.4 列表选择弹窗

Button('显示选择弹窗')
  .width('100%')
  .onClick(async () => {
    try {
      let index = await DialogUtil.showActionSheet(['拍照', '相册', '取消']);
      this.result = `选择了: 第${index}项`;
    } catch (e) {
      this.result = '异常: ' + e;
    }
  })

在这里插入图片描述

三、完整页面示例

import { DialogUtil } from '@pura/harmony-utils';

@Entry
@Component
struct DialogDemo {
  @State result: string = '';

  build() {
    Column({ space: 12 }) {
      Button('提示弹窗').width('100%').onClick(() => {
        DialogUtil.showAlert('提示', '操作成功');
      });
      Button('确认弹窗').width('100%').onClick(async () => {
        let ok = await DialogUtil.showConfirm('确认', '是否继续？');
        this.result = ok ? '确认' : '取消';
      });
      Button('选择弹窗').width('100%').onClick(async () => {
        let idx = await DialogUtil.showActionSheet(['选项1', '选项2']);
        this.result = `选择: ${idx}`;
      });
      Text(this.result).fontSize(14).fontColor('#333333')
    }
    .padding(16)
  }
}

四、进阶用法

4.1 删除确认

import { DialogUtil, ToastUtil } from '@pura/harmony-utils';

async function confirmDelete(filename: string): Promise<void> {
  let confirmed = await DialogUtil.showConfirm('删除确认', `确定删除 ${filename} 吗？此操作不可恢复。`);
  if (confirmed) {
    FileUtil.deleteFile(filename);
    ToastUtil.show('已删除');
  }
}

4.2 图片选择

async function selectImageSource(): Promise<string> {
  let index = await DialogUtil.showActionSheet(['拍照', '从相册选择', '取消']);
  if (index === 0) return 'camera';
  if (index === 1) return 'gallery';
  return 'cancel';
}