📚 目录

• 1. 概述
• 2. 引入三方库
• 3. 目录结构
• 4. 核心代码解读
• 5. 实际步骤
• 6. 常见错误与解决方案
• 7. 进阶功能
• 8. 总结

1. 概述

1.1 什么是 FlutterToast？

fluttertoast 是一个轻量级的 Flutter 吐司提示库，提供了：

• ✅ 灵活的位置控制：支持顶部、中间、底部等多种位置
• ✅ 自定义时长：可设置短时（2秒）或长时（3.5秒）
• ✅ 丰富的样式选项：背景色、文字颜色、字体大小等
• ✅ 轻量级：体积小，性能好，适合天气应用的轻量反馈
• ✅ HarmonyOS 适配：使用鸿蒙化版本（br_8.2.8_ohos），针对 HarmonyOS 平台优化

📌 重要提示：

本教程使用的是 鸿蒙化版本的 fluttertoast，通过 AtomGit仓库引入：

• 仓库地址：https://atomgit.com/openharmony-sig/flutter_fluttertoast.git
• 分支版本：br_8.2.8_ohos
• 适配平台：HarmonyOS/OpenHarmony

1.2 为什么选择 FlutterToast？

相比系统自带的 SnackBar，fluttertoast 具有以下优势：

特性	SnackBar	FlutterToast
📍 位置控制	仅底部	顶部/中间/底部
⏱️ 时长控制	固定	灵活可调
🎨 样式自定义	有限	丰富
💡 轻量级	较重	轻量
🔧 使用便捷	需要 Context	全局调用
📱 跨平台	支持	支持

1.3 应用场景

在天气应用中，我们使用 fluttertoast 实现：

• ✅ 操作反馈：保存设置、切换城市等操作成功提示
• ✅ 错误提示：网络错误、数据加载失败等错误信息
• ✅ 警告提示：城市已存在、数据过期等警告信息
• ✅ 信息提示：功能说明、使用提示等信息展示

1.4 功能流程图

---

2. 引入三方库

2.1 添加依赖

在 pubspec.yaml 文件的 dependencies 部分添加：

dependencies:
  flutter:
    sdk: flutter
  
  # Toast 提示组件（鸿蒙化版本）
  fluttertoast:
    git:
      url: https://gitcode.com/openharmony-sig/flutter_fluttertoast.git
      ref: br_8.2.8_ohos

📝 代码解读：

• fluttertoast:: 依赖包名称
• git:: 指定使用 Git 方式引入依赖
• url:: Git 仓库地址（OpenHarmony SIG 官方仓库）
• ref:: 指定分支版本（br_8.2.8_ohos 为鸿蒙适配版本）

⚠️ 重要说明：

• ✅ 必须使用鸿蒙化版本：本项目针对 HarmonyOS 平台，必须使用 br_8.2.8_ohos 分支
• ✅ Git 方式引入：不能使用 pub.dev 版本，必须通过 Git 方式引入
• ✅ 网络要求：确保网络连接正常，能够访问 gitcode.com

2.2 安装依赖

在项目根目录运行：

flutter pub get

预期输出：

Resolving dependencies...
Downloading packages...
+ fluttertoast (from git)
Got dependencies!

✅ 成功标志：

• 看到 Got dependencies! 提示
• 没有错误信息
• .dart_tool/package_config.json 文件中包含 fluttertoast

2.3 依赖说明

依赖包	版本/分支	用途	来源
fluttertoast	br_8.2.8_ohos	Toast 提示组件核心库，提供吐司提示功能	GitCode (鸿蒙化版本)

💡 为什么使用鸿蒙化版本？

• 🎯 平台适配：针对 HarmonyOS 平台进行了专门优化和适配
• 🔧 兼容性：确保在 HarmonyOS 上正常运行
• 📱 性能优化：针对 HarmonyOS 系统特性进行了性能优化
• 🛡️ 稳定性：经过 OpenHarmony SIG 团队测试和验证

2.4 平台配置

HarmonyOS 配置：

使用鸿蒙化版本的 fluttertoast 在 HarmonyOS 上无需额外配置，可以直接使用。

⚠️ 注意事项：

