使用鸿蒙化flutter_fluttertoast替换Flutter原有的SnackBar提示弹窗

📚 目录

• [1. 概述](#1. 概述)
• [2. 引入三方库](#2. 引入三方库)
• [3. 目录结构](#3. 目录结构)
• [4. 核心代码解读](#4. 核心代码解读)
• [5. 实际步骤](#5. 实际步骤)
• [6. 常见错误与解决方案](#6. 常见错误与解决方案)
• [7. 进阶功能](#7. 进阶功能)
• [8. 总结](#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 功能流程图

✅ 成功
❌ 失败
⚠️ 警告
ℹ️ 信息
📱 用户操作
操作类型
显示成功提示

绿色 Toast
显示错误提示

红色 Toast
显示警告提示

橙色 Toast
显示信息提示

蓝色 Toast
设置位置/时长/样式
显示 Toast
自动消失

---

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 工具类架构

ToastUtil工具类
showSuccess

成功提示
showError

错误提示
showWarning

警告提示
showInfo

信息提示
show

通用提示
cancel

取消提示
Fluttertoast.showToast
Fluttertoast.cancel
设置参数

位置/时长/样式

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 使用流程

📢 Fluttertoast 🛠️ ToastUtil 📱 页面 👤 用户 📢 Fluttertoast 🛠️ ToastUtil 📱 页面 👤 用户 2-3秒后自动消失 执行操作（保存/删除等） 处理操作逻辑 调用 ToastUtil.showSuccess() Fluttertoast.showToast() 显示 Toast 提示 Toast 消失 操作失败 调用 ToastUtil.showError() Fluttertoast.showToast() 显示红色错误提示

---

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 使用

✅ 成功
❌ 错误
⚠️ 警告
ℹ️ 信息
用户操作
操作结果
showSuccess

绿色 2秒
showError

红色 3秒
showWarning

橙色 2秒
showInfo

蓝色 2秒
保存成功

删除成功

切换成功
网络错误

加载失败

操作失败
城市已存在

数据过期

权限不足
功能说明

使用提示

操作指引

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 完整使用流程图

保存设置
删除城市
切换城市
添加城市
网络错误
加载失败
操作失败
城市已存在
数据过期
权限不足
功能说明
使用提示
操作指引
📱 用户操作
操作类型
ToastUtil.showSuccess

✅ 设置已保存
ToastUtil.showError

❌ 网络连接失败
ToastUtil.showWarning

⚠️ 该城市已存在
ToastUtil.showInfo

ℹ️ 请在搜索框中输入
显示 Toast
自动消失

---

9. 参考资料

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

---

10. 功能演示流程图

📢 Fluttertoast 🛠️ ToastUtil 📱 页面 👤 用户 📢 Fluttertoast 🛠️ ToastUtil 📱 页面 👤 用户 2秒后自动消失 3秒后自动消失 点击保存按钮 执行保存操作 保存成功 ToastUtil.showSuccess('已保存') Fluttertoast.showToast() 显示绿色成功提示 Toast 消失 添加已存在的城市 检查城市是否存在 城市已存在 ToastUtil.showWarning('该城市已存在') Fluttertoast.showToast() 显示橙色警告提示 网络请求失败 捕获网络错误 ToastUtil.showError('网络连接失败', duration: 3) Fluttertoast.showToast() 显示红色错误提示

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