HarmonyOS 弹窗与提示：Dialog/Toast 完整指南

dingchengyu_

89人浏览 · 2026-08-25 23:35:20

dingchengyu_ · 2026-08-25 23:35:20 发布

在这里插入图片描述

一、引言

弹窗和提示是应用与用户交互的重要方式。无论是确认操作、选择选项、展示信息，还是轻量级的操作反馈，都需要合适的弹窗组件。HarmonyOS ArkUI 提供了丰富的弹窗能力，包括 AlertDialog、ActionSheet、CustomDialog、TextPickerDialog、DatePickerDialog 以及 Toast 轻提示等。

本文将以一个对话框演示风格的页面为主线，深入讲解各种弹窗的使用方法、参数配置和适用场景，帮助读者掌握弹窗开发的核心技能。

二、弹窗体系概览

2.1 弹窗分类

HarmonyOS 的弹窗可以分为以下几类：

类型	组件	适用场景
确认弹窗	AlertDialog	确认/警告/删除确认
操作列表	ActionSheet	底部操作选项
自定义弹窗	CustomDialog	自定义内容
选择器	TextPickerDialog	滚轮选择
选择器	DatePickerDialog	日期选择
选择器	TimePickerDialog	时间选择
轻提示	Toast	操作反馈

2.2 弹窗 vs Toast

特性	弹窗	Toast
交互性	需要用户操作	自动消失
展示时长	直到用户操作	短暂（默认 2 秒）
阻断性	阻断当前操作	不阻断
适用场景	重要决策	轻量反馈

三、AlertDialog 确认弹窗

3.1 基本用法

AlertDialog.show({
  title: '确认操作',
  message: '这是一个 AlertDialog 确认弹窗',
  primaryButton: {
    value: '取消',
    action: () => { console.info('点击了取消'); }
  },
  secondaryButton: {
    value: '确定',
    action: () => { console.info('点击了确定'); }
  },
  cancel: () => { console.info('点击了遮罩'); }
});

代码说明：

AlertDialog.show 是静态方法，直接调用即可弹出确认弹窗：

title：弹窗标题。
message：弹窗内容。
primaryButton：主按钮（通常为取消）。
secondaryButton：次按钮（通常为确定）。
cancel：点击遮罩层或返回键时的回调。

3.2 完整参数

AlertDialog.show({
  title: '删除确认',
  message: '确定要删除这条记录吗？删除后不可恢复。',
  autoCancel: true,          // 点击遮罩是否关闭
  alignment: DialogAlignment.Center, // 弹窗位置
  offset: { dx: 0, dy: 0 },  // 位置偏移
  gridCount: 3,              // 栅格列数
  primaryButton: {
    value: '取消',
    fontColor: '#999999',
    action: () => {}
  },
  secondaryButton: {
    value: '删除',
    fontColor: '#FF4757',
    action: () => {}
  },
  cancel: () => {},
  onWillDismiss: (dismissAction) => {
    // 拦截关闭事件
    dismissAction.dismiss();
  }
});

四、ActionSheet 操作列表

4.1 基本用法

ActionSheet.show({
  title: '请选择操作',
  message: 'ActionSheet 底部操作列表',
  buttons: [
    { value: '复制', action: () => { console.info('复制'); } },
    { value: '分享', action: () => { console.info('分享'); } },
    { value: '删除', action: () => { console.info('删除'); } }
  ]
});

代码说明：

ActionSheet.show 用于弹出底部操作列表：

title：标题。
message：描述信息。
buttons：操作按钮数组，每个按钮包含 value（文字）和 action（点击回调）。

ActionSheet 适合提供多个操作选项的场景，如复制、分享、删除等。

五、CustomDialog 自定义弹窗

5.1 定义自定义弹窗

@CustomDialog
struct MyCustomDialog {
  controller?: CustomDialogController;
  @Prop title: string = '';
  @Prop content: string = '';
  onConfirm: () => void = () => {};

  build() {
    Column({ space: 12 }) {
      Text(this.title)
        .fontSize(18)
        .fontWeight(FontWeight.Bold)
      Text(this.content)
        .fontSize(14)
        .fontColor('#666666')
      Row({ space: 16 }) {
        Button('取消')
          .onClick(() => {
            this.controller?.close();
          })
        Button('确定')
          .onClick(() => {
            this.onConfirm();
            this.controller?.close();
          })
      }
    }
    .padding(24)
  }
}