• ✅ 确保使用 br_8.2.8_ohos 分支版本
• ✅ 不要使用 pub.dev 上的标准版本
• ✅ 如果遇到问题，检查网络连接和 Git 仓库访问权限

---

3. 目录结构

3.1 项目结构

lib/
├── utils/
│   └── toast_util.dart          # Toast 工具类（封装 fluttertoast）
├── screens/
│   ├── profile_page.dart        # 我的页面（使用 Toast）
│   ├── city_manage_page.dart    # 城市管理页面（使用 Toast）
│   ├── home_page.dart           # 首页（使用 Toast）
│   └── case_detail_page.dart   # 案例详情页（使用 Toast）
└── main.dart                    # 应用入口

3.2 文件说明

• toast_util.dart：Toast 工具类

  • 封装 fluttertoast 的常用方法
  • 提供统一的接口（成功、错误、警告、信息）
  • 简化使用，提高代码可维护性

• 各页面文件：使用 Toast 的页面

  • 导入 toast_util.dart
  • 调用 ToastUtil 的静态方法显示提示

---

4. 核心代码解读

4.1 Toast 工具类架构

4.2 Toast 工具类实现

创建 lib/utils/toast_util.dart 文件：

import 'package:flutter/material.dart';
import 'package:fluttertoast/fluttertoast.dart';

/// Toast 工具类
/// 封装 fluttertoast，提供统一的吐司提示接口
class ToastUtil {
  /// 显示成功提示
  /// [message] 提示信息
  /// [duration] 显示时长（秒），默认2秒
  static void showSuccess(String message, {int duration = 2}) {
    Fluttertoast.showToast(
      msg: message,
      toastLength: duration > 3 ? Toast.LENGTH_LONG : Toast.LENGTH_SHORT,
      gravity: ToastGravity.BOTTOM,
      backgroundColor: Colors.green.shade600,
      textColor: Colors.white,
      fontSize: 14.0,
    );
  }

  /// 显示错误提示
  /// [message] 提示信息
  /// [duration] 显示时长（秒），默认3秒
  static void showError(String message, {int duration = 3}) {
    Fluttertoast.showToast(
      msg: message,
      toastLength: duration > 3 ? Toast.LENGTH_LONG : Toast.LENGTH_SHORT,
      gravity: ToastGravity.BOTTOM,
      backgroundColor: Colors.red.shade600,
      textColor: Colors.white,
      fontSize: 14.0,
    );
  }

  /// 显示警告提示
  /// [message] 提示信息
  /// [duration] 显示时长（秒），默认2秒
  static void showWarning(String message, {int duration = 2}) {
    Fluttertoast.showToast(
      msg: message,
      toastLength: duration > 3 ? Toast.LENGTH_LONG : Toast.LENGTH_SHORT,
      gravity: ToastGravity.BOTTOM,
      backgroundColor: Colors.orange.shade600,
      textColor: Colors.white,
      fontSize: 14.0,
    );
  }

  /// 显示普通提示
  /// [message] 提示信息
  /// [duration] 显示时长（秒），默认2秒
  /// [gravity] 显示位置，默认底部
  static void show(String message, {
    int duration = 2,
    ToastGravity gravity = ToastGravity.BOTTOM,
    Color? backgroundColor,
    Color? textColor,
  }) {
    Fluttertoast.showToast(
      msg: message,
      toastLength: duration > 3 ? Toast.LENGTH_LONG : Toast.LENGTH_SHORT,
      gravity: gravity,
      backgroundColor: backgroundColor ?? Colors.grey.shade800,
      textColor: textColor ?? Colors.white,
      fontSize: 14.0,
    );
  }

  /// 显示信息提示（蓝色）
  /// [message] 提示信息
  /// [duration] 显示时长（秒），默认2秒
  static void showInfo(String message, {int duration = 2}) {
    Fluttertoast.showToast(
      msg: message,
      toastLength: duration > 3 ? Toast.LENGTH_LONG : Toast.LENGTH_SHORT,
      gravity: ToastGravity.BOTTOM,
      backgroundColor: Colors.blue.shade600,
      textColor: Colors.white,
      fontSize: 14.0,
    );
  }

