前言

Toast提示是轻量级的信息反馈方式，短暂显示后自动消失，不打断用户操作。@pura/harmony-utils 的 ToastUtil 封装了Toast显示方法，支持不同时长和位置。本文将从API说明、代码实战、进阶用法、常见问题等多个维度进行全面讲解，帮助开发者快速掌握并应用到实际项目中。

一、ToastUtil核心API

ToastUtil 提供了以下Toast显示方法：

方法	说明	参数	使用场景
show(message)	显示短时Toast	message	操作反馈
showLong(message)	显示长时Toast	message	较长提示
showAtBottom(message)	底部显示Toast	message	底部提示
showAtCenter(message)	居中显示Toast	message	居中提示

1.1 核心特性

• 简洁易用：封装复杂API为一行调用，降低使用门槛
• 类型安全：完整的TypeScript类型定义，编译期即可发现错误
• 异常处理：内置异常捕获机制，避免运行时崩溃
• 灵活定位：支持不同位置和时长

1.2 Toast与Dialog对比

特性	Toast	Dialog
打断性	不打断操作	阻断操作
显示时长	自动消失	需手动关闭
交互性	无	有按钮
适用场景	轻量反馈	重要确认

二、完整使用步骤

2.1 安装依赖

ohpm install @pura/harmony-utils

2.2 基本Toast

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

Button('显示短Toast')
  .width('100%')
  .onClick(() => {
    try {
      ToastUtil.show('操作成功');
      this.result = '短Toast已显示 🍞';
    } catch (e) {
      this.result = '异常: ' + e;
    }
  })

Button('显示长Toast')
  .width('100%')
  .onClick(() => {
    try {
      ToastUtil.showLong('这是一条较长的提示信息，会显示更久');
      this.result = '长Toast已显示 🍞🍞';
    } catch (e) {
      this.result = '异常: ' + e;
    }
  })

2.3 不同位置Toast

Button('底部Toast')
  .width('100%')
  .onClick(() => {
    ToastUtil.showAtBottom('底部提示');
    this.result = '底部Toast已显示';
  })

Button('居中Toast')
  .width('100%')
  .onClick(() => {
    ToastUtil.showAtCenter('居中提示');
    this.result = '居中Toast已显示';
  })

三、完整页面示例

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

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

  build() {
    Column({ space: 12 }) {
      Button('短Toast').width('100%').onClick(() => {
        ToastUtil.show('操作成功');
        this.result = '短Toast已显示';
      });
      Button('长Toast').width('100%').onClick(() => {
        ToastUtil.showLong('这是一条较长的提示信息');
        this.result = '长Toast已显示';
      });
      Button('底部Toast').width('100%').onClick(() => {
        ToastUtil.showAtBottom('底部提示');
      });
      Text(this.result).fontSize(14).fontColor('#333333')
    }
    .padding(16)
  }
}

四、进阶用法

4.1 操作反馈封装

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

function showSuccess(message: string): void {
  ToastUtil.showAtCenter(`✅ ${message}`);
}

function showError(message: string): void {
  ToastUtil.showAtCenter(`❌ ${message}`);
}

function showWarning(message: string): void {
  ToastUtil.showAtCenter(`⚠️ ${message}`);
}

4.2 网络状态提示

NetworkUtil.onNetworkChange(() => {
  if (NetworkUtil.isNetworkAvailable()) {
    ToastUtil.show('网络已恢复');
  } else {
    ToastUtil.showLong('网络已断开，请检查网络设置');
  }
});

五、注意事项

1. 频率控制：避免短时间内频繁显示Toast
2. 内容长度：Toast内容应简洁，不宜过长
3. 不阻断：Toast不会阻断用户操作
4. 初始化依赖：使用前需确保 AppUtil.init() 已调用
5. 时序问题：连续显示Toast时后者可能覆盖前者

六、常见问题

Q1: Toast显示后立即消失？

短时Toast约2秒消失，如需更久请使用showLong。

Q2: 连续调用show只显示最后一个？

Toast会覆盖前一个，建议间隔显示或合并消息。

Q3: Toast可以自定义样式吗？

ToastUtil提供标准样式，如需自定义请使用ArkUI的CustomDialog。

Q4: Toast在后台能显示吗？

Toast需要UI上下文，应用在后台时无法显示。

总结

ToastUtil 的Toast提示方法为轻量级信息反馈提供了便捷支持。本文详细介绍了核心API、使用步骤、完整示例、进阶用法以及常见问题的解决方案。开发者可以利用Toast实现操作反馈、状态提示等功能。

本文基于 @pura/harmony-utils 工具库，更多功能请参考官方文档与后续系列文章。