代码说明：

自定义弹窗通过 @CustomDialog 装饰器定义：

@CustomDialog 装饰：标记结构体为自定义弹窗组件。
controller 属性：controller?: CustomDialogController 用于控制弹窗的关闭，通过 this.controller?.close() 关闭弹窗。
数据传递：使用 @Prop 接收外部传入的标题和内容。
回调函数：onConfirm 是外部传入的回调，用于处理确认操作。

5.2 使用自定义弹窗

@Entry
@Component
struct DialogPage {
  dialogController: CustomDialogController = new CustomDialogController({
    builder: MyCustomDialog({
      title: '自定义弹窗',
      content: '这是一个自定义内容的弹窗',
      onConfirm: () => { console.info('确认'); }
    }),
    autoCancel: true
  });

  showCustom(): void {
    this.dialogController.open();
  }
}

代码说明：

CustomDialogController 是弹窗控制器，在组件中声明。
builder 参数传入自定义弹窗组件实例。
通过 this.dialogController.open() 打开弹窗。

六、TextPickerDialog 滚轮选择器

6.1 基本用法

TextPickerDialog.show({
  range: ['ArkTS', 'TypeScript', 'JavaScript', 'Cangjie', 'C++'],
  selected: 0,
  onAccept: (value: TextPickerResult) => {
    console.info(`选择了索引: ${value.index}`);
  },
  onCancel: () => {
    console.info('取消了选择');
  }
});

代码说明：

TextPickerDialog.show 弹出滚轮选择器：

range：选项数组。
selected：默认选中的索引。
onAccept：点击确定时的回调，参数 value.index 是选中项的索引。
onCancel：取消时的回调。

七、DatePickerDialog 日期选择器

DatePickerDialog.show({
  start: new Date('2000-1-1'),
  end: new Date('2030-12-31'),
  selected: new Date(),
  lunar: false,
  onAccept: (value: DatePickerResult) => {
    console.info(`选择的日期: ${value.year}-${value.month}-${value.day}`);
  }
});

代码说明：

start / end：可选日期的范围。
selected：默认选中日期。
lunar：是否显示农历。
onAccept：确认回调，value 包含 year、month、day。

八、Toast 轻提示

8.1 基本用法

import { promptAction } from '@kit.ArkUI';

promptAction.showToast({
  message: '操作成功',
  duration: 2000
});

代码说明：

promptAction.showToast 弹出轻提示。
message：提示内容。
duration：展示时长（毫秒），默认 2000。

8.2 Toast 的定位

promptAction.showToast({
  message: '顶部提示',
  duration: 2000,
  bottom: '500px'  // 距离底部的位置
});

8.3 其他提示方式

// 对话框提示
promptAction.showDialog({
  title: '提示',
  message: '这是一个对话框',
  buttons: [
    { text: '确定', color: '#FF4757' }
  ]
});

// 操作菜单
promptAction.showActionMenu({
  title: '菜单',
  buttons: [
    { text: '选项一', color: '#2F3542' }
  ]
});

九、实战代码：弹窗演示页面

下面我们实现一个完整的弹窗演示页面。

9.1 定义数据结构

interface DialogRow {
  type: string;
  use: string;
  color: string;
}

代码说明：

DialogRow 接口描述弹窗类型表格中的一行数据，包含弹窗类型、用途和标识颜色。

9.2 弹窗触发方法

showAlert(): void {
  AlertDialog.show({
    title: '确认操作',
    message: '这是一个 AlertDialog 确认弹窗',
    primaryButton: {
      value: '取消',
      action: () => { promptAction.showToast({ message: '已取消' }); }
    },
    secondaryButton: {
      value: '确定',
      action: () => { promptAction.showToast({ message: '已确定' }); }
    },
    cancel: () => { promptAction.showToast({ message: '点击了遮罩' }); }
  });
}

showActionSheet(): void {
  ActionSheet.show({
    title: '请选择操作',
    message: 'ActionSheet 底部操作列表',
    buttons: [
      { value: '复制', action: () => { promptAction.showToast({ message: '复制成功' }); } },
      { value: '分享', action: () => { promptAction.showToast({ message: '分享面板' }); } },
      { value: '删除', action: () => { promptAction.showToast({ message: '已删除' }); } }
    ]
  });
}

showToast(): void {
  promptAction.showToast({ message: 'Toast 轻提示，2 秒后消失', duration: 2000 });
}

