一、引言

弹窗和提示是应用与用户交互的重要方式。无论是确认操作、选择选项、展示信息，还是轻量级的操作反馈，都需要合适的弹窗组件。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 装饰器定义：

1. @CustomDialog 装饰：标记结构体为自定义弹窗组件。

2. controller 属性：controller?: CustomDialogController 用于控制弹窗的关闭，通过 this.controller?.close() 关闭弹窗。

3. 数据传递：使用 @Prop 接收外部传入的标题和内容。

4. 回调函数：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}` });
    }
  });
}

代码说明：

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

1. showAlert：确认弹窗，取消/确定按钮都有 Toast 反馈。
2. showActionSheet：底部操作列表，三个操作选项。
3. showToast：轻提示，2 秒后自动消失。
4. 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' })

代码说明：

弹窗类型速查表：

• 每行左侧是彩色标签（弹窗类型名），右侧是用途说明。
• 标签使用 borderRadius(6) 圆角，形成胶囊标签效果。
• 行间用浅色边框分隔，形成表格效果。
• 整体背景为淡紫色（#FAF7FF），与页面主色调呼应。

十、弹窗最佳实践

10.1 合理选择弹窗类型

• 简单确认 → AlertDialog。
• 多个操作选项 → ActionSheet。
• 复杂自定义内容 → CustomDialog。
• 轻量反馈 → Toast。

10.2 弹窗文案规范

• 标题简洁明确。
• 按钮文案使用动词（如"确定"“删除”“取消”）。
• 危险操作使用红色按钮并明确提示后果。

10.3 避免弹窗滥用

弹窗会打断用户操作，应尽量减少不必要的弹窗。轻量反馈优先使用 Toast。

10.4 处理弹窗关闭

自定义弹窗务必提供关闭方式（取消按钮、遮罩点击），避免用户无法关闭。

十一、常见问题

11.1 弹窗不显示

原因：可能在错误的生命周期调用，或弹窗控制器未正确初始化。

解决：确认在组件显示后调用，检查 CustomDialogController 初始化。

11.2 自定义弹窗无法关闭

原因：没有调用 controller.close()。

解决：在按钮回调中调用 this.controller?.close()。

11.3 Toast 不显示

原因：promptAction 未正确导入，或调用时机错误。

解决：确认 import { promptAction } from '@kit.ArkUI'。

十二、总结

本文深入讲解了 HarmonyOS 弹窗与提示体系，通过一个对话框演示风格的页面实战演示了 AlertDialog、ActionSheet、TextPickerDialog、Toast 等核心弹窗的使用。

核心要点回顾：

1. AlertDialog 用于确认/警告，支持主次按钮。
2. ActionSheet 用于底部操作列表。
3. CustomDialog 支持自定义内容，通过控制器管理。
4. TextPickerDialog / DatePickerDialog 提供滚轮选择。
5. Toast 是轻量提示，自动消失。
6. 合理选择弹窗类型，避免弹窗滥用。

弹窗是应用交互的重要组成部分，掌握它能让应用的操作反馈更加清晰友好。下一篇我们将讲解 HarmonyOS 列表与懒加载。