  /// 取消当前显示的 Toast
  static void cancel() {
    Fluttertoast.cancel();
  }
}

关键参数说明：

• msg：要显示的提示信息
• toastLength：显示时长
  • Toast.LENGTH_SHORT：短时（约2秒）
  • Toast.LENGTH_LONG：长时（约3.5秒）
• gravity：显示位置
  • ToastGravity.TOP：顶部
  • ToastGravity.CENTER：中间
  • ToastGravity.BOTTOM：底部（默认）
• backgroundColor：背景颜色
• textColor：文字颜色
• fontSize：字体大小

4.3 使用流程

---

5. 实际步骤

5.1 步骤1：创建 Toast 工具类

创建 lib/utils/toast_util.dart 文件，参考上面的代码实现。

💡 新手提示：

• 工具类使用 static 方法，可以直接通过类名调用
• 封装常用方法，简化使用，提高代码可维护性

5.2 步骤2：在页面中导入工具类

在需要使用 Toast 的页面文件顶部添加导入：

import '../utils/toast_util.dart';

5.3 步骤3：替换 SnackBar 为 Toast

5.3.1 替换成功提示

原来的代码（SnackBar）：

ScaffoldMessenger.of(context).showSnackBar(
  SnackBar(
    content: Text('已保存'),
    duration: const Duration(seconds: 1),
  ),
);

替换后的代码（Toast）：

ToastUtil.showSuccess('已保存');

5.3.2 替换错误提示

原来的代码（SnackBar）：

ScaffoldMessenger.of(context).showSnackBar(
  SnackBar(
    content: Text('保存失败'),
    duration: const Duration(seconds: 3),
    backgroundColor: Colors.red.shade300,
  ),
);

替换后的代码（Toast）：

ToastUtil.showError('保存失败', duration: 3);

5.3.3 替换警告提示

原来的代码（SnackBar）：

ScaffoldMessenger.of(context).showSnackBar(
  SnackBar(
    content: Text('该城市已存在'),
    duration: const Duration(seconds: 2),
    backgroundColor: Colors.orange.shade300,
  ),
);

替换后的代码（Toast）：

ToastUtil.showWarning('该城市已存在');

5.3.4 替换信息提示

原来的代码（SnackBar）：

ScaffoldMessenger.of(context).showSnackBar(
  const SnackBar(
    content: Text('请在搜索框中输入城市名称'),
    duration: Duration(seconds: 2),
  ),
);

替换后的代码（Toast）：

ToastUtil.showInfo('请在搜索框中输入城市名称');

5.4 步骤4：实际应用示例

5.4.1 在"我的"页面中使用

// 保存设置成功
ToastUtil.showSuccess('设置已保存');

// 切换开关
ToastUtil.show('个性化推荐已${value ? "开启" : "关闭"}');

5.4.2 在城市管理页面中使用

// 添加城市成功
ToastUtil.showSuccess('已添加 ${city.name}');

// 删除城市成功
ToastUtil.showSuccess('已删除 ${city.name}');

// 切换城市成功
ToastUtil.showSuccess('已切换到 ${city.name}');

// 城市已存在警告
ToastUtil.showWarning('该城市已存在');

// 搜索失败错误
ToastUtil.showError('搜索失败: $errorMessage', duration: 3);

5.4.3 在首页中使用

// 未找到城市
ToastUtil.showWarning('未找到城市: $cityName');

// 搜索失败
ToastUtil.showError('搜索失败: $e');

5.5 步骤5：自定义 Toast 样式

如果需要自定义样式，可以使用 show() 方法：

// 自定义位置和样式
ToastUtil.show(
  '自定义提示信息',
  duration: 3,
  gravity: ToastGravity.TOP,  // 显示在顶部
  backgroundColor: Colors.purple.shade600,
  textColor: Colors.white,
);

5.6 步骤6：取消 Toast

如果需要手动取消当前显示的 Toast：

ToastUtil.cancel();

---

6. 常见错误与解决方案

6.1 错误：Toast 不显示

可能原因：