showTextPicker(): void {
  TextPickerDialog.show({
    range: ['ArkTS', 'TypeScript', 'JavaScript', 'Cangjie', 'C++'],
    selected: 0,
    onAccept: (value: TextPickerResult) => {
      promptAction.showToast({ message: `选择了: ${value.index}` });
    }
  });
}

代码说明：

四个方法分别演示了四种弹窗：

showAlert：确认弹窗，取消/确定按钮都有 Toast 反馈。
showActionSheet：底部操作列表，三个操作选项。
showToast：轻提示，2 秒后自动消失。
showTextPicker：滚轮选择器，选择结果通过 Toast 反馈。

9.3 构建 UI

build() {
  Scroll() {
    Column({ space: 16 }) {
      // 顶部标题
      Column() {
        Text('DIALOG')
          .fontSize(12)
          .fontColor('#B8A5FF')
          .letterSpacing(6)
        Text('弹窗与提示')
          .fontSize(26)
          .fontWeight(FontWeight.Bold)
          .fontColor(Color.White)
          .margin({ top: 6 })
        Text('AlertDialog · ActionSheet · Toast')
          .fontSize(12)
          .fontColor('#B8A5FF')
          .margin({ top: 6 })
      }
      .width('100%')
      .padding({ top: 48, bottom: 30 })
      .backgroundColor('#5F4B8B')

      // 弹窗触发按钮组（不同样式）
      Column({ space: 12 }) {
        Button('⚠ 确认弹窗 AlertDialog')
          .width('100%')
          .height(46)
          .fontSize(14)
          .fontColor(Color.White)
          .backgroundColor('#FF4757')
          .borderRadius(10)
          .onClick(() => { this.showAlert(); })

        Button('☰ 底部操作 ActionSheet')
          .width('100%')
          .height(46)
          .fontSize(14)
          .fontColor(Color.White)
          .backgroundColor('#3742FA')
          .borderRadius(10)
          .onClick(() => { this.showActionSheet(); })

        Button('⚙ 滚轮选择 TextPickerDialog')
          .width('100%')
          .height(46)
          .fontSize(14)
          .fontColor(Color.White)
          .backgroundColor('#2ED573')
          .borderRadius(10)
          .onClick(() => { this.showTextPicker(); })

        Button('💬 轻提示 Toast')
          .width('100%')
          .height(46)
          .fontSize(14)
          .fontColor('#5F4B8B')
          .backgroundColor('#FFEAA7')
          .borderRadius(10)
          .border({ width: 1, color: '#FFA502' })
          .onClick(() => { this.showToast(); })
      }
      .width('100%')
      .padding(16)
      .backgroundColor('#FFFFFF')
      .borderRadius(16)
      .shadow({ radius: 8, color: '#22000000', offsetY: 4 })

代码说明：

弹窗触发按钮组：

每个按钮使用不同的背景色，通过颜色区分弹窗类型：
- AlertDialog：红色（#FF4757）。
- ActionSheet：靛蓝（#3742FA）。
- TextPickerDialog：绿色（#2ED573）。
- Toast：黄色（#FFEAA7）配橙色描边。
按钮文字带图标（⚠、☰、⚙、💬），增强可读性。
每个按钮点击触发对应的弹窗方法。

      // 弹窗类型对比表
      Column() {
        Text('弹窗类型速查')
          .fontSize(14)
          .fontWeight(FontWeight.Bold)
          .fontColor('#5F4B8B')
          .alignSelf(ItemAlign.Start)
          .margin({ bottom: 8 })
        ForEach(this.dialogs, (row: DialogRow) => {
          Row({ space: 12 }) {
            Text(row.type)
              .fontSize(12)
              .fontWeight(FontWeight.Bold)
              .fontColor(Color.White)
              .padding({ left: 10, right: 10, top: 4, bottom: 4 })
              .backgroundColor(row.color)
              .borderRadius(6)
            Text(row.use)
              .fontSize(12)
              .fontColor('#555555')
              .layoutWeight(1)
          }
          .width('100%')
          .padding({ top: 10, bottom: 10 })
          .border({ width: { bottom: 1 }, color: '#EEEEEE' })
        })
      }
      .width('100%')
      .padding(16)
      .backgroundColor('#FAF7FF')
      .borderRadius(14)
      .border({ width: 1, color: '#E5DDF5' })