• 未正确导入 fluttertoast 包
• 未调用 flutter pub get 安装依赖
• 使用了错误的版本（未使用鸿蒙化版本）
• Context 问题（fluttertoast 不需要 Context，但需要确保应用已初始化）

解决方案：

// ✅ 正确：确保已导入
import 'package:fluttertoast/fluttertoast.dart';
import '../utils/toast_util.dart';

// ✅ 正确：直接调用，无需 Context
ToastUtil.showSuccess('提示信息');

// ❌ 错误：不需要 Context
// ToastUtil.showSuccess('提示信息', context: context);

⚠️ 鸿蒙版本检查：

确保 pubspec.yaml 中使用的是鸿蒙化版本：

# ✅ 正确：使用鸿蒙化版本
fluttertoast:
  git:
    url: https://gitcode.com/openharmony-sig/flutter_fluttertoast.git
    ref: br_8.2.8_ohos

# ❌ 错误：不要使用 pub.dev 版本
# fluttertoast: ^8.2.4

6.6 错误：Git 依赖下载失败

可能原因：

• 网络连接问题，无法访问 gitcode.com
• Git 仓库地址错误
• 分支版本不存在

解决方案：

# 1. 检查网络连接
ping gitcode.com

# 2. 清理缓存后重新获取
flutter clean
flutter pub get

# 3. 检查 pubspec.yaml 配置是否正确
# 确保 url 和 ref 正确

💡 提示：

• 如果网络不稳定，可以尝试使用代理
• 确保 Git 已正确安装和配置
• 检查 .dart_tool/package_config.json 确认依赖是否正确下载

6.2 错误：Toast 显示位置不正确

可能原因：

• gravity 参数设置错误
• 在某些平台上可能不支持某些位置

解决方案：

// ✅ 正确：使用预定义的位置常量
ToastUtil.show(
  '提示信息',
  gravity: ToastGravity.BOTTOM,  // 底部
);

ToastUtil.show(
  '提示信息',
  gravity: ToastGravity.TOP,     // 顶部
);

ToastUtil.show(
  '提示信息',
  gravity: ToastGravity.CENTER,  // 中间
);

6.3 错误：Toast 时长设置无效

可能原因：

• duration 参数单位理解错误（应该是秒数，不是 Duration）
• toastLength 和 duration 参数冲突

解决方案：

// ✅ 正确：duration 是秒数
ToastUtil.showSuccess('提示信息', duration: 2);  // 2秒
ToastUtil.showSuccess('提示信息', duration: 4);  // 4秒（长时）

// ❌ 错误：不要使用 Duration
// ToastUtil.showSuccess('提示信息', duration: Duration(seconds: 2));

💡 提示：

• duration <= 3：使用 Toast.LENGTH_SHORT（约2秒）
• duration > 3：使用 Toast.LENGTH_LONG（约3.5秒）

6.4 错误：Toast 样式不生效

可能原因：

• 颜色值设置错误
• 在某些平台上可能不支持某些颜色

解决方案：

// ✅ 正确：使用 Material 颜色
ToastUtil.show(
  '提示信息',
  backgroundColor: Colors.green.shade600,
  textColor: Colors.white,
);

// ✅ 正确：使用预定义方法（推荐）
ToastUtil.showSuccess('成功');  // 绿色
ToastUtil.showError('错误');    // 红色
ToastUtil.showWarning('警告');  // 橙色
ToastUtil.showInfo('信息');     // 蓝色

6.5 错误：多个 Toast 重叠显示

可能原因：

• 快速连续调用多个 Toast
• 未取消之前的 Toast

解决方案：

// ✅ 正确：取消之前的 Toast
ToastUtil.cancel();
ToastUtil.showSuccess('新的提示');

// ✅ 正确：使用防抖机制
Timer? _toastTimer;
void _showToast(String message) {
  _toastTimer?.cancel();
  ToastUtil.cancel();
  _toastTimer = Timer(const Duration(milliseconds: 100), () {
    ToastUtil.showSuccess(message);
  });
}

---

7. 进阶功能

7.1 自定义 Toast 工具类

可以根据项目需求扩展 ToastUtil：

class ToastUtil {
  // ... 现有方法 ...
  
  /// 显示网络错误提示
  static void showNetworkError() {
    showError('网络连接失败，请检查网络设置', duration: 3);
  }
  
  /// 显示加载中提示
  static void showLoading(String message) {
    show(
      message,
      duration: 1,
      gravity: ToastGravity.CENTER,
      backgroundColor: Colors.black87,
    );
  }
  
  /// 显示天气相关提示
  static void showWeatherInfo(String message) {
    showInfo('🌤️ $message');
  }
}

7.2 不同场景的 Toast 使用

7.3 Toast 最佳实践

1. 选择合适的提示类型

   • ✅ 成功操作 → showSuccess
   • ❌ 错误信息 → showError
   • ⚠️ 警告信息 → showWarning
   • ℹ️ 普通信息 → showInfo

2. 设置合理的时长

   • 简单提示：2秒
   • 重要提示：3-4秒
   • 错误提示：3秒以上

3. 使用统一的位置

   • 默认使用底部（ToastGravity.BOTTOM）
   • 重要提示可以使用中间（ToastGravity.CENTER）

4. 避免过度使用

   • 不要频繁显示 Toast
   • 重要操作才显示 Toast
   • 避免同时显示多个 Toast

---

8. 总结

8.1 实现的功能

本教程详细介绍了如何使用 鸿蒙化版本的 fluttertoast 替代 SnackBar 实现灵活的吐司提示，已完成的功能包括：

1. ✅ 引入三方库：添加鸿蒙化版本的 fluttertoast 依赖（br_8.2.8_ohos）
2. ✅ 创建工具类：封装 ToastUtil 提供统一接口
3. ✅ 替换 SnackBar：在所有页面中替换为 Toast
4. ✅ 多种提示类型：成功、错误、警告、信息
5. ✅ 自定义样式：位置、时长、颜色等
6. ✅ HarmonyOS 适配：使用专门针对 HarmonyOS 优化的版本
7. ✅ 最佳实践：使用建议和注意事项

8.2 核心功能

• 📍 位置控制：支持顶部、中间、底部三种位置
• ⏱️ 时长控制：短时（2秒）和长时（3.5秒）
• 🎨 样式自定义：背景色、文字颜色、字体大小
• 💡 轻量级：体积小，性能好，适合天气应用
• 🔧 使用便捷：全局调用，无需 Context
• 📱 HarmonyOS 适配：使用鸿蒙化版本（br_8.2.8_ohos），针对 HarmonyOS 平台优化
• 🌐 平台支持：专门适配 HarmonyOS/OpenHarmony 系统

8.3 使用示例总结

// ✅ 成功提示（绿色）
ToastUtil.showSuccess('操作成功');

// ❌ 错误提示（红色）
ToastUtil.showError('操作失败', duration: 3);

// ⚠️ 警告提示（橙色）
ToastUtil.showWarning('该城市已存在');

// ℹ️ 信息提示（蓝色）
ToastUtil.showInfo('请在搜索框中输入城市名称');

// 🎨 自定义提示
ToastUtil.show(
  '自定义提示',
  duration: 3,
  gravity: ToastGravity.TOP,
  backgroundColor: Colors.purple.shade600,
  textColor: Colors.white,
);

// 🚫 取消提示
ToastUtil.cancel();

8.4 优势对比

特性	SnackBar	FlutterToast（鸿蒙版）
📍 位置	仅底部	顶部/中间/底部
⏱️ 时长	固定	灵活可调
🎨 样式	有限	丰富
💡 轻量	较重	轻量
🔧 使用	需要 Context	全局调用
📱 HarmonyOS 适配	基础支持	✅ 专门优化
🌐 平台支持	多平台	HarmonyOS 优化版本

8.5 完整使用流程图

---

9. 参考资料

• 📚 fluttertoast 官方文档
• 🌐 鸿蒙化 fluttertoast 仓库
• 🎨 Flutter Toast 最佳实践
• 📱 HarmonyOS Flutter 开发指南
• 🔧 OpenHarmony SIG 项目

---

10. 功能演示流程图

🎉 祝你开发顺利！ 🚀
欢迎加入开源鸿蒙跨平